Subject: [netmod] FW: DISCUSS and COMMENT: draft-ietf-netmod-yang

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Mon, 26 Apr 2010 10:36:54 +0200

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of
Alexey Melnikov
Sent: Monday, April 26, 2010 12:51 AM
To: [email-masked]
Cc: [email-masked]; [email-masked]
Subject: DISCUSS and COMMENT: draft-ietf-netmod-yang 

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:

     <data xmlns:if="http://example.com/ns/interface">
       <if:interface>
         <if:ifIndex>1</if:ifIndex>
       </if:interface>
     </data>

I don't see where the payload ("<if:interface>...") 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.

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:

       <host-name>my.example.com</host-name>

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