YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)
draft-ietf-netmod-yang-13

[Ballot comment]
1. [Addressed in -13.]

2. [Addressed in -13.]

3. [Redacted.]

4. [Explained by authors.]

5. [Addressed in -13.]

6. [Addressed in -13.]

7. [Addressed in -13.]

8. [Explained by authors.]

9. In Section 13, the "unknown-element" referred to under Section 8.3.1 is not defined.

[Ballot discuss]
1. [Addressed in -13.]

2. [Text OK as-is.]

3. [Addressed via RFC Editor note.]

[4. does not exist.]

5. [Addressed in -13.]

6. [Addressed in -13.]

7. [Addressed in -13.]

8. [Addressed in -13.]

[Ballot comment]
Formerly a DISCUSS item:


1)
5.1.  Modules and Submodules

  The names of all standard modules and submodules MUST be unique.
  Developers of enterprise modules are RECOMMENDED to choose names for

(Similar text in several other sections, e.g. 7.1, 7.2)
Why RECOMMENDED and not a MUST here?
I.e. what is a good reason to violate this and to choose conflicting names?

  their modules that will have a low probability of colliding with
  standard or other enterprise modules, e.g., by using the enterprise
  or organization name as a prefix for the module name.

6)
7.10.2.  XML Mapping Rules

  An anyxml node is encoded as an XML element.  The element's local
  name is the anyxml's identifier, and its namespace is the module's
  XML namespace (see Section 7.1.3).  The value of the anyxml node is
  encoded as XML content of this element.

and

7.10.4.  Usage Example

  Given the following anyxml statement:

    anyxml data;

  The following are two valid encodings of the same anyxml value:

   
     
        1
     
   

DISCUSS DISCUSS: I don't see where the payload ("...") is coming from.
<>

15)
7.19.3.  The description Statement

  The "description" statement takes as an argument a string which
  contains a high-level textual description of this definition.

As this field is human readable, I think BCP 18 (RFC 2277), Section 4.2 applies. So this would need ability to tag language of the description.
(YIN should be using xml:lang attribute.)

You can find a bit more information on

---------------------------------------

9.4.  The string Built-in Type

  The string built-in type represents human readable strings in YANG.
  Legal characters are tab, carriage return, line feed, and the legal
  characters of Unicode and ISO/IEC 10646 [ISO.10646]:

    ;; any Unicode character, excluding the surrogate blocks,
    ;; FFFE, and FFFF.

This comment is not quite correct - it doesn't mention excluded ASCII control characters (at least some of them).

[Ballot comment]
1. [Addressed in -13.]

2. [Addressed in -13.]

3. [Redacted.]

4. [Explained by authors.]

5. [Addressed in -13.]

6. [Addressed in -13.]

7. [Addressed in -13.]

8. [Explained by authors.]

9. In Section 13, the "unknown-element" referred to under Section 8.3.1 is not defined.

[Ballot discuss]
1. [Addressed in -13.]

2. [Text OK as-is.]

3. In Section 7.19.3, the "description" statement contains a high-level textual description of this definition, which appears to be human-readable. However, no language tagging is provided in accordance with RFC 2277.

[4. does not exist.]

5. [Addressed in -13.]

6. [Addressed in -13.]

7. [Addressed in -13.]

8. [Addressed in -13.]

[Ballot comment]
I have cleared - I believe that this issue can be more appropriately addressed in yang-usage.

[The issue is how to identify elements that are required to be supported.  That is, which elements
can not be deviations (especially for omitted...)]

[Ballot discuss]
[Sorry about the late discuss text.  I encountered a tracker bug that prevented entry before the telechat.]

(1) I believe that Robert’s comment on deviation merits a discuss because of interoperability and
conformance concerns.  I would like to understand the intent of the wg, since this seems to
create a large loophole.

(2) I believe this document should note that specifications using yang can indicate that a deviation of "not supported" is not allowed for a particular object.  This feature should be used to ensure that a minimum level of interoperability is achieved.

[Ballot comment]
Formerly a DISCUSS item:

15)
7.19.3.  The description Statement

  The "description" statement takes as an argument a string which
  contains a high-level textual description of this definition.

As this field is human readable, I think BCP 18 (RFC 2277), Section 4.2 applies. So this would need ability to tag language of the description.
(YIN should be using xml:lang attribute.)

You can find a bit more information on

1)
5.1.  Modules and Submodules

  The names of all standard modules and submodules MUST be unique.
  Developers of enterprise modules are RECOMMENDED to choose names for

(Similar text in several other sections, e.g. 7.1, 7.2)
Why RECOMMENDED and not a MUST here?
I.e. what is a good reason to violate this and to choose conflicting names?

  their modules that will have a low probability of colliding with
  standard or other enterprise modules, e.g., by using the enterprise
  or organization name as a prefix for the module name.

---------------------------------------

7.1.6.  The include Statement

  When the optional "revision-date" is present, the specified revision
  of the submodule is included in the module.

What would happen if a specific revision is included, but the submodule doesn't contain any revision?
I assume that would be an error, but I am wondering if it is worth calling this out explicitly.

(Similar comment for "import".)

  Otherwise, it is
  undefined which revision of the submodule is included.

7.5.3.  The must Statement

  The "must" statement, which is optional, takes as an argument a
  string which contains an XPath expression.

I think this needs a reference to a section defining XPath expressions.

7.10.  The anyxml Statement

  An anyxml node cannot be augmented.

A reference to where augmented is defined would be useful. Or instead say something like:

  An anyxml node cannot be augmented using the ... statement.

7.18.1.  The feature Statement

  The "feature" statement is used to define a mechanism by which
  portions of the schema are marked as conditional.  A feature name is
  defined that can later be referenced using the "if-feature" statement
  (see Section 7.18.2).  Schema nodes tagged with a feature are ignored
  unless the device supports the given feature.

Ignored by whom?

  If a feature is dependent on any other features (i.e., the feature
  has one or more "if-feature" sub-statements), then all of features it
  depends on MUST also be implemented by the device.

I think you meant to say that if one of "if-feature" statements of a feature is not implemented by a device, then the device can't implement the feature.

9.4.4.  The length Statement

  The "length" statement, which is an optional substatement to the
  "type" statement, takes as an argument a length expression string.
  It is used to restrict the built-in type "string", or types derived
  from "string".

  A "length" statement restricts the number of characters in the

number of *Unicode* characters

  string.

In Section 12:

  ;;
  ;; RFC 4234 core rules.
  ;;

s/4234/5234

[Ballot discuss]
This is a well written document, a pleasure to read. Thank you.
However I did find some things that I would like to discuss before recommending approval of this document:

2)
5.2.  File Layout

  YANG modules and submodules are typically stored in files, one module
  or submodule per file.  The name of the file SHOULD be of the form:

    module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )

Does this mean that 2 new MIME media types should be registered?
<>

3)
6.1.3.  Quoting

  If the double quoted string contains a line break followed by space
  or tab characters which are used to indent the text according to the

Does a tab character correspond to a fixed number of spaces? If yes, how many?

  layout in the YANG file, this leading whitespace is stripped from the
  string, up to and including the column of the double quote character,
  or to the first non-whitespace character, whichever occurs first.

4)
7.1.  The module Statement

  A module SHOULD have the following layout:

Why SHOULD here? What is the significance of the recommended layout and how does it benefit an implementation?
Parsers can't rely on this SHOULD, so they will have to implement any allowed ordering.

(Similar text in Section 7.2).

6)
7.10.2.  XML Mapping Rules

  An anyxml node is encoded as an XML element.  The element's local
  name is the anyxml's identifier, and its namespace is the module's
  XML namespace (see Section 7.1.3).  The value of the anyxml node is
  encoded as XML content of this element.

and

7.10.4.  Usage Example

  Given the following anyxml statement:

    anyxml data;

  The following are two valid encodings of the same anyxml value:

   
     
        1
     
   

DISCUSS DISCUSS: I don't see where the payload ("...") is coming from.
<>

7)
7.19.2.  The status Statement

  If a definition is "current", it MUST NOT reference a "deprecated" or
  "obsolete" definition within the same module.

  If a definition is "deprecated", it MUST NOT reference an "obsolete"
  definition within the same module.

What does it mean to reference a definition?

Can you show an example demonstrating use of this statement?

9)
9.6.4.  The enum Statement

  The "enum" statement, which is a substatement to the "type"
  statement, MUST be present if the type is "enumeration".  It is
  repeatedly used to specify each assigned name of an enumeration type.
  It takes as an argument a string which is the assigned name.  The
  string MUST NOT be empty and MUST NOT have any leading or trailing
  whitespace characters.  The use of control codes SHOULD be avoided.

How do you define a "control code"?

10)

9.8.2.  Lexicographic Representation

  Binary values are encoded with the base64 encoding scheme [RFC4648].

You need to specify the alphabet used (there are 2 different ones defined in RFC 4648).

12)
14.  IANA Considerations

  o  a reference to the (sub)module's documentation (the RFC number)

[...]

  The module name prefix 'ietf-' is reserved for IETF stream documents
  [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
  stream documents.  Modules published in other RFC streams must have a
  similar suitable prefix.  The prefix 'iana-' is reserved for modules
  maintained by IANA.

How can "iana-" be used if all modules require an RFC?

13)
9.4.  The string Built-in Type

  The string built-in type represents human readable strings in YANG.
  Legal characters are tab, carriage return, line feed, and the legal
  characters of Unicode and ISO/IEC 10646 [ISO.10646]:

    ;; any Unicode character, excluding the surrogate blocks,
    ;; FFFE, and FFFF.

(Comment) This comment is not quite correct - it doesn't mention exclusded ASCII control characters (at least some of them).

    string = *char
    char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD /
            %x10000-10FFFF

Surrogate pairs are between U+D800 and U+DFFF. They are not excluded above.

14)
  [ISO.10646]
              International Organization for Standardization,
              "Information Technology - Universal Multiple-octet coded
              Character Set (UCS) - Part 1: Architecture and Basic
              Multilingual Plane", ISO Standard 10646-1, May 1993.

This reference is way too old, you should reference something more recent (e.g. dated 2003). Additionally, Part 1 only covers 16 bit Unicode codepoints, while you want the whole 24 bits. So you should be referencing ISO.10646, not just part 1.

[Ballot comment]
Consider deleting the sentence "A list is similar to a
table where each list entry is a row in the table." The
document defines a list. A table is not defined in this
document. Appealing to a common-sense notion of what a
table might be is not much more useful than just appealing
to the common-sense notion of a list, and the statement
might introduce confusion if the reader makes assumptions
about tables that you didn't intend.

[Ballot discuss]
I have a few points to discuss before recommending approval
of this document.

1) The definition of line folding in quotes (6.1.3) is
  ambiguous if tabs don't represent a pre-defined fixed
  number of columns.

2) I'm not finding an explicit definition of the semantics
  of merge that results in the move behavior described in
  the example at the end of section 7.8.7.  What text
  informs an implementation to do the right thing if the
  example isn't available? (I may just be missing it).

3) Is it the case that  can only operate on
  lists that have config true; in their definition? If so,
  does the document say that somewhere? If not, then the
  operations will only work on lists that have a defined
  key and that constraint should be called out.

4) Given the canonical form and lexicographic representation
  defined in section 9.5.1, is it defined what a server
  should do if it sees a boolean represented as "TRUE"
  instead of "true"?

5) (Moved this to a discuss based on telechat conversation
  Tim plans to enter support when the tracker works for him)
The deviation mechanism seems too flexible to me. As
defined, someone could claim to implement standard X, but
use deviation statements to completely replace the contents
of X with something proprietary. Discussions with Dan
indicate that this was explicitly considered by the group
and deemed acceptable.  Is there any text that could be
added to more strongly discourage this kind of abuse of the
mechanism? In particular, what would help a client
implementor defend against a statement like
"No, the spec says I can deviate this way, and you're at
non-interoperability-fault for not conforming to my
deviations" when the deviations are more extreme than the
simple policy and limit deviations shown as examples?

[Ballot discuss]
[Updated.  I added #4.]

#1) Sec 4.1: The text says:

These constraints are enforceable by either the client or the server,
and valid content must abide by them.

I think the must needs to be MUST?

#2) Sec 8.3: The text says:

For configuration data, there are three windows when constraints can
be enforced

Is this suggesting that constraints might not be applied?  That is, why isn't the "can" a "MUST":

For configuration data, there are three windows when constraints MUST
be enforced

#3) The deviate statement scares me a bit.  The text says:

Device deviations are strongly discouraged and SHOULD only be used as
a last resort.  Telling the application how a device fails to follow
a standard is no substitute for implementing the standard correctly.

Why not a MUST instead of the SHOULD?  It seems like this is the way I'd get out of doing what I'm supposed to.

#4) The author agreed to incorporate some text as a result of the SECDIR review.  Awaiting either an RFC editor with the text or a new version before clearing.  Text is included below:

YANG parsers need to be robust with respect to malformed documents.
Reading malformed documents from unknown or untrusted sources could
result in an attacker gaining privileges of the user running the YANG
parser.  In an extreme situation, the entire machine could be
compromised.

[Ballot discuss]
#1) Sec 4.1: The text says:

These constraints are enforceable by either the client or the server,
and valid content must abide by them.

I think the must needs to be MUST?

#2) Sec 8.3: The text says:

For configuration data, there are three windows when constraints can
be enforced

Is this suggesting that constraints might not be applied?  That is, why isn't the "can" a "MUST":

For configuration data, there are three windows when constraints MUST
be enforced

#3) The deviate statement scares me a bit.  The text says:

Device deviations are strongly discouraged and SHOULD only be used as
a last resort.  Telling the application how a device fails to follow
a standard is no substitute for implementing the standard correctly.

Why not a MUST instead of the SHOULD?  It seems like this is the way I'd get out of doing what I'm supposed to.

[Ballot discuss]
#1) Sec 4.1: The text says:

These constraints are enforceable by either the client or the server,
and valid content must abide by them.

I think the must needs to be MUST?

#2) Sec 8.3: The text says:

For configuration data, there are three windows when constraints can
be enforced

Is this suggesting that constraints might not be applied?  That is, why isn't the "can" a "MUST":

For configuration data, there are three windows when constraints MUST
be enforced

#3) The deviate statement scares me a bit.  The text says:

Device deviations are strongly discouraged and SHOULD only be used as
a last resort.  Telling the application how a device fails to follow
a standard is no substitute for implementing the standard correctly.

Why not a MUST instead of the SHOULD?  It seems like this is the way I'd get out of doing what I'm supposed to.

[Ballot comment]
1. Throughout the document, change "lexicographic" and "lexicographical" to "lexical" ("lexicographic" means "related to the practice of compiling dictionaries" whereas "lexical" means "related to a vocabulary").

2. Please expand the acronym PDU (protocol data unit) on first use in Section 4.2.7. (By the way, this term does not seem to be defined in RFC 4741 or any other core NETCONF specification, nor even in RFC 2578, so an explanation might be in order here for the benefit of readers not familiar with NETCONF or SNMP.)

3. In Section 7.1.8, it appears that the "contact" statement has no internal structure and is free-form text. Does this make automated processing more difficult?

4. In Section 8.3.1 (Payload Parsing), the following unmatched constraints both produce an "unknown-element" error-tag...

  o  data for a node tagged with "if-feature" is present, and the
      feature is not supported by the device

  o  data for a node tagged with "when" is present, and the "when"
      condition evaluates to "false"

It would seem preferable to differentiate between these two case, for example by defining a "feature-not-implemented" error-tag for the first case.

5. Section 10 has the following sentence:

  Furthermore, the "namespace" statement MUST NOT be changed,
  since all XML elements are encoded in the namespace.

Please change "encoded in" to "qualified by". A namespace does not provide an encoding.

You might also be consistent about "qualified by", such as here:

  o  If the argument is encoded as an element, it is placed to the same
      namespace as its parent keyword element.

That is, change "placed to" to "qualified by". Perhaps search through the document for other instances (I have not performed a thorough search).

6. Similarly, the term "encoding" is used when talking about how to represent data in XML. As just one example:

  The argument of a YANG statement is encoded in YIN either as an XML
  attribute or a subelement of the keyword element.  Table 1 defines
  the encoding for the set of YANG keywords.

I would suggest changing "encoded" to "represented" and "encoding" to "mapping" (or choose other words that you find suitable).

7. Editorial nit, change "less" to "fewer" here:

  o  A "min-elements" statement may be removed, or changed to require
      less elements.

8. In Section 12, the ABNF for "identifier" does not programmatically restrict an entity from specifying an identifier that starts with 'xml' (it is restricted by means of a human-readable comment). It's not clear whether a programmatic restriction is truly necessary, however.

  identifier-arg      = identifier

  ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l'))
  identifier          = (ALPHA / "_")
                        *(ALPHA / DIGIT / "_" / "-" / ".")

9. In Section 13, the "unknown-element" referred to under Section 8.3.1 is not defined.

[Ballot discuss]
1. In Section 7.1.4 and elsewhere, the meaning of the prefix statement is unclear:

  The "prefix" statement is used to define the prefix associated with
  the module and its namespace.

Does this mean that this prefix is reserved? How shall applications handle conflicts among prefix names asserted by different modules? Does the IANA perhaps need to maintain a registry of prefix names? Do prefix names apply to module names (e.g., in accordance with the "orgprefix-modname" structure that appears to be assumed in this specification)?

2. In Section 7.1.9, the "revision" statement has the structure "YYYY-MM-DD"; this prevents an entity from releasing multiple versions on the same day, although it's not clear if that is serious issue (e.g., an entity might find a significant error or security problem with a released revision and might need to generate a new revision immediately thereafter).

3. In Section 7.19.3, the "description" statement contains a high-level textual description of this definition, which appears to be human-readable. However, no language tagging is provided in accordance with RFC 2277.

5. In Section 9, some of the built-in types (e.g., various integers) can have multiple lexical representations. This is justified as follows:

  The lexicographic representation of a value of a certain type is used
  in the NETCONF PDUs, and when specifying default values and numerical
  ranges in YANG modules.

And also justified on the grounds of "convenience" in Section 9.2.1.

What is this "convenience"? Is there really a strong reason to have multiple lexical representations? Is it a MUST for all implementations to support all lexical representations? If so, doesn't that increase code complexity? If not, doesn't that harm interoperability?

6. No motivation is provided for the alternate "YIN" syntax. Why is this here? Does it harm interoperability to have more than one syntax? (Perhaps not, given that there is a one-to-one mapping between them.) Does an implementation need to support both YANG and YIN?

7. Protocol versioning is good and seems to be represented here in the namespace names "urn:ietf:params:xml:ns:yang:1" and "urn:ietf:params:xml:ns:yang:yin:1". However, no guidance is provided about possible versioning of the data format, under what circumstances the version number would need to change, how older versions and newer versions can interoperate, etc.

8. The IANA considerations seem to request that the IANA shall enforce the structure "orgprefix-modname", but that structure is not required anywhere else in the document (although it is suggested).

  The module name prefix 'ietf-' is reserved for IETF stream documents
  [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
  stream documents.  Modules published in other RFC streams must have a
  similar suitable prefix. 

Furthermore, it is not clear what it means for the IANA to maintain a module.

  The prefix 'iana-' is reserved for modules
  maintained by IANA.

[Ballot comment]
1. Throughout the document, change "lexicographic" and "lexicographical" to "lexical" ("lexicographic" means "related to the practice of compiling dictionaries" whereas "lexical" means "related to a vocabulary").

2. Please expand the acronym PDU (protocol data unit) on first use in Section 4.2.7. (By the way, this term does not seem to be defined in RFC 4741 or any other core NETCONF specification, nor even in RFC 2578, so an explanation might be in order here for the benefit of readers not familiar with NETCONF or SNMP.)

3. In Section 7.1.8, it appears that the "contact" statement has no internal structure and is free-form text. Does this make automated processing more difficult?

4. In Section 8.3.1 (Payload Parsing), the following unmatched constraints both produce an "unknown-element" error-tag...

  o  data for a node tagged with "if-feature" is present, and the
      feature is not supported by the device

  o  data for a node tagged with "when" is present, and the "when"
      condition evaluates to "false"

It would seem preferable to differentiate between these two case, for example by defining a "feature-not-implemented" error-tag for the first case.

5. Section 10 has the following sentence:

  Furthermore, the "namespace" statement MUST NOT be changed,
  since all XML elements are encoded in the namespace.

Please change "encoded in" to "qualified by". A namespace does not provide an encoding.

You might also be consistent about "qualified by", such as here:

  o  If the argument is encoded as an element, it is placed to the same
      namespace as its parent keyword element.

That is, change "placed to" to "qualified by". Perhaps search through the document for other instances (I have not performed a thorough search).

6. Similarly, the term "encoding" is used when talking about how to represent data in XML. As just one example:

  The argument of a YANG statement is encoded in YIN either as an XML
  attribute or a subelement of the keyword element.  Table 1 defines
  the encoding for the set of YANG keywords.

I would suggest changing "encoded" to "represented" and "encoding" to "mapping" (or choose other words that you find suitable).

7. Editorial nit, change "less" to "fewer" here:

  o  A "min-elements" statement may be removed, or changed to require
      less elements.

8. In Section 12, the ABNF for "identifier" does not programmatically restrict an entity from specifying an identifier that starts with 'xml' (it is restricted by means of a human-readable comment). It's not clear whether a programmatic restriction is truly necessary, however.

  identifier-arg      = identifier

  ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l'))
  identifier          = (ALPHA / "_")
                        *(ALPHA / DIGIT / "_" / "-" / ".")

9. In Section 13, the "unknown-element" referred to under Section 8.3.1 is not defined.

[Ballot discuss]
1. In Section 7.1.4 and elsewhere, the meaning of the prefix statement is unclear:

  The "prefix" statement is used to define the prefix associated with
  the module and its namespace.

Does this mean that this prefix is reserved? How shall applications handle conflicts among prefix names asserted by different modules? Does the IANA perhaps need to maintain a registry of prefix names? Do prefix names apply to module names (e.g., in accordance with the "orgprefix-modname" structure that appears to be assumed in this specification)?

2. In Section 7.1.9, the "revision" statement has the structure "YYYY-MM-DD"; this prevents an entity from releasing multiple versions on the same day, although it's not clear if that is serious issue (e.g., an entity might find a significant error or security problem with a released revision and might need to generate a new revision immediately thereafter).

3. In Section 7.19.3, the "description" statement contains a high-level textual description of this definition, which appears to be human-readable. However, no language tagging is provided in accordance with RFC 2277.

5. In Section 9, some of the built-in types (e.g., various integers) can have multiple lexical representations. This is justified as follows:

  The lexicographic representation of a value of a certain type is used
  in the NETCONF PDUs, and when specifying default values and numerical
  ranges in YANG modules.

And also justified on the grounds of "convenience" in Section 9.2.1.

What is this "convenience"? Is there really a strong reason to have multiple lexical representations? Is it a MUST for all implementations to support all lexical representations? If so, doesn't that increase code complexity? If not, doesn't that harm interoperability?

6. No motivation is provided for the alternate "YIN" syntax. Why is this here? Does it harm interoperability to have more than one syntax? (Perhaps not, given that there is a one-to-one mapping between them.) Does an implementation need to support both YANG and YIN?

7. Protocol versioning is good and seems to be represented here in the namespace names "urn:ietf:params:xml:ns:yang:1" and "urn:ietf:params:xml:ns:yang:yin:1". However, no guidance is provided about possible versioning of the data format, under what circumstances the version number would need to change, how older versions and newer versions can interoperate, etc.

8. The IANA considerations seem to request that the IANA shall enforce the structure "orgprefix-modname", but that structure is not required anywhere else in the document (although it is suggested).

  The module name prefix 'ietf-' is reserved for IETF stream documents
  [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
  stream documents.  Modules published in other RFC streams must have a
  similar suitable prefix. 

Furthermore, it is not clear what it means for the IANA to maintain a module.

  The prefix 'iana-' is reserved for modules
  maintained by IANA.

[Ballot comment]
1. Throughout the document, change "lexicographic" and "lexicographical" to "lexical" ("lexicographic" means "related to the practice of compiling dictionaries" whereas "lexical" means "related to a vocabulary").

2. Please expand the acronym PDU (protocol data unit) on first use. (By the way, this term does not seem to be defined in RFC 4741 or any other core NETCONF specification, nor even in RFC 2578, so an explanation might be in order here for the benefit of readers not familiar with NETCONF or SNMP.)

3. In Section 8.3.1 (Payload Parsing), the following unmatched constraints both produce an "unknown-element" error-tag...

  o  data for a node tagged with "if-feature" is present, and the
      feature is not supported by the device

  o  data for a node tagged with "when" is present, and the "when"
      condition evaluates to "false"

It would seem preferable to differentiate between these two case, for example by defining a "feature-not-implemented" error-tag for the first case.

4. Section 10 has the following sentence:

  Furthermore, the "namespace" statement MUST NOT be changed,
  since all XML elements are encoded in the namespace.

Please change "encoded in" to "qualified by". A namespace does not provide an encoding.

You might also be consistent about "qualified by", such as here:

  o  If the argument is encoded as an element, it is placed to the same
      namespace as its parent keyword element.

That is, change "placed to" to "qualified by". Perhaps search through the document for other instances (I have not performed a thorough search).

5. Similarly, the term "encoding" is used when talking about how to represent data in XML. As just one example:

  The argument of a YANG statement is encoded in YIN either as an XML
  attribute or a subelement of the keyword element.  Table 1 defines
  the encoding for the set of YANG keywords.

I would suggest changing "encoded" to "represented" and "encoding" to "mapping" (or choose other words that you find suitable).

6. Editorial nit, change "less" to "fewer" here:

  o  A "min-elements" statement may be removed, or changed to require
      less elements.

7. In Section 12, the ABNF for "identifier" does not programmatically restrict an entity from specifying an identifier that starts with 'xml' (it is restricted by means of a human-readable comment). It's not clear whether a programmatic restriction is truly necessary, however.

  identifier-arg      = identifier

  ;; An identifier MUST NOT start with (('X'|'x') ('M'|'m') ('L'|'l'))
  identifier          = (ALPHA / "_")
                        *(ALPHA / DIGIT / "_" / "-" / ".")

8. In Section 13, the "unknown-element" referred to under Section 8.3.1 is not defined.

[Ballot discuss]
1. In Section 9, some of the built-in types (e.g., various integers) can have multiple lexical representations. This is justified as follows:

  The lexicographic representation of a value of a certain type is used
  in the NETCONF PDUs, and when specifying default values and numerical
  ranges in YANG modules.

And also justified on the grounds of "convenience" in Section 9.2.1.

What is this "convenience"? Is there really a strong reason to have multiple lexical representations? Is it a MUST for all implementations to support all lexical representations? If so, doesn't that increase code complexity? If not, doesn't that harm interoperability?

2. No motivation is provided for the alternate "YIN" syntax. Why is this here? Does it harm interoperability to have more than one syntax? (Perhaps not, given that there is a one-to-one mapping between them.) Does an implementation need to support both YANG and YIN?

3. Protocol versioning is good and seems to be represented here in the namespace names "urn:ietf:params:xml:ns:yang:1" and "urn:ietf:params:xml:ns:yang:yin:1". However, no guidance is provided about possible versioning of the data format, under what circumstances the version number would need to change, how older versions and newer versions can interoperate, etc.

[Ballot comment]
Formerly a DISCUSS item:

1)
5.1.  Modules and Submodules

  The names of all standard modules and submodules MUST be unique.
  Developers of enterprise modules are RECOMMENDED to choose names for

(Similar text in several other sections, e.g. 7.1, 7.2)
Why RECOMMENDED and not a MUST here?
I.e. what is a good reason to violate this and to choose conflicting names?

  their modules that will have a low probability of colliding with
  standard or other enterprise modules, e.g., by using the enterprise
  or organization name as a prefix for the module name.

---------------------------------------

7.1.6.  The include Statement

  When the optional "revision-date" is present, the specified revision
  of the submodule is included in the module.

What would happen if a specific revision is included, but the submodule doesn't contain any revision?
I assume that would be an error, but I am wondering if it is worth calling this out explicitly.

(Similar comment for "import".)

  Otherwise, it is
  undefined which revision of the submodule is included.

7.5.3.  The must Statement

  The "must" statement, which is optional, takes as an argument a
  string which contains an XPath expression.

I think this needs a reference to a section defining XPath expressions.

7.10.  The anyxml Statement

  An anyxml node cannot be augmented.

A reference to where augmented is defined would be useful. Or instead say something like:

  An anyxml node cannot be augmented using the ... statement.

7.18.1.  The feature Statement

  The "feature" statement is used to define a mechanism by which
  portions of the schema are marked as conditional.  A feature name is
  defined that can later be referenced using the "if-feature" statement
  (see Section 7.18.2).  Schema nodes tagged with a feature are ignored
  unless the device supports the given feature.

Ignored by whom?

  If a feature is dependent on any other features (i.e., the feature
  has one or more "if-feature" sub-statements), then all of features it
  depends on MUST also be implemented by the device.

I think you meant to say that if one of "if-feature" statements of a feature is not implemented by a device, then the device can't implement the feature.

9.4.4.  The length Statement

  The "length" statement, which is an optional substatement to the
  "type" statement, takes as an argument a length expression string.
  It is used to restrict the built-in type "string", or types derived
  from "string".

  A "length" statement restricts the number of characters in the

number of *Unicode* characters

  string.

In Section 12:

  ;;
  ;; RFC 4234 core rules.
  ;;

s/4234/5234

[Ballot discuss]
This is a well written document, a pleasure to read. Thank you.
However I did find some things that I would like to discuss before recommending approval of this document:

2)
5.2.  File Layout

  YANG modules and submodules are typically stored in files, one module
  or submodule per file.  The name of the file SHOULD be of the form:

    module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )

Does this mean that 2 new MIME media types should be registered?
<>

3)
6.1.3.  Quoting

  If the double quoted string contains a line break followed by space
  or tab characters which are used to indent the text according to the

Does a tab character correspond to a fixed number of spaces? If yes, how many?

  layout in the YANG file, this leading whitespace is stripped from the
  string, up to and including the column of the double quote character,
  or to the first non-whitespace character, whichever occurs first.

4)
7.1.  The module Statement

  A module SHOULD have the following layout:

Why SHOULD here? What is the significance of the recommended layout and how does it benefit an implementation?
Parsers can't rely on this SHOULD, so they will have to implement any allowed ordering.

(Similar text in Section 7.2).

6)
7.10.2.  XML Mapping Rules

  An anyxml node is encoded as an XML element.  The element's local
  name is the anyxml's identifier, and its namespace is the module's
  XML namespace (see Section 7.1.3).  The value of the anyxml node is
  encoded as XML content of this element.

and

7.10.4.  Usage Example

  Given the following anyxml statement:

    anyxml data;

  The following are two valid encodings of the same anyxml value:

   
     
        1
     
   

DISCUSS DISCUSS: I don't see where the payload ("...") is coming from.
<>

7)
7.19.2.  The status Statement

  If a definition is "current", it MUST NOT reference a "deprecated" or
  "obsolete" definition within the same module.

  If a definition is "deprecated", it MUST NOT reference an "obsolete"
  definition within the same module.

What does it mean to reference a definition?

Can you show an example demonstrating use of this statement?

9)
9.6.4.  The enum Statement

  The "enum" statement, which is a substatement to the "type"
  statement, MUST be present if the type is "enumeration".  It is
  repeatedly used to specify each assigned name of an enumeration type.
  It takes as an argument a string which is the assigned name.  The
  string MUST NOT be empty and MUST NOT have any leading or trailing
  whitespace characters.  The use of control codes SHOULD be avoided.

How do you define a "control code"?

10)

9.8.2.  Lexicographic Representation

  Binary values are encoded with the base64 encoding scheme [RFC4648].

You need to specify the alphabet used (there are 2 different ones defined in RFC 4648).

12)
14.  IANA Considerations

  o  a reference to the (sub)module's documentation (the RFC number)

[...]

  The module name prefix 'ietf-' is reserved for IETF stream documents
  [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
  stream documents.  Modules published in other RFC streams must have a
  similar suitable prefix.  The prefix 'iana-' is reserved for modules
  maintained by IANA.

How can "iana-" be used if all modules require an RFC?

13)
9.4.  The string Built-in Type

  The string built-in type represents human readable strings in YANG.
  Legal characters are tab, carriage return, line feed, and the legal
  characters of Unicode and ISO/IEC 10646 [ISO.10646]:

    ;; any Unicode character, excluding the surrogate blocks,
    ;; FFFE, and FFFF.

(Comment) This comment is not quite correct - it doesn't mention exclusded ASCII control characters (at least some of them).

    string = *char
    char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD /
            %x10000-10FFFF

Surrogate pairs are between U+D800 and U+DFFF. They are not excluded above.

14)
  [ISO.10646]
              International Organization for Standardization,
              "Information Technology - Universal Multiple-octet coded
              Character Set (UCS) - Part 1: Architecture and Basic
              Multilingual Plane", ISO Standard 10646-1, May 1993.

This reference is way too old, you should reference something more recent (e.g. dated 2003). Additionally, Part 1 only covers 16 bit Unicode codepoints, while you want the whole 24 bits. So you should be referencing ISO.10646, not just part 1.

15)
7.19.3.  The description Statement

  The "description" statement takes as an argument a string which
  contains a high-level textual description of this definition.

As this field is human readable, I think BCP 18 (RFC 2277), Section 4.2 applies. So this would need ability to tag language of the description.
(YIN should be using xml:lang attribute.)

You can find a bit more information on

[Ballot comment]
Formerly a DISCUSS item:

1)
5.1.  Modules and Submodules

  The names of all standard modules and submodules MUST be unique.
  Developers of enterprise modules are RECOMMENDED to choose names for

(Similar text in several other sections, e.g. 7.1, 7.2)
Why RECOMMENDED and not a MUST here?
I.e. what is a good reason to violate this and to choose conflicting names?

  their modules that will have a low probability of colliding with
  standard or other enterprise modules, e.g., by using the enterprise
  or organization name as a prefix for the module name.

---------------------------------------

7.1.6.  The include Statement

  When the optional "revision-date" is present, the specified revision
  of the submodule is included in the module.

What would happen if a specific revision is included, but the submodule doesn't contain any revision?
I assume that would be an error, but I am wondering if it is worth calling this out explicitly.

(Similar comment for "import".)

  Otherwise, it is
  undefined which revision of the submodule is included.

7.5.3.  The must Statement

  The "must" statement, which is optional, takes as an argument a
  string which contains an XPath expression.

I think this needs a reference to a section defining XPath expressions.

7.10.  The anyxml Statement

  An anyxml node cannot be augmented.

A reference to where augmented is defined would be useful. Or instead say something like:

  An anyxml node cannot be augmented using the ... statement.

7.18.1.  The feature Statement

  The "feature" statement is used to define a mechanism by which
  portions of the schema are marked as conditional.  A feature name is
  defined that can later be referenced using the "if-feature" statement
  (see Section 7.18.2).  Schema nodes tagged with a feature are ignored
  unless the device supports the given feature.

Ignored by whom?

  If a feature is dependent on any other features (i.e., the feature
  has one or more "if-feature" sub-statements), then all of features it
  depends on MUST also be implemented by the device.

I think you meant to say that if one of "if-feature" statements of a feature is not implemented by a device, then the device can't implement the feature.

9.4.4.  The length Statement

  The "length" statement, which is an optional substatement to the
  "type" statement, takes as an argument a length expression string.
  It is used to restrict the built-in type "string", or types derived
  from "string".

  A "length" statement restricts the number of characters in the

number of *Unicode* characters

  string.

In Section 12:

  ;;
  ;; RFC 4234 core rules.
  ;;

s/4234/5234

[Ballot discuss]
[I reviewed the whole document, except for the ABNF section. I haven't reviewed reply to my original DUSCUSS yet. Note that I also have a list of other possible comments I need to check, so expect an update.]

This is a well written document, a pleasure to read. Thank you.
However I did find some things that I would like to discuss before recommending approval of this document:

2)
5.2.  File Layout

  YANG modules and submodules are typically stored in files, one module
  or submodule per file.  The name of the file SHOULD be of the form:

    module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )

Does this mean that 2 new MIME media types should be registered?
<>

3)
6.1.3.  Quoting

  If the double quoted string contains a line break followed by space
  or tab characters which are used to indent the text according to the

Does a tab character correspond to a fixed number of spaces? If yes, how many?

  layout in the YANG file, this leading whitespace is stripped from the
  string, up to and including the column of the double quote character,
  or to the first non-whitespace character, whichever occurs first.

4)
7.1.  The module Statement

  A module SHOULD have the following layout:

Why SHOULD here? What is the significance of the recommended layout and how does it benefit an implementation?
Parsers can't rely on this SHOULD, so they will have to implement any allowed ordering.

(Similar text in Section 7.2).

6)
7.10.2.  XML Mapping Rules

  An anyxml node is encoded as an XML element.  The element's local
  name is the anyxml's identifier, and its namespace is the module's
  XML namespace (see Section 7.1.3).  The value of the anyxml node is
  encoded as XML content of this element.

and

7.10.4.  Usage Example

  Given the following anyxml statement:

    anyxml data;

  The following are two valid encodings of the same anyxml value:

   
     
        1
     
   

I don't see where the payload ("...") is coming from.

7)
7.19.2.  The status Statement

  If a definition is "current", it MUST NOT reference a "deprecated" or
  "obsolete" definition within the same module.

  If a definition is "deprecated", it MUST NOT reference an "obsolete"
  definition within the same module.

What does it mean to reference a definition?

Can you show an example demonstrating use of this statement?

9)
9.6.4.  The enum Statement

  The "enum" statement, which is a substatement to the "type"
  statement, MUST be present if the type is "enumeration".  It is
  repeatedly used to specify each assigned name of an enumeration type.
  It takes as an argument a string which is the assigned name.  The
  string MUST NOT be empty and MUST NOT have any leading or trailing
  whitespace characters.  The use of control codes SHOULD be avoided.

How do you define a "control code"?

10)

9.8.2.  Lexicographic Representation

  Binary values are encoded with the base64 encoding scheme [RFC4648].

You need to specify the alphabet used (there are 2 different ones defined in RFC 4648).

12)
14.  IANA Considerations

  o  a reference to the (sub)module's documentation (the RFC number)

[...]

  The module name prefix 'ietf-' is reserved for IETF stream documents
  [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
  stream documents.  Modules published in other RFC streams must have a
  similar suitable prefix.  The prefix 'iana-' is reserved for modules
  maintained by IANA.

How can "iana-" be used if all modules require an RFC?

13)
9.4.  The string Built-in Type

  The string built-in type represents human readable strings in YANG.
  Legal characters are tab, carriage return, line feed, and the legal
  characters of Unicode and ISO/IEC 10646 [ISO.10646]:

    ;; any Unicode character, excluding the surrogate blocks,
    ;; FFFE, and FFFF.

(Comment) This comment is not quite correct - it doesn't mention exclusded ASCII control characters (at least some of them).

    string = *char
    char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD /
            %x10000-10FFFF

Surrogate pairs are between U+D800 and U+DFFF. They are not excluded above.

14)
  [ISO.10646]
              International Organization for Standardization,
              "Information Technology - Universal Multiple-octet coded
              Character Set (UCS) - Part 1: Architecture and Basic
              Multilingual Plane", ISO Standard 10646-1, May 1993.

This reference is way too old, you should reference something more recent (e.g. dated 2003). Additionally, Part 1 only covers 16 bit Unicode codepoints, while you want the whole 24 bits. So you should be referencing ISO.10646, not just part 1.

15)
7.19.3.  The description Statement

  The "description" statement takes as an argument a string which
  contains a high-level textual description of this definition.

As this field is human readable, I think BCP 18 (RFC 2277), Section 4.2 applies. So this would need ability to tag language of the description.
(YIN should be using xml:lang attribute.)

You can find a bit more information on

[Ballot comment]
1. Throughout the document, change "lexicographic" and "lexicographical" to "lexical" ("lexicographic" means "related to the practice of compiling dictionaries" whereas "lexical" means "related to a vocabulary").

2. Please expand the acronym PDU (protocol data unit) on first use. (By the way, this term does not seem to be defined in RFC 4741 or any other core NETCONF specification, nor even in RFC 2578, so an explanation might be in order here for the benefit of readers not familiar with NETCONF or SNMP.)

3. In Section 8.3.1 (Payload Parsing), the following unmatched constraints both produce an "unknown-element" error-tag...

  o  data for a node tagged with "if-feature" is present, and the
      feature is not supported by the device

  o  data for a node tagged with "when" is present, and the "when"
      condition evaluates to "false"

It would seem preferable to differentiate between these two case, for example by defining a "feature-not-implemented" error-tag for the first case.

[Ballot discuss]
1. In Section 9, some of the built-in types (e.g., various integers) can have multiple lexical representations. This is justified as follows:

  The lexicographic representation of a value of a certain type is used
  in the NETCONF PDUs, and when specifying default values and numerical
  ranges in YANG modules.

And also justified on the grounds of "convenience" in Section 9.2.1.

What is this "convenience"? Is there really a strong reason to have multiple lexical representations? Is it a MUST for all implementations to support all lexical representations? If so, doesn't that increase code complexity? If not, doesn't that harm interoperability?

[Ballot comment]
Formerly a DISCUSS item:

1)
5.1.  Modules and Submodules

  The names of all standard modules and submodules MUST be unique.
  Developers of enterprise modules are RECOMMENDED to choose names for

(Similar text in several other sections, e.g. 7.1, 7.2)
Why RECOMMENDED and not a MUST here?
I.e. what is a good reason to violate this and to choose conflicting names?

  their modules that will have a low probability of colliding with
  standard or other enterprise modules, e.g., by using the enterprise
  or organization name as a prefix for the module name.

---------------------------------------

7.1.6.  The include Statement

  When the optional "revision-date" is present, the specified revision
  of the submodule is included in the module.

What would happen if a specific revision is included, but the submodule doesn't contain any revision?
I assume that would be an error, but I am wondering if it is worth calling this out explicitly.

(Similar comment for "import".)

  Otherwise, it is
  undefined which revision of the submodule is included.

7.5.3.  The must Statement

  The "must" statement, which is optional, takes as an argument a
  string which contains an XPath expression.

I think this needs a reference to a section defining XPath expressions.

7.10.  The anyxml Statement

  An anyxml node cannot be augmented.

A reference to where augmented is defined would be useful. Or instead say something like:

  An anyxml node cannot be augmented using the ... statement.

7.18.1.  The feature Statement

  The "feature" statement is used to define a mechanism by which
  portions of the schema are marked as conditional.  A feature name is
  defined that can later be referenced using the "if-feature" statement
  (see Section 7.18.2).  Schema nodes tagged with a feature are ignored
  unless the device supports the given feature.

Does this mean that nodes with if-feature are also ignored (can be omitted) in YIN representation?

  If a feature is dependent on any other features (i.e., the feature
  has one or more "if-feature" sub-statements), then all of features it
  depends on MUST also be implemented by the device.

I think you meant to say that if one of "if-feature" statements of a feature is not implemented by a device, then the device can't implement the feature.

9.4.4.  The length Statement

  The "length" statement, which is an optional substatement to the
  "type" statement, takes as an argument a length expression string.
  It is used to restrict the built-in type "string", or types derived
  from "string".

  A "length" statement restricts the number of characters in the

number of *Unicode* characters

  string.

In Section 12:

  ;;
  ;; RFC 4234 core rules.
  ;;

s/4234/5234

[Ballot discuss]
[I reviewed the whole document, except for the ABNF section. I haven't reviewed reply to my original DUSCUSS yet. Note that I also have a list of other possible comments I need to check, so expect an update.]

This is a well written document, a pleasure to read. Thank you.
However I did find some things that I would like to discuss before recommending approval of this document:

2)
5.2.  File Layout

  YANG modules and submodules are typically stored in files, one module
  or submodule per file.  The name of the file SHOULD be of the form:

    module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )

Does this mean that 2 new MIME media types should be registered?
<>

3)
6.1.3.  Quoting

  If the double quoted string contains a line break followed by space
  or tab characters which are used to indent the text according to the

Does a tab character correspond to a fixed number of spaces? If yes, how many?

  layout in the YANG file, this leading whitespace is stripped from the
  string, up to and including the column of the double quote character,
  or to the first non-whitespace character, whichever occurs first.

4)
7.1.  The module Statement

  A module SHOULD have the following layout:

Why SHOULD here? What is the significance of the recommended layout and how does it benefit an implementation?
Parsers can't rely on this SHOULD, so they will have to implement any allowed ordering.

(Similar text in Section 7.2).

6)
7.10.2.  XML Mapping Rules

  An anyxml node is encoded as an XML element.  The element's local
  name is the anyxml's identifier, and its namespace is the module's
  XML namespace (see Section 7.1.3).  The value of the anyxml node is
  encoded as XML content of this element.

and

7.10.4.  Usage Example

  Given the following anyxml statement:

    anyxml data;

  The following are two valid encodings of the same anyxml value:

   
     
        1
     
   

I don't see where the payload ("...") is specified in the example. It looks that either your example is incorrect, or the description of anyxml is incorrect. Of course I can be wrong as well.

7)
7.19.2.  The status Statement

  If a definition is "current", it MUST NOT reference a "deprecated" or
  "obsolete" definition within the same module.

  If a definition is "deprecated", it MUST NOT reference an "obsolete"
  definition within the same module.

What does it mean to reference a definition?

Can you show an example demonstrating use of this statement?

9)
9.6.4.  The enum Statement

  The "enum" statement, which is a substatement to the "type"
  statement, MUST be present if the type is "enumeration".  It is
  repeatedly used to specify each assigned name of an enumeration type.
  It takes as an argument a string which is the assigned name.  The
  string MUST NOT be empty and MUST NOT have any leading or trailing
  whitespace characters.  The use of control codes SHOULD be avoided.

How do you define a "control code"?

10)

9.8.2.  Lexicographic Representation

  Binary values are encoded with the base64 encoding scheme [RFC4648].

You need to specify the alphabet used (there are 2 different ones defined in RFC 4648).

12)
14.  IANA Considerations

  o  a reference to the (sub)module's documentation (the RFC number)

[...]

  The module name prefix 'ietf-' is reserved for IETF stream documents
  [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
  stream documents.  Modules published in other RFC streams must have a
  similar suitable prefix.  The prefix 'iana-' is reserved for modules
  maintained by IANA.

How can "iana-" be used if all modules require an RFC?

13)
9.4.  The string Built-in Type

  The string built-in type represents human readable strings in YANG.
  Legal characters are tab, carriage return, line feed, and the legal
  characters of Unicode and ISO/IEC 10646 [ISO.10646]:

    ;; any Unicode character, excluding the surrogate blocks,
    ;; FFFE, and FFFF.

(Comment) This comment is not quite correct - it doesn't mention exclusded ASCII control characters (at least some of them).

    string = *char
    char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD /
            %x10000-10FFFF

Surrogate pairs are between U+D800 and U+DFFF. They are not excluded above.

14)
  [ISO.10646]
              International Organization for Standardization,
              "Information Technology - Universal Multiple-octet coded
              Character Set (UCS) - Part 1: Architecture and Basic
              Multilingual Plane", ISO Standard 10646-1, May 1993.

This reference is way too old, you should reference something more recent (e.g. dated 2003). Additionally, Part 1 only covers 16 bit Unicode codepoints, while you want the whole 24 bits. So you should be referencing ISO.10646, not just part 1.

15)
7.19.3.  The description Statement

  The "description" statement takes as an argument a string which
  contains a high-level textual description of this definition.

As this field is human readable, I think BCP 18 (RFC 2277), Section 4.2 applies. So this would need ability to tag language of the description.
(YIN should be using xml:lang attribute.)

You can find a bit more information on

[Ballot comment]
1. Throughout the document, change "lexicographic" and "lexicographical" to "lexical" ("lexicographic" means "related to the practice of compiling dictionaries" whereas "lexical" means "related to a vocabulary").

2. Please expand the acronym PDU (protocol data unit) on first use. (By the way, this term does not seem to be defined in RFC 4741 or any other core NETCONF specification, nor even in RFC 2578, so an explanation might be in order here for the benefit of readers not familiar with NETCONF or SNMP.)

3. In Section 8.3.1 (Payload Parsing), the following unmatched constraints both produce an "unknown-element" error-tag...

  o  data for a node tagged with "if-feature" is present, and the
      feature is not supported by the device

  o  data for a node tagged with "when" is present, and the "when"
      condition evaluates to "false"

It would seem preferable to differentiate between these two case, for example by defining a "feature-not-implemented" error-tag for the first case.

[Ballot discuss]
1. In Section 9, most of the built-in types can have different lexical representations. This is justified as follows:

  The lexicographic representation of a value of a certain type is used
  in the NETCONF PDUs, and when specifying default values and numerical
  ranges in YANG modules.

Is there a strong reason to have different lexical representations? Is it a MUST for all implementations to support all lexical representations? If so, doesn't that increase code complexity? If not, doesn't that harm interoperability?

[Ballot comment]
1. Throughout the document, change "lexicographic" and "lexicographical" to "lexical" ("lexicographic" means "related to the practice of compiling dictionaries" whereas "lexical" means "related to a vocabulary").

2. Please expand the acronym PDU (protocol data unit) on first use. (By the way, this term does not seem to be defined in RFC 4741 or any other core NETCONF specification, nor even in RFC 2578, so an explanation might be in order here for the benefit of readers not familiar with NETCONF or SNMP.)

3. In Section 8.3.1 (Payload Parsing), the following unmatched constraints both produce an "unknown-element" error-tag...

  o  data for a node tagged with "if-feature" is present, and the
      feature is not supported by the device

  o  data for a node tagged with "when" is present, and the "when"
      condition evaluates to "false"

It would seem preferable to differentiate between these two case, for example by defining a "feature-not-implemented" error-tag for the first case.

4. In Section 9, most of the built-in types can have different lexical representations. This is justified as follows:

  The lexicographic representation of a value of a certain type is used
  in the NETCONF PDUs, and when specifying default values and numerical
  ranges in YANG modules.

Is there a strong reason to have different lexical representations? Is it a MUST for all implementations to support all lexical representations? If so, doesn't that increase code complexity? If not, doesn't that harm interoperability?

[Ballot comment]
The deviation mechanism seems too flexible to me. As
defined, someone could claim to implement standard X, but
use deviation statements to completely replace the contents
of X with something proprietary. Discussions with Dan
indicate that this was explicitly considered by the group
and deemed acceptable.  Is there any text that could be
added to more strongly discourage this kind of abuse of the
mechanism? In particular, what would help a client
implementor defend against a statement like
"No, the spec says I can deviate this way, and you're at
non-interoperability-fault for not conforming to my
deviations" when the deviations are more extreme than the
simple policy and limit deviations shown as examples?

Consider deleting the sentence "A list is similar to a
table where each list entry is a row in the table." The
document defines a list. A table is not defined in this
document. Appealing to a common-sense notion of what a
table might be is not much more useful than just appealing
to the common-sense notion of a list, and the statement
might introduce confusion if the reader makes assumptions
about tables that you didn't intend.

[Ballot discuss]
I have a few points to discuss before recommending approval
of this document.

1) The definition of line folding in quotes (6.1.3) is
  ambiguous if tabs don't represent a pre-defined fixed
  number of columns.

2) I'm not finding an explicit definition of the semantics
  of merge that results in the move behavior described in
  the example at the end of section 7.8.7.  What text
  informs an implementation to do the right thing if the
  example isn't available? (I may just be missing it).

3) Is it the case that  can only operate on
  lists that have config true; in their definition? If so,
  does the document say that somewhere? If not, then the
  operations will only work on lists that have a defined
  key and that constraint should be called out.

4) Given the canonical form and lexicographic representation
  defined in section 9.5.1, is it defined what a server
  should do if it sees a boolean represented as "TRUE"
  instead of "true"?

[Ballot comment]
Formerly a DISCUSS item:

2)
5.2.  File Layout

  YANG modules and submodules are typically stored in files, one module
  or submodule per file.  The name of the file SHOULD be of the form:

    module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )

Does this mean that 2 new MIME media types should be registered?
If yes, I can help you create the registration templates.

---------------------------------------

7.1.6.  The include Statement

  When the optional "revision-date" is present, the specified revision
  of the submodule is included in the module.

What would happen if a specific revision is included, but the submodule doesn't contain any revision?
I assume that would be an error, but I am wondering if it is worth calling this out explicitly.

(Similar comment for "import".)

  Otherwise, it is
  undefined which revision of the submodule is included.

7.5.3.  The must Statement

  The "must" statement, which is optional, takes as an argument a
  string which contains an XPath expression.

I think this needs a reference to a section defining XPath expressions.

7.10.  The anyxml Statement

  An anyxml node cannot be augmented.

A reference to where augmented is defined would be useful. Or instead say something like:

  An anyxml node cannot be augmented using the ... statement.

7.18.1.  The feature Statement

  The "feature" statement is used to define a mechanism by which
  portions of the schema are marked as conditional.  A feature name is
  defined that can later be referenced using the "if-feature" statement
  (see Section 7.18.2).  Schema nodes tagged with a feature are ignored
  unless the device supports the given feature.

Does this mean that nodes with if-feature are also ignored (can be omitted) in YIN representation?

  If a feature is dependent on any other features (i.e., the feature
  has one or more "if-feature" sub-statements), then all of features it
  depends on MUST also be implemented by the device.

I think you meant to say that if one of "if-feature" statements of a feature is not implemented by a device, then the device can't implement the feature.

9.4.4.  The length Statement

  The "length" statement, which is an optional substatement to the
  "type" statement, takes as an argument a length expression string.
  It is used to restrict the built-in type "string", or types derived
  from "string".

  A "length" statement restricts the number of characters in the

number of *Unicode* characters

  string.

In Section 12:

  ;;
  ;; RFC 4234 core rules.
  ;;

s/4234/5234

[Ballot discuss]
[I reviewed the whole document, except for the ABNF section. I haven't reviewed reply to my original DUSCUSS yet. Note that I also have a list of other possible comments I need to check, so expect an update.]

This is a well written document, a pleasure to read. Thank you.
However I did find some things that I would like to discuss before recommending approval of this document:

1)
5.1.  Modules and Submodules

  The names of all standard modules and submodules MUST be unique.
  Developers of enterprise modules are RECOMMENDED to choose names for

(Similar text in several other sections, e.g. 7.1, 7.2)
Why RECOMMENDED and not a MUST here?
I.e. what is a good reason to violate this and to choose conflicting names?

  their modules that will have a low probability of colliding with
  standard or other enterprise modules, e.g., by using the enterprise
  or organization name as a prefix for the module name.

3)
6.1.3.  Quoting

  If the double quoted string contains a line break followed by space
  or tab characters which are used to indent the text according to the

Does a tab character correspond to a fixed number of spaces? If yes, how many?

  layout in the YANG file, this leading whitespace is stripped from the
  string, up to and including the column of the double quote character,
  or to the first non-whitespace character, whichever occurs first.

4)
7.1.  The module Statement

  A module SHOULD have the following layout:

Why SHOULD here? What is the significance of the recommended layout and how does it benefit an implementation?
Parsers can't rely on this SHOULD, so they will have to implement any allowed ordering.

(Similar text in Section 7.2).

5)
7.7.1.  Ordering

  YANG supports two styles for ordering the entries within lists and
  leaf-lists.  In many lists, the order of list entries does not impact
  the implementation of the list's configuration, and the device is
  free to sort the list entries in any reasonable order.  The
  "description" string for the list may suggest an order.

Are you sure you meant "description" here?

  YANG calls
  this style of list "system ordered" and they are indicated with the
  statement "ordered-by system".

6)
7.10.2.  XML Mapping Rules

  An anyxml node is encoded as an XML element.  The element's local
  name is the anyxml's identifier, and its namespace is the module's
  XML namespace (see Section 7.1.3).  The value of the anyxml node is
  encoded as XML content of this element.

and

7.10.4.  Usage Example

  Given the following anyxml statement:

    anyxml data;

  The following are two valid encodings of the same anyxml value:

   
     
        1
     
   

I don't see where the payload ("...") is specified in the example. It looks that either your example is incorrect, or the description of anyxml is incorrect. Of course I can be wrong as well.

7)
7.19.2.  The status Statement

  If a definition is "current", it MUST NOT reference a "deprecated" or
  "obsolete" definition within the same module.

  If a definition is "deprecated", it MUST NOT reference an "obsolete"
  definition within the same module.

What does it mean to reference a definition?

Can you show an example demonstrating use of this statement?

8)
7.19.4.  The reference Statement

  The "reference" statement takes as an argument a string which is used
  to specify a textual cross-reference to an external document, either
  another module which defines related management information, or a
  document which provides additional information relevant to this
  definition.

What do you call a "reference" here? Is a URI a reference?

9)
9.6.4.  The enum Statement

  The "enum" statement, which is a substatement to the "type"
  statement, MUST be present if the type is "enumeration".  It is
  repeatedly used to specify each assigned name of an enumeration type.
  It takes as an argument a string which is the assigned name.  The
  string MUST NOT be empty and MUST NOT have any leading or trailing
  whitespace characters.  The use of control codes SHOULD be avoided.

How do you define a "control code"?

10)

9.8.2.  Lexicographic Representation

  Binary values are encoded with the base64 encoding scheme [RFC4648].

You need to specify the alphabet used (there are 2 different ones defined in RFC 4648).

12)
14.  IANA Considerations

  o  a reference to the (sub)module's documentation (the RFC number)

[...]

  The module name prefix 'ietf-' is reserved for IETF stream documents
  [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
  stream documents.  Modules published in other RFC streams must have a
  similar suitable prefix.  The prefix 'iana-' is reserved for modules
  maintained by IANA.

How can "iana-" be used if all modules require an RFC?

13)
9.4.  The string Built-in Type

  The string built-in type represents human readable strings in YANG.
  Legal characters are tab, carriage return, line feed, and the legal
  characters of Unicode and ISO/IEC 10646 [ISO.10646]:

    ;; any Unicode character, excluding the surrogate blocks,
    ;; FFFE, and FFFF.

(Comment) This comment is not quite correct - it doesn't mention exclusded ASCII control characters (at least some of them).

    string = *char
    char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD /
            %x10000-10FFFF

Surrogate pairs are between U+D800 and U+DFFF. They are not excluded above.

14)
  [ISO.10646]
              International Organization for Standardization,
              "Information Technology - Universal Multiple-octet coded
              Character Set (UCS) - Part 1: Architecture and Basic
              Multilingual Plane", ISO Standard 10646-1, May 1993.

This reference is way too old, you should reference something more recent (e.g. dated 2003). Additionally, Part 1 only covers 16 bit Unicode codepoints, while you want the whole 24 bits. So you should be referencing ISO.10646, not just part 1.

15)
7.19.3.  The description Statement

  The "description" statement takes as an argument a string which
  contains a high-level textual description of this definition.

As this field is human readable, I think BCP 18 (RFC 2277), Section 4.2 applies. So this would need ability to tag language of the description.
(YIN should be using xml:lang attribute.)

You can find a bit more information on

[Ballot comment]
Formerly a DISCUSS item:

2)
5.2.  File Layout

  YANG modules and submodules are typically stored in files, one module
  or submodule per file.  The name of the file SHOULD be of the form:

    module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )

Does this mean that 2 new MIME media types should be registered?
If yes, I can help you create the registration templates.

---------------------------------------

7.1.6.  The include Statement

  When the optional "revision-date" is present, the specified revision
  of the submodule is included in the module.

What would happen if a specific revision is included, but the submodule doesn't contain any revision?
I assume that would be an error, but I am wondering if it is worth calling this out explicitly.

(Similar comment for "import".)

  Otherwise, it is
  undefined which revision of the submodule is included.

7.5.3.  The must Statement

  The "must" statement, which is optional, takes as an argument a
  string which contains an XPath expression.

I think this needs a reference to a section defining XPath expressions.

7.10.  The anyxml Statement

  An anyxml node cannot be augmented.

A reference to where augmented is defined would be useful. Or instead say something like:

  An anyxml node cannot be augmented using the ... statement.

7.18.1.  The feature Statement

  The "feature" statement is used to define a mechanism by which
  portions of the schema are marked as conditional.  A feature name is
  defined that can later be referenced using the "if-feature" statement
  (see Section 7.18.2).  Schema nodes tagged with a feature are ignored
  unless the device supports the given feature.

Does this mean that nodes with if-feature are also ignored (can be omitted) in YIN representation?

  If a feature is dependent on any other features (i.e., the feature
  has one or more "if-feature" sub-statements), then all of features it
  depends on MUST also be implemented by the device.

I think you meant to say that if one of "if-feature" statements of a feature is not implemented by a device, then the device can't implement the feature.

9.4.4.  The length Statement

  The "length" statement, which is an optional substatement to the
  "type" statement, takes as an argument a length expression string.
  It is used to restrict the built-in type "string", or types derived
  from "string".

  A "length" statement restricts the number of characters in the

number of *Unicode* characters

  string.

In Section 12:

  ;;
  ;; RFC 4234 core rules.
  ;;

s/4234/5234

[Ballot discuss]
[I reviewed the whole document, except for the ABNF section. I haven't reviewed reply to my original DUSCUSS yet. Note that I also have a list of other possible comments I need to check, so expect an update.]

This is a well written document, a pleasure to read. Thank you.
However I did find some things that I would like to discuss before recommending approval of this document:

1)
5.1.  Modules and Submodules

  The names of all standard modules and submodules MUST be unique.
  Developers of enterprise modules are RECOMMENDED to choose names for

(Similar text in several other sections, e.g. 7.1, 7.2)
Why RECOMMENDED and not a MUST here?
I.e. what is a good reason to violate this and to choose conflicting names?

  their modules that will have a low probability of colliding with
  standard or other enterprise modules, e.g., by using the enterprise
  or organization name as a prefix for the module name.

3)
6.1.3.  Quoting

  If the double quoted string contains a line break followed by space
  or tab characters which are used to indent the text according to the

Does a tab character correspond to a fixed number of spaces? If yes, how many?

  layout in the YANG file, this leading whitespace is stripped from the
  string, up to and including the column of the double quote character,
  or to the first non-whitespace character, whichever occurs first.

4)
7.1.  The module Statement

  A module SHOULD have the following layout:

Why SHOULD here? What is the significance of the recommended layout and how does it benefit an implementation?
Parsers can't rely on this SHOULD, so they will have to implement any allowed ordering.

(Similar text in Section 7.2).

5)
7.7.1.  Ordering

  YANG supports two styles for ordering the entries within lists and
  leaf-lists.  In many lists, the order of list entries does not impact
  the implementation of the list's configuration, and the device is
  free to sort the list entries in any reasonable order.  The
  "description" string for the list may suggest an order.

Are you sure you meant "description" here?

  YANG calls
  this style of list "system ordered" and they are indicated with the
  statement "ordered-by system".

6)
7.10.2.  XML Mapping Rules

  An anyxml node is encoded as an XML element.  The element's local
  name is the anyxml's identifier, and its namespace is the module's
  XML namespace (see Section 7.1.3).  The value of the anyxml node is
  encoded as XML content of this element.

and

7.10.4.  Usage Example

  Given the following anyxml statement:

    anyxml data;

  The following are two valid encodings of the same anyxml value:

   
     
        1
     
   

I don't see where the payload ("...") is specified in the example. It looks that either your example is incorrect, or the description of anyxml is incorrect. Of course I can be wrong as well.

7)
7.19.2.  The status Statement

  If a definition is "current", it MUST NOT reference a "deprecated" or
  "obsolete" definition within the same module.

  If a definition is "deprecated", it MUST NOT reference an "obsolete"
  definition within the same module.

What does it mean to reference a definition?

Can you show an example demonstrating use of this statement?

8)
7.19.4.  The reference Statement

  The "reference" statement takes as an argument a string which is used
  to specify a textual cross-reference to an external document, either
  another module which defines related management information, or a
  document which provides additional information relevant to this
  definition.

What do you call a "reference" here? Is a URI a reference?

9)
9.6.4.  The enum Statement

  The "enum" statement, which is a substatement to the "type"
  statement, MUST be present if the type is "enumeration".  It is
  repeatedly used to specify each assigned name of an enumeration type.
  It takes as an argument a string which is the assigned name.  The
  string MUST NOT be empty and MUST NOT have any leading or trailing
  whitespace characters.  The use of control codes SHOULD be avoided.

How do you define a "control code"?

10)

9.8.2.  Lexicographic Representation

  Binary values are encoded with the base64 encoding scheme [RFC4648].

You need to specify the alphabet used (there are 2 different ones defined in RFC 4648).

12)
14.  IANA Considerations

  o  a reference to the (sub)module's documentation (the RFC number)

[...]

  The module name prefix 'ietf-' is reserved for IETF stream documents
  [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
  stream documents.  Modules published in other RFC streams must have a
  similar suitable prefix.  The prefix 'iana-' is reserved for modules
  maintained by IANA.

How can "iana-" be used if all modules require an RFC?

13)
9.4.  The string Built-in Type

  The string built-in type represents human readable strings in YANG.
  Legal characters are tab, carriage return, line feed, and the legal
  characters of Unicode and ISO/IEC 10646 [ISO.10646]:

    ;; any Unicode character, excluding the surrogate blocks,
    ;; FFFE, and FFFF.

(Comment) This comment is not quite correct - it doesn't mention exclusded ASCII control characters (at least some of them).

    string = *char
    char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD /
            %x10000-10FFFF

Surrogate pairs are between U+D800 and U+DFFF. They are not excluded above.

[Ballot comment]
4.2.2.1.  Leaf Nodes

  A leaf node contains simple data like an integer or a string.  It has
  exactly one value of a particular type, and no child nodes.

  YANG Example:

      leaf host-name {
          type string;
          description "Hostname for this system";
      }

  NETCONF XML Example:

      my.example.com

This and other examples got me confused. First, the document says that 1 representation can be converted to the other one without loss of data, but  then the example doesn't show "description".


7.1.6.  The include Statement

  When the optional "revision-date" is present, the specified revision
  of the submodule is included in the module.

What would happen if a specific revision is included, but the submodule doesn't contain any revision?
I assume that would be an error, but I am wondering if it is worth calling this out explicitly.

(Similar comment for "import".)

  Otherwise, it is
  undefined which revision of the submodule is included.

-------New comments----------

7.5.3.  The must Statement

  The "must" statement, which is optional, takes as an argument a
  string which contains an XPath expression.

I think this needs a reference to a section defining XPath expressions.

7.10.  The anyxml Statement

  An anyxml node cannot be augmented.

A reference to where augmented is defined would be useful. Or instead say something like:

  An anyxml node cannot be augmented using the ... statement.

7.18.1.  The feature Statement

  The "feature" statement is used to define a mechanism by which
  portions of the schema are marked as conditional.  A feature name is
  defined that can later be referenced using the "if-feature" statement
  (see Section 7.18.2).  Schema nodes tagged with a feature are ignored
  unless the device supports the given feature.

Does this mean that nodes with if-feature are also ignored (can be omitted) in YIN representation?

  If a feature is dependent on any other features (i.e., the feature
  has one or more "if-feature" sub-statements), then all of features it
  depends on MUST also be implemented by the device.

I think you meant to say that if one of "if-feature" statements of a feature is not implemented by a device, then the device can't implement the feature.

9.4.4.  The length Statement

  The "length" statement, which is an optional substatement to the
  "type" statement, takes as an argument a length expression string.
  It is used to restrict the built-in type "string", or types derived
  from "string".

  A "length" statement restricts the number of characters in the

number of *Unicode* characters

  string.

In Section 12:

  ;;
  ;; RFC 4234 core rules.
  ;;

s/4234/5234

[Ballot discuss]
[I reviewed the whole document, except for the ABNF section. I haven't reviewed reply to my original DUSCUSS yet. Note that I also have a list of other possible comments I need to check, so expect an update.]

This is a well written document, a pleasure to read. Thank you.
However I did find some things that I would like to discuss before recommending approval of this document:

1)
5.1.  Modules and Submodules

  The names of all standard modules and submodules MUST be unique.
  Developers of enterprise modules are RECOMMENDED to choose names for

(Similar text in several other sections, e.g. 7.1, 7.2)
Why RECOMMENDED and not a MUST here?
I.e. what is a good reason to violate this and to choose conflicting names?

  their modules that will have a low probability of colliding with
  standard or other enterprise modules, e.g., by using the enterprise
  or organization name as a prefix for the module name.

2)
5.2.  File Layout

  YANG modules and submodules are typically stored in files, one module
  or submodule per file.  The name of the file SHOULD be of the form:

    module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )

Does this mean that 2 new MIME media types should be registered?
If yes, I can help you create the registration templates.

3)
6.1.3.  Quoting

  If the double quoted string contains a line break followed by space
  or tab characters which are used to indent the text according to the

Does a tab character correspond to a fixed number of spaces? If yes, how many?

  layout in the YANG file, this leading whitespace is stripped from the
  string, up to and including the column of the double quote character,
  or to the first non-whitespace character, whichever occurs first.

4)
7.1.  The module Statement

  A module SHOULD have the following layout:

Why SHOULD here? What is the significance of the recommended layout and how does it benefit an implementation?
Parsers can't rely on this SHOULD, so they will have to implement any allowed ordering.

(Similar text in Section 7.2).

-----------New text--------------

5)
7.7.1.  Ordering

  YANG supports two styles for ordering the entries within lists and
  leaf-lists.  In many lists, the order of list entries does not impact
  the implementation of the list's configuration, and the device is
  free to sort the list entries in any reasonable order.  The
  "description" string for the list may suggest an order.

Are you sure you meant "description" here?

  YANG calls
  this style of list "system ordered" and they are indicated with the
  statement "ordered-by system".

6)
7.10.2.  XML Mapping Rules

  An anyxml node is encoded as an XML element.  The element's local
  name is the anyxml's identifier, and its namespace is the module's
  XML namespace (see Section 7.1.3).  The value of the anyxml node is
  encoded as XML content of this element.

and

7.10.4.  Usage Example

  Given the following anyxml statement:

    anyxml data;

  The following are two valid encodings of the same anyxml value:

   
     
        1
     
   

I don't see where the payload ("...") is specified in the example. It looks that either your example is incorrect, or the description of anyxml is incorrect. Of course I can be wrong as well.

7)
7.19.2.  The status Statement

  If a definition is "current", it MUST NOT reference a "deprecated" or
  "obsolete" definition within the same module.

  If a definition is "deprecated", it MUST NOT reference an "obsolete"
  definition within the same module.

What does it mean to reference a definition?

Can you show an example demonstrating use of this statement?

8)
7.19.4.  The reference Statement

  The "reference" statement takes as an argument a string which is used
  to specify a textual cross-reference to an external document, either
  another module which defines related management information, or a
  document which provides additional information relevant to this
  definition.

What do you call a "reference" here? Is a URI a reference?

9)
9.6.4.  The enum Statement

  The "enum" statement, which is a substatement to the "type"
  statement, MUST be present if the type is "enumeration".  It is
  repeatedly used to specify each assigned name of an enumeration type.
  It takes as an argument a string which is the assigned name.  The
  string MUST NOT be empty and MUST NOT have any leading or trailing
  whitespace characters.  The use of control codes SHOULD be avoided.

How do you define a "control code"?

10)

9.8.2.  Lexicographic Representation

  Binary values are encoded with the base64 encoding scheme [RFC4648].

You need to specify the alphabet used (there are 2 different ones defined in RFC 4648).

11) In Section 12:

  ;; statment keywords
  anyxml-keyword      = 'anyxml'
  argument-keyword    = 'argument'
  augment-keyword    = 'augment'

<'> is not allowed in ABNF.

12)
14.  IANA Considerations

  o  a reference to the (sub)module's documentation (the RFC number)

[...]

  The module name prefix 'ietf-' is reserved for IETF stream documents
  [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
  stream documents.  Modules published in other RFC streams must have a
  similar suitable prefix.  The prefix 'iana-' is reserved for modules
  maintained by IANA.

How can "iana-" be used if all modules require an RFC?

13)
9.4.  The string Built-in Type

  The string built-in type represents human readable strings in YANG.
  Legal characters are tab, carriage return, line feed, and the legal
  characters of Unicode and ISO/IEC 10646 [ISO.10646]:

    ;; any Unicode character, excluding the surrogate blocks,
    ;; FFFE, and FFFF.

(Comment) This comment is not quite correct - it doesn't mention exclusded ASCII control characters (at least some of them).

    string = *char
    char = %x9 / %xA / %xD / %x20-DFFF / %xE000-FFFD /
            %x10000-10FFFF

Surrogate pairs are between U+D800 and U+DFFF. They are not excluded above.

[Ballot comment]
4.2.2.1.  Leaf Nodes

  A leaf node contains simple data like an integer or a string.  It has
  exactly one value of a particular type, and no child nodes.

  YANG Example:

      leaf host-name {
          type string;
          description "Hostname for this system";
      }

  NETCONF XML Example:

      my.example.com

This and other examples got me confused. First, the document says that 1 representation can be converted to the other one without loss of data, but  then the example doesn't show "description".


7.1.6.  The include Statement

  When the optional "revision-date" is present, the specified revision
  of the submodule is included in the module.

What would happen if a specific revision is included, but the submodule doesn't contain any revision?
I assume that would be an error, but I am wondering if it is worth calling this out explicitly.

(Similar comment for "import".)

  Otherwise, it is
  undefined which revision of the submodule is included.

-------New comments----------

7.5.3.  The must Statement

  The "must" statement, which is optional, takes as an argument a
  string which contains an XPath expression.

I think this needs a reference to a section defining XPath expressions.

7.10.  The anyxml Statement

  An anyxml node cannot be augmented.

A reference to where augmented is defined would be useful. Or instead say something like:

  An anyxml node cannot be augmented using the ... statement.

7.18.1.  The feature Statement

  The "feature" statement is used to define a mechanism by which
  portions of the schema are marked as conditional.  A feature name is
  defined that can later be referenced using the "if-feature" statement
  (see Section 7.18.2).  Schema nodes tagged with a feature are ignored
  unless the device supports the given feature.

Does this mean that nodes with if-feature are also ignored (can be omitted) in YIN representation?

  If a feature is dependent on any other features (i.e., the feature
  has one or more "if-feature" sub-statements), then all of features it
  depends on MUST also be implemented by the device.

I think you meant to say that if one of "if-feature" statements of a feature is not implemented by a device, then the device can't implement the feature.

9.4.4.  The length Statement

  The "length" statement, which is an optional substatement to the
  "type" statement, takes as an argument a length expression string.
  It is used to restrict the built-in type "string", or types derived
  from "string".

  A "length" statement restricts the number of characters in the

number of *Unicode* characters

  string.

In Section 12:

  ;;
  ;; RFC 4234 core rules.
  ;;

s/4234/5234

[Ballot discuss]
[I reviewed the whole document, except for the ABNF section. I haven't reviewed reply to my original DUSCUSS yet.]

This is a well written document, a pleasure to read. Thank you.
However I did find some things that I would like to discuss before recommending approval of this document:

1)
5.1.  Modules and Submodules

  The names of all standard modules and submodules MUST be unique.
  Developers of enterprise modules are RECOMMENDED to choose names for

(Similar text in several other sections, e.g. 7.1, 7.2)
Why RECOMMENDED and not a MUST here?
I.e. what is a good reason to violate this and to choose conflicting names?

  their modules that will have a low probability of colliding with
  standard or other enterprise modules, e.g., by using the enterprise
  or organization name as a prefix for the module name.

2)
5.2.  File Layout

  YANG modules and submodules are typically stored in files, one module
  or submodule per file.  The name of the file SHOULD be of the form:

    module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )

Does this mean that 2 new MIME media types should be registered?
If yes, I can help you create the registration templates.

3)
6.1.3.  Quoting

  If the double quoted string contains a line break followed by space
  or tab characters which are used to indent the text according to the

Does a tab character correspond to a fixed number of spaces? If yes, how many?

  layout in the YANG file, this leading whitespace is stripped from the
  string, up to and including the column of the double quote character,
  or to the first non-whitespace character, whichever occurs first.

4)
7.1.  The module Statement

  A module SHOULD have the following layout:

Why SHOULD here? What is the significance of the recommended layout and how does it benefit an implementation?
Parsers can't rely on this SHOULD, so they will have to implement any allowed ordering.

(Similar text in Section 7.2).

-----------New text--------------

5)
7.7.1.  Ordering

  YANG supports two styles for ordering the entries within lists and
  leaf-lists.  In many lists, the order of list entries does not impact
  the implementation of the list's configuration, and the device is
  free to sort the list entries in any reasonable order.  The
  "description" string for the list may suggest an order.

Are you sure you meant "description" here?

  YANG calls
  this style of list "system ordered" and they are indicated with the
  statement "ordered-by system".

6)
7.10.2.  XML Mapping Rules

  An anyxml node is encoded as an XML element.  The element's local
  name is the anyxml's identifier, and its namespace is the module's
  XML namespace (see Section 7.1.3).  The value of the anyxml node is
  encoded as XML content of this element.

and

7.10.4.  Usage Example

  Given the following anyxml statement:

    anyxml data;

  The following are two valid encodings of the same anyxml value:

   
     
        1
     
   

I don't see where the payload ("...") is specified in the example. It looks that either your example is incorrect, or the description of anyxml is incorrect. Of course I can be wrong as well.

7)
7.19.2.  The status Statement

  If a definition is "current", it MUST NOT reference a "deprecated" or
  "obsolete" definition within the same module.

  If a definition is "deprecated", it MUST NOT reference an "obsolete"
  definition within the same module.

What does it mean to reference a definition?

Can you show an example demonstrating use of this statement?

8)
7.19.4.  The reference Statement

  The "reference" statement takes as an argument a string which is used
  to specify a textual cross-reference to an external document, either
  another module which defines related management information, or a
  document which provides additional information relevant to this
  definition.

What do you call a "reference" here? Is a URI a reference?

9)
9.6.4.  The enum Statement

  The "enum" statement, which is a substatement to the "type"
  statement, MUST be present if the type is "enumeration".  It is
  repeatedly used to specify each assigned name of an enumeration type.
  It takes as an argument a string which is the assigned name.  The
  string MUST NOT be empty and MUST NOT have any leading or trailing
  whitespace characters.  The use of control codes SHOULD be avoided.

How do you define a "control code"?

10)

9.8.2.  Lexicographic Representation

  Binary values are encoded with the base64 encoding scheme [RFC4648].

You need to specify the alphabet used (there are 2 different ones defined in RFC 4648).

11) In Section 12:

  ;; statment keywords
  anyxml-keyword      = 'anyxml'
  argument-keyword    = 'argument'
  augment-keyword    = 'augment'

<'> is not allowed in ABNF.

12)
14.  IANA Considerations

  o  a reference to the (sub)module's documentation (the RFC number)

[...]

  The module name prefix 'ietf-' is reserved for IETF stream documents
  [RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
  stream documents.  Modules published in other RFC streams must have a
  similar suitable prefix.  The prefix 'iana-' is reserved for modules
  maintained by IANA.

How can "iana-" be used if all modules require an RFC?

[Ballot comment]
4.2.2.1.  Leaf Nodes

  A leaf node contains simple data like an integer or a string.  It has
  exactly one value of a particular type, and no child nodes.

  YANG Example:

      leaf host-name {
          type string;
          description "Hostname for this system";
      }

  NETCONF XML Example:

      my.example.com

This and other examples got me confused. First, the document says that 1 representation can be converted to the other one without loss of data, but  then the example doesn't show "description".


7.1.6.  The include Statement

  When the optional "revision-date" is present, the specified revision
  of the submodule is included in the module.

What would happen if a specific revision is included, but the submodule doesn't contain any revision?
I assume that would be an error, but I am wondering if it is worth calling this out explicitly.

(Similar comment for "import".)

  Otherwise, it is
  undefined which revision of the submodule is included.

[Ballot discuss]
[I only read 1/3rd of the document so far, but I am sending my comments in order to speedup discuss resolution.]

This is a well written document, a pleasure to read. Thank you.
However I did find some things that I would like to discuss before recommending approval of this document:

1)
5.1.  Modules and Submodules

  The names of all standard modules and submodules MUST be unique.
  Developers of enterprise modules are RECOMMENDED to choose names for

(Similar text in several other sections, e.g. 7.1, 7.2)
Why RECOMMENDED and not a MUST here?
I.e. what is a good reason to violate this and to choose conflicting names?

  their modules that will have a low probability of colliding with
  standard or other enterprise modules, e.g., by using the enterprise
  or organization name as a prefix for the module name.

2)
5.2.  File Layout

  YANG modules and submodules are typically stored in files, one module
  or submodule per file.  The name of the file SHOULD be of the form:

    module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )

Does this mean that 2 new MIME media types should be registered?
If yes, I can help you create the registration templates.

3)
6.1.3.  Quoting

  If the double quoted string contains a line break followed by space
  or tab characters which are used to indent the text according to the

Does a tab character correspond to a fixed number of spaces? If yes, how many?

  layout in the YANG file, this leading whitespace is stripped from the
  string, up to and including the column of the double quote character,
  or to the first non-whitespace character, whichever occurs first.

4)
7.1.  The module Statement

  A module SHOULD have the following layout:

Why SHOULD here? What is the significance of the recommended layout and how does it benefit an implementation?
Parsers can't rely on this SHOULD, so they will have to implement any allowed ordering.

(Similar text in Section 7.2).

IANA comments:

Action 1:

Upon approval of this document, IANA will create the following
registry at http://www.iana.org/assignments/TBD

Registry Name: YANG Module Names
Registration Procedures: RFC Required

Note:
The module name prefix 'ietf-' is reserved for IETF stream documents
[RFC4844] while the module name prefix 'irtf-' is reserved for IRTF
stream documents. Modules published in other RFC streams must have a
similar suitable prefix. The prefix 'iana-' is reserved for modules
maintained by IANA.

Initial contents of this registry will be:

(Sub)Module Name | (Module) Namespace | (Module) Prefix | (SubModule)
Module |
Reference


Action 2:

Upon approval of this document, IANA will make the following assignments
in the "ns" registry at
http://www.iana.org/assignments/xml-registry/ns.html

ID URI Registration template Reference
yang:yin:1 urn:ietf:params:xml:ns:yang:yin:1 yang:yin:1 [RFC-netmod-yang-11]
yang:1 urn:ietf:params:xml:ns:yang:1 yang:1 [RFC-netmod-yang-11]

Document write-up for draft-ietf-netmod-yang-11.txt

  (1.a) Who is the Document Shepherd for this document?

David Partain, NETMOD WG co-chair

Has the Document Shepherd personally reviewed this
version of the document and, in particular, does he or
she believe this version is ready for forwarding to the
IESG for publication?

Yes, I have reviewed this document and consider it very
much ready for IESG review and publication as a Proposed
Standard.

  (1.b) Has the document had adequate review both from key WG members
        and from key non-WG members?

Yes, we have had extensive review of the document itself.
We have requested and received review from outside the
working group.

Does the Document Shepherd have any concerns about the
depth or breadth of the reviews that have been performed?

No, I do not.

  (1.c) Does the Document Shepherd have concerns that the document
        needs more review from a particular or broader perspective,
        e.g., security, operational complexity, someone familiar with
        AAA, internationalization or XML?

        The document would be well-served by further review from
        the XML Directorate review as well as a broader APPS area
review.  Requests have been made for such reviews during
the normal course of WG activity, but response has been
very limited.

  (1.d) Does the Document Shepherd have any specific concerns or
        issues with this document that the Responsible Area Director
        and/or the IESG should be aware of?  For example, perhaps he
        or she is uncomfortable with certain parts of the document, or
        has concerns whether there really is a need for it. In any
        event, if the WG has discussed those issues and has indicated
        that it still wishes to advance the document, detail those
        concerns here.

I am concerned that the document's size is going to be a
hindrance to review by some members of the IETF community.

There have been a number of contentious issues in the
working group, but all have in the end been worked out to
the satisfaction of most.  The most contentious issue was
how defaults are going to be handled, which is now
documented in the specification.

Has an IPR disclosure related to this document been
filed? If so, please include a reference to the
disclosure and summarize the WG discussion and conclusion
on this issue.

No IPR disclosures have been filed against this document.

  (1.e) How solid is the WG consensus behind this document? Does it
        represent the strong concurrence of a few individuals, with
        others being silent, or does the WG as a whole understand and
        agree with it?

I believe this document represents strong consensus of
the working group after intense work over the last 18
months.

  (1.f) Has anyone threatened an appeal or otherwise indicated extreme
        discontent?

No.

  (1.g) Has the Document Shepherd personally verified that the
        document satisfies all ID nits? (See the Internet-Drafts Checklist
        and http://tools.ietf.org/tools/idnits/). Boilerplate checks are
        not enough; this check needs to be thorough.

        Those issues pointed out by the tool are not correct.

1. It incorrectly identifies some numbers as IP
  addresses.  They are not; they are instead section
  numbers.
 
  == There are 14 instances of lines with
  non-RFC3330-compliant IPv4 addresses in the document.
  If these are example addresses, they should be
  changed.

2. There are some possible down-refs, but they are not;
  they are documents produced by other standards bodies.

Has the document met all formal review criteria it needs
to, such as the MIB Doctor, media type and URI type
reviews?

Yes.

  (1.h) Has the document split its references into normative and
        informative?

Yes.

Are there normative references to documents that are not
ready for advancement or are otherwise in an unclear
state?

No.

Are there normative references that are downward
references, as described in [RFC3967]?

No.

  (1.i) Has the Document Shepherd verified that the document IANA
        consideration section exists and is consistent with the body
        of the document?

Yes.

        Are the IANA registries clearly identified?

Yes.

If the document creates a new registry, does it define the
proposed initial contents of the registry and an
allocation procedure for future registrations?

Yes.

Does it suggest a reasonable name for the new registry?

Yes.

If the document describes an Expert Review
process has Shepherd conferred with the Responsible Area
Director so that the IESG can appoint the needed Expert
during the IESG Evaluation?

It does not describe an Expert Review process.

  (1.j) Has the Document Shepherd verified that sections of the
        document that are written in a formal language, such as XML
        code, BNF rules, MIB definitions, etc., validate correctly in
        an automated checker?

Yes.

  (1.k) The IESG approval announcement includes a Document
        Announcement Write-Up. Please provide such a Document
        Announcement Write-Up? Recent examples can be found in the
        "Action" announcements for approved documents. The approval
        announcement contains the following sections:

    Technical Summary

YANG is a data modeling language used to model
configuration and state data manipulated by the Network
Configuration Protocol (NETCONF) protocol, NETCONF remote
procedure calls, and NETCONF notifications.  YANG is used
to model the operations and content layers of NETCONF. This
document describes the syntax and semantics of the YANG
language, how the data model defined in a YANG module is
represented in XML, and how NETCONF operations are used to
manipulate the data.

    Working Group Summary

Consensus was reached among all interested parties before
requesting the publication of this document.

    Document Quality

        There are multiple independent implementations of YANG
today, including both commercial and freely-available
tools.