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

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Thu, 6 May 2010 11:18:19 +0200

Was this DISCUSS and COMMENT from Peter addressed? 

Dan

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of
Peter Saint-Andre
Sent: Wednesday, May 05, 2010 11:51 PM
To: [email-masked]
Cc: [email-masked]; [email-masked]
Subject: DISCUSS and COMMENT: draft-ietf-netmod-yang 

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.

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.