[RTG-DIR] RtgDir Early review: draft-ietf-i2rs-yang-l3-topology

[Michael Richardson <[e-mail]>]

Hello

I have been selected to do a routing directorate “early” review of this draft. 
https://tools.ietf.org/html/draft-ietf-i2rs-yang-l3-topology-10

The routing directorate will, on request from the working group chair,
perform an “early” review of a draft before it is submitted for publication
to the IESG. The early review can be performed at any time during the draft’s
lifetime as a working group document. The purpose of the early review depends
on the stage that the document has reached.

I believe that this is case 3, the document is neither recently adopted
nor is it in WGLC.   The request is for a sanity check.

For more information about the Routing Directorate, please see
​http://trac.tools.ietf.org/area/rtg/trac/wiki/RtgDir 

Document: draft-ietf-i2rs-yang-l3-topology
Reviewer: Michael Richardson
Review Date: 2017-07-18
Intended Status: Standards Track

Summary: 

I have some minor concerns about this document that I think should be
resolved before it is submitted to the IESG.

Comments:

I found the document clear and well written.
You told me at the beginning that:
   For this purpose,
   example models are introduced that cover IS-IS [RFC1195] and OSPF
   [RFC2328].

Yet I still felt sad when I got to spot where it said:
   Accordingly, the module is not delimited with
   CODE BEGINS and CODE ENDS

I think that the point of the OSPF and ISIS examples was to show, via a kind
of running-code of YANG, that the specification was complete enough that
it could be used.   Maybe this could be clarified better, the examples occupy
a large portion of the document.   I'm not sure so much of the document
should be devoted to non-normative examples.

I don't think I agree with ommitting the CODE BEGINS, because someone reading
this might well want to run the examples through their yang validator.
   
It was nice to have the mini-tutorial on YANG, but I don't think it needed
to be repeated.

I found parts of the YANG to be silly, such as:

        leaf-list flag {
           type node-flag-type;
           description
             "Node flags";
         }

Does YANG require that actually have to have a description?
It is meaningless as above.  What are node flags?   I suggest that the
description should be far more useful.  Consider someone seeing the data
decoded into a database, but has this description.

Another example of useless descriptions:
        case asbr {
           leaf asbr {
             type empty;
             description
               "The node is ASBR";
           }

okay, fair enough, it is an example, so don't work too hard here.

As examples, I thought that maybe I'd see this module instantiated into
JSON or XML and to see an example of a data set that describes a real-life
router's interfaces.  I did not see such a thing.
Perhaps there are feelings about whether or not a YANG model should include
concrete code or not, I'm not sure.

I didn't understand why:
  Appendix A.  Companion YANG model for non-NMDA compliant implementations
was included.  Probably I don't know enough about NMDA.

Nits:

I found no trivial nits.

-- 
Michael Richardson <[e-mail]>, Sandelman Software Works
 -= IPv6 IoT consulting =-