Guidelines for Authors and Reviewers of Documents Containing YANG Data Models

Note: This ballot was opened for revision 18 and is now closed.

(Alia Atlas) Yes

Comment (2018-03-06 for -18)
No email
send info
Very clear - and glad to see the NMDA transition guidelines get published!

(Deborah Brungard) Yes

Comment (2018-03-05 for -18)
No email
send info
Thanks for doing!

(Ben Campbell) Yes

Comment (2018-03-07 for -18)
No email
send info
Thanks for this very readable and informative document. I am balloting YES, but I do have a few minor comments:

Substantive Comments:

§3, first paragraph:

Can there be a citation for internet-draft guidelines? Also, it seems odd to have a normative MUST for I-D guidelines, but the RFC guidelines are not normative?

§3.5: Is the referenced draft in the example likely to become an RFC prior to publication? As it is, the way it is referenced looks a lot like a citation, which are not recommended in an abstract.

§3.7:  The URL in the second paragraph is very dependent on the structure of the tools pages. Any reorganization of those pages is likely to break the link. I wonder if there is a way to alias that to something less brittle.

§4.8, 2nd paragraph: I’m surprised to see the WG mail list a MUST level requirement here. WGs (and their mailing lists) come and go. I think, in many cases, it would make more sense to list the IESG as the contact, at least for standards track models. (I’ve seen us do that more often lately for IANA registrations, and this seems in the same spirit.)

I can see that it might still make sense to reference the WG list in some circumstances, but MUST seems excessive.
Editorial Comments and Nits:

§3.9, last paragraph:

There are two clauses starting with “, which”, which I think are intended as restrictive clauses. Consider s/“, which”/“that”

(Benoît Claise) Yes

Warren Kumari Yes

(Terry Manderson) Yes

Comment (2018-03-06 for -18)
No email
send info
Thanks for the effort on this document!

(Alexey Melnikov) Yes

Comment (2018-03-06 for -18)
No email
send info
Thank you for a great document. Some minor comments:

3.8.  IANA Considerations Section

   In order to comply with IESG policy as set forth in, every Internet-Draft that
   is submitted to the IESG for publication MUST contain an IANA
   Considerations section.  The requirements for this section vary
   depending on what actions are required of the IANA.  If there are no
   IANA considerations applicable to the document, then the IANA
   Considerations section stating that there are no actions is removed
   by the RFC Editor before publication.

IANA's and RFC Editor opinion about empty IANA Considerations section has changed over time (and might change again), so I would not make this statement. I don't think this is necessarily the current policy. RFC Editor asks, but doesn't enforce this. So I suggest changing "is removed" to "might be removed".

[I-D.ietf-netmod-revised-datastores] - I am pretty sure that some uses of this document are normative, so you should move it to Normative References.

(Kathleen Moriarty) Yes

Comment (2018-03-06 for -18)
No email
send info
Thanks for your work on this draft and in particular Section 3.7 with the updated Security Considerations Section template and pointer to one that can change over time.

It looks like the authors may not have seen Stephen's questions from his SecDir review, please respond:

(Alissa Cooper) No Objection

(Spencer Dawkins) No Objection

(Suresh Krishnan) (was Discuss) No Objection

Comment (2018-03-13 for -19)
No email
send info
Thanks for addressing my DISCUSS and COMMENT points.

(Mirja Kühlewind) No Objection

(Eric Rescorla) No Objection

Comment (2018-03-07 for -18)
No email
send info
   normative, if the module itself is considered normative, and not an
   example module or example YANG fragment.  The use of keywords defined
   in [RFC2119] apply to YANG description statements in normative
I think you probably want to rewrite this as:

"Note that if the module itself is considered normative and not an example module or example YANG fragment, then all YANG statements..."

   o  Prefixes are never allowed for built in data types and YANG
I'm not sure I understand what this means. Is the idea that I can't use "example-import" somewhere?

   character MAY be used if the identifier represents a well-known value
   that uses these characters.
Is this text saying that only characters in these two subsets are allowed and therefore, for instance "." is forbidden

   It is RECOMMENDED that only valid YANG modules be included in
   documents, whether or not they are published yet.  This allows:
For clarify, I assume you mean "the modules are published yet"

   The NETCONF Access Control Model (NACM) [I-D.ietf-netconf-rfc6536bis]
   does not support parameter access control for RPC operations.  The
   user is given permission (or not) to invoke the RPC operation with
This might be slightly clearer if you said "parameter-based access control"

Alvaro Retana No Objection

Comment (2018-03-07 for -18)
No email
send info
(1) This sentence in the Introduction caught my attention: "This document defines a set of usage guidelines for Standards Track documents containing models."    The Abstract extends to say that "Applicable portions may be used as a basis for reviews of other YANG data model documents."  

I don't remember a non-Standards Track document off the top of my head [*], but I'm sure the guidelines apply to any IETF document containing a module.  Is that true?  

I see, for example, that in 4.1 (Module Naming Conventions) it is clear how modules published by the IETF should be named...and a note is included about what other SDOs might do.  Are there cases where the guidelines are only applicable to Standards Track documents, but would not apply to other IETF documents?

This may be a nit, but I think it is good to close this door before the justification for non-compliance starts being the Status of a document.

[*] I do remember the IESG talking about whether a document with a module for an Experimental protocol should be in the Standards Track or not.  IMHO, what matters is for the module to be used (i.e. correct, implementable, implemented, etc.) and not the status of the document it is in.

(2) The second paragraph in 2.1. (Requirements Notation) is not needed: "RFC 2119 if it were describing best current practices."  This document is now a BCP.

(Adam Roach) No Objection

Comment (2018-03-08 for -18)
No email
send info
Thanks for this document. It is well-written and I believe it will be helpful.
Comments follow.



I've reviewed a couple of YANG modules where the indentation and/or wrapping was
awkward and inconsistent. I would love to see guidance in this document that
authors be careful to run their modules through pyang (or a similar tool) to
ensure consistent formatting. It may be worthwhile to give an example of the
exact commandline invocation of pyang to achieve a formatting that is consistent
with existing published modules.



>  YANG data model modules under review are likely to be contained in
>  Internet-Drafts.  All guidelines for Internet-Draft authors MUST be
>  followed.  The RFC Editor provides guidelines for authors of RFCs,
>  which are first published as Internet-Drafts.  These guidelines
>  should be followed and are defined in [RFC7322] and updated in
>  [RFC7841] and "RFC Document Style" [RFC-STYLE].

Maybe include a pointer to draft-flanagan-7322bis also, as this document is in
the process of being revised.



>  Example YANG modules and example YANG fragments MUST NOT contain any
>  normative text, including any reserved words from [RFC2119]

Please clarify that this means only all-uppercase reserved words.



>  If there are no
>  IANA considerations applicable to the document, then the IANA
>  Considerations section stating that there are no actions is removed
>  by the RFC Editor before publication.

I believe that the current state of play is that removal is left to the authors'
discretion, and that the IANA has a weak preference for leaving in sections that
say "No actions are requested of IANA." This may change. Rather than try to
capture the (potentially changing) state of play, my suggestion is to
remove the text I quote above.



>  Each specification that defines one or more modules SHOULD contain
>  usage examples, either throughout the document or in an appendix.

Many of the YANG documents I've reviewed over the past year have contained
examples that show only IPv4 addresses. The IAB has issued guidance that
examples in standards track documents use either a mix of IPv4 and IPv6
addresses or IPv6 addresses exclusively (see
<>). This section would do
authors and reviewers a great favor by reiterating or pointing to this guidance.



>  The following typedef from [RFC6991] demonstrates the proper use of
>  the "pattern" statement:
>      typedef ipv4-address-no-zone {
>        type inet:ipv4-address {
>          pattern '[0-9\.]*';
>        }
>        ...
>      }

By contrast, RFC 6021 has a somewhat more complex production:

       +  '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])'
       + '(%[\p{N}\p{L}]+)?';

Is there any consensus on how complex the pattern validation should be? I've
seen some YANG modules with patterns that occupied more than half a page. Is
that encouraged, discouraged, or neither? It seems some guidance on this
specific issue would be useful, as the currently published modules appear to be
all over the map on this topic.



>              Braden, R., Ginoza, S., and A. Hagens, "RFC Document
>              Style", September 2009,
>              <>.

This URL returns a 404.