Early Review of draft-ietf-netmod-rfc6020bis-11
review-ietf-netmod-rfc6020bis-11-opsdir-early-morand-2016-05-23-00

I have reviewed this document as part of the Operational directorate's ongoing
effort to review all IETF documents being processed by the IESG.  These
comments were written with the intent of improving the operational aspects of
the IETF drafts. Comments that are not addressed in last call may be included
in AD reviews during the IESG review.  Document editors and WG chairs should
treat these comments just like any other last call comments.

Document: draft-ietf-netmod-rfc6020bis-11

Summary: This document defines version 1.1 of the YANG language.  YANG version
1.1 is a maintenance release of the YANG language, addressing ambiguities and
defects in the original specification, YANG version 1 (RFC6020). Status: Ready
with issues

I'm not familiar with YANG and Netconf and I've read the document as a first
reader, as intended in the introduction. I think the document is mostly clear,
heavily relying on the original document that have been widely used for
implementation of YANG modules. However, I have a number of issues that need to
be considered and could be fixed before publication.

**Main comments:

- it is not clear what is the status of the version 1.1 compared to RFC6020. As
it is a "bis", I assume that it aims to obsolete the RFC6020 but it is not
clearly stated in the abstract and in the introduction of document. -This
comment is based mainly on the following: "addressing ambiguities and defects
in the original specification". As there are defects, new mandatory statements,
deprecation of earlier uses, etc., it is assumed that modelers are encouraged
to define any new YANG module based on this specification. This point could be
clearly stated.

- Backward incompatible changes are not all (enough) highlighted in the section
1.1 and in the body of document (when required).

- At the end of the document, there is a section dealing with coexistence with
YANG version 1. It is said that a "YANG version 1.1 module or submodule MAY
import a YANG version 1 module by revision [...] to allow implementations of
existing YANG version 1 modules together with YANG version 1.1 modules". There
is no other indication, e.g. recommend the definition of pure v1.1module or
migration from of v1 to v1.1. It could lead to long period of coexistence (for
ever?), with the issues known with the v1. I'm wondering what is the real
objectif of this new version and if further recommendations could be given to
modelers to ensure a widespread of the v1.1. It is somehow likned to the final
status of this document.

**Idnits: OK but please use correct example type for IP addresses
== There are 14 instances of lines with non-RFC6890-compliant IPv4
     addresses in the document.  If these are example addresses, they should
     be changed.

Further comments attached hereafter.

regards,

Lionel

******************

1.  Introduction

   YANG is a data modeling language originally designed to model
   configuration and state data manipulated by the Network Configuration
   Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF
   notifications [RFC6241].  Since the publication of YANG version 1
   [RFC6020], YANG has been used or proposed to be used for other
   protocols (e.g., RESTCONF [I-D.ietf-netconf-restconf] and CoMI
   [I-D.vanderstok-core-comi]).

LM: For the purpose i.e. modeling configuration and state data?

   Further, other encodings than XML have
   been proposed (e.g., JSON [I-D.ietf-netmod-yang-json]).

   This document describes the syntax and semantics of version 1.1 of
   the YANG language.

LM: it is not clear what is the status of the version 1.1 compared to RFC6020.
    As it is a "bis", I assume that it aims to obsolete the RFC6020 but it is
    not clearly stated here and in the abstract.

   It also describes how a data model defined in a
   YANG module is encoded in the Extensible Markup Language (XML), and
   how NETCONF operations are used to manipulate the data.  Other
   protocols and encodings are possible, but out of scope for this
   specification.

1.1.  Summary of Changes from RFC 6020

   This document defines version 1.1 of the YANG language.  YANG version
   1.1 is a maintenance release of the YANG language, addressing
   ambiguities and defects in the original specification [RFC6020].

   o  Changed the YANG version from "1" to "1.1".

   o  Made the "yang-version" statement mandatory.

LM: meant is was optional before. Incompatible change?

   o  Made noncharacters illegal in the built-in type "string".

LM: does it imply that it is a backward compatible change?

   o  Defined the legal characters in YANG modules.

   o  Changed the rules for the interpretation of escaped characters in
      double quoted strings.  This is an backwards incompatible change
      from YANG version 1.  A module that uses a character sequence that
      is now illegal must change the string to match the new rules.  See
      Section 6.1.3 for details.

   o  An unquoted string cannot contain any single or double quote
      characters.  This is an backwards incompatible change from YANG
      version 1.

   o  Extended the "if-feature" syntax to be a boolean expression over
      feature names.

   o  Allow "if-feature" in "bit", "enum", and "identity".

LM: what is not clear if what happens when a client supporting the older version
    receives the "if-feature" in these statements.

LM: this comment is valid for any "allow" or "added" listed below.

   o  Allow "if-feature" in "refine".

   o  Made "when" and "if-feature" illegal on list keys.

LM: does it imply that it is a backward compatible change?

[..].

3.  Terminology

   The following terms are used within this document:

   o  action: An operation defined for a node in the data tree.

[...]

   The following terms are defined in [RFC6241]:

   o  configuration data

   o  configuration datastore: a configuration datastore is an
      instantiated data tree with configuration data

   o  datastore: an instantiated data tree

LM: for the two above, either they are in RFC6241 and there is no need
    of additional definition or they are defined in this document.
    Except if there is some nuance

[...]

4.1.  Functional Overview

[...]

   YANG models can describe constraints to be enforced on the data,
   restricting the appearance or value of nodes based on the presence or
   value of other nodes in the hierarchy.  These constraints are
   enforceable by either the client or the server, and valid content
   MUST abide by them.

LM: The section 4 is "non-normative". The "MUST" is not relevant here.
    could simply be: "and the valid content abides by them"
LM: by the way, it is the "valid content" of what?

   YANG defines a set of built-in types, and has a type mechanism
   through which additional types may be defined.  Derived types can
   restrict their base type's set of valid values using mechanisms like
   range or pattern restrictions that can be enforced by clients or
   servers.  They can also define usage conventions for use of the
   derived type, such as a string-based type that contains a host name.

LM: between the first sentence and the second one, it misses the fact that
    the mechanism allows the definition of new type that can be derived
    from a base type, which can be either built-in type or another derived type.

 [...]

4.2.3.  State Data

LM: the title could be extended as "State Data and Configuration Data"

   YANG can model state data, as well as configuration data, based on
   the "config" statement.  When a node is tagged with "config false",
   its subhierarchy is flagged as state data.  In NETCONF, state data is
   reported using the <get> operation, not the <get-config> operation.
   Parent containers, lists, and key leafs are reported also, giving the
   context for the state data.

LM: I know that at this stage, it is just for information/overview, but
    before the second sentence, it could be added with something like:

    "When a node is tagged with "config true" or when the "config" statement
     is not specified, its subhierarchy is flagged as configuration data."

LM: This helps the reader to understand the example given below in which
    there is no "config" statement for the leaf "speed".

   In this example, two leafs are defined for each interface, a
   configured speed and an observed speed.  The observed speed is not
   configuration, so it can be returned with NETCONF <get> operations,
   but not with <get-config> operations.  The observed speed is not
   configuration data, and it cannot be manipulated using <edit-config>.

     list interface {
       key "name";

       leaf name {
         type string;
       }
       leaf speed {
         type enumeration {
           enum 10m;
           enum 100m;
           enum auto;
         }
       }
       leaf observed-speed {
         type uint32;
         config false;
       }
     }

LM: could be useful to add "The "config" statement is covered in Section
7.21.1."

4.2.6.  Reusable Node Groups (grouping)

   Groups of nodes can be assembled into reusable collections using the
   "grouping" statement.  A grouping defines a set of nodes that are
   instantiated with the "uses" statement:

LM: s/instantiated with the "uses" statement:/instantiated with the "uses"
statement. LM:  add "YANG Example:" before the example.

4.2.7.  Choices

   YANG allows the data model to segregate incompatible nodes into
   distinct choices using the "choice" and "case" statements.  The
   "choice" statement contains a set of "case" statements that define
   sets of schema nodes that cannot appear together.  Each "case" may
   contain multiple nodes, but each node may appear in only one "case"
   under a "choice".

   When a node from one case is created in the data tree, all nodes from
   all other cases are implicitly deleted.  The server handles the
   enforcement of the constraint, preventing incompatibilities from
   existing in the configuration.

LM: for clarification, I would add in front of the first sentence:
    "Since only one of the choice's cases can be valid at any time,"

4.2.9.  Operation Definitions

   YANG allows the definition of operations.  The operations' name,
   input parameters, and output parameters are modeled using YANG data
   definition statements.  Operations on the top-level in a module are
   defined with the "rpc" statement.  Operations can also be tied to a
   data node.  Such operations are defined with the "action" statement.

LM: could be added
    "Here is an example for operation on the top-level in a module."

   YANG Example:

     rpc activate-software-image {
       input {
         leaf image-name {
           type string;
         }
       }
       output {
         leaf status {
           type string;
         }
       }
     }

   NETCONF XML Example:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <activate-software-image xmlns="

http://example.com/system&quot

;>
         <image-name>example-fw-2.3</image-name>
      </activate-software-image>
     </rpc>

     <rpc-reply message-id="101"
                xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <status xmlns="

http://example.com/system&quot

;>
         The image example-fw-2.3 is being installed.
       </status>
     </rpc-reply>

LM: could be added
    "Here is an example for operation tied to a data node."

   YANG Example:

     list interface {
       key "name";

       leaf name {
         type string;
       }

       action ping {
         input {
           leaf destination {
             type inet:ip-address;
           }
         }
         output {
           leaf packet-loss {
             type uint8;
           }
         }
       }
     }

   NETCONF XML Example:

     <rpc message-id="102"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <action xmlns="urn:ietf:params:xml:ns:yang:1">
         <interface xmlns="

http://example.com/system&quot

;>
           <name>eth1</name>
           <ping>
             <destination>192.0.2.1</destination>
           </ping>
         </interface>
       </action>
     </rpc>

     <rpc-reply message-id="102"
                xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
                xmlns:sys="

http://example.com/system&quot

;>
       <sys:packet-loss>60</sys:packet-loss>
     </rpc-reply>

   The "rpc" statement is covered in Section 7.14, and the "action"
   statement in Section 7.15.

5.1.  Modules and Submodules

[...]

   For backward compatibility with YANG version 1, a submodule is
   allowed to use the "include" statement to reference other submodules
   within its module, but this is not necessary in YANG version 1.1.  A
   submodule can reference any definition in the module it belongs to
   and in all submodules included by the module.

LM: according to the backward compatibility statement, as it is about
    "allow/not allow", the use of normative text (MUST/SHOULD/MAY) could
    be more appropriate e.g. "MUST use "include" statement". If it is the
    case, the point on backward compatibility could be addressed in a NOTE.

LM: about the backward compatibility issue, I assume that the submodule MUST
    use "import" and SHOULD NOT (strong recommendation) use "include". If it
    is, the recommendation could be strengthened

   A module or submodule MUST NOT include submodules from other modules,
   and a submodule MUST NOT import its own module.

   The import and include statements are used to make definitions
   available from other modules:

   o  For a module or submodule to reference definitions in an external
      module, the external module MUST be imported.

   o  A module MUST include all its submodules.

   o  A module or submodule belonging to that module can reference
      definitions in the module and all submodules included by the
      module.

LM: "that module MAY reference"?

   There MUST NOT be any circular chains of imports.  For example, if
   module "a" imports module "b", "b" cannot import "a".

   When a definition in an external module is referenced, a locally
   defined prefix MUST be used, followed by ":", and then the external
   identifier.  References to definitions in the local module MAY use
   the prefix notation.  Since built-in data types do not belong to any
   module and have no prefix, references to built-in data types (e.g.,
   int32) cannot use the prefix notation.  The syntax for a reference to
   a definition is formally defined by the rule "identifier-ref" in
   Section 14.

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' )

LM: It is assumed that the reader will do a one-to-one mapping between
    this recommended file name format and YANG specific info. This could
    be further detailed, especially if there are some restrictions to apply
    (e.g. unique file name, etc.). Further detailed below.
LM: I assume that "module-name" and "submodule-name" inherit the
    properties of module/submodule names required by YANG (uniqueness, etc.)
LM: I think that "revision-date" makes reference to the the "revision-date"
    statement used in YANG, with the same format. If it is and if there is
    a recommendation to use a specific format for file name ("SHOULD"), it
    could be nice to clarify this point.
LM: It is not said when to use ".yang" or ".yin". It is only assumed that
    the reader can make the difference.

   YANG parsers can find imported modules and included submodules via
   this convention.

5.6.4.  Implementing a Module

[..]

   A server that implements revision "2015-01-01" of module "a" and
   supports feature "foo" can implement revision "2015-01-01" or
   "2015-04-04" of module "b".  Since "b" was imported by revision, the
   type of leaf "/b:x/a:y" is the same regardless of which revision of
   "b" the server implements.

LM: could be intersting to detail why it the same regardless of the
    revision, based on statements given before the example.

   A server that implements module "a", but does not support feature
   "foo" does not have to implement module "b".

   A server that implements revision "2015-01-01" of module "a" must
   pick a revision of module "c", and list it in the "/modules-state/
   module" list from "ietf-yang-library".

LM: "must" may not be appropriate if not normative. therefore, "must pick"
    could be simply "picks"
LM: as any of the revision is OK, this could be clarified as follows:
    "A server that implements revision "2015-01-01" of module "a"
    picks one (or "any") of the revisions of module "c",..."

5.6.5.  Announcing Conformance Information in NETCONF

   This document defines the following mechanism for announcing
   conformance information.  Other mechanisms may be defined by future
   specifications.

   A NETCONF server announces the modules it implements by implementing
   the YANG module "ietf-yang-library" defined in
   [I-D.ietf-netconf-yang-library], and listing all implemented modules
   in the "/modules-state/module" list.

LM: MUST/SHOULD announce?

   The server also advertises the following capability in the <hello>
   message (line-breaks and whitespaces are used for formatting reasons
   only):

LM: MUST/SHOULD advertize?

     urn:ietf:params:netconf:capability:yang-library:1.0?
       module-set-id=<id>

   The parameter "module-set-id" has the same value as the leaf
   "/modules-state/module-set-id" from "ietf-yang-library".  This
   parameter MUST be present.

   With this mechanism, a client can cache the supported modules for a
   server, and only update the cache if the "module-set-id" value in the
   <hello> message changes.

LM: What about interoperability with earlier implementation of YANG?
LM: in particular, what about the standard capability URI defined in RFC6020?

6.  YANG Syntax

   The YANG syntax is similar to that of SMIng [RFC3780] and programming
   languages like C and C++.  This C-like syntax was chosen specifically
   for its readability, since YANG values the time and effort of the
   readers of models above those of modules writers and YANG tool-chain
   developers.  This section introduces the YANG syntax.

   YANG modules use the UTF-8 [RFC3629] character encoding.

   Legal characters in YANG modules are the Unicode and ISO/IEC 10646
   [ISO.10646] characters, including tab, carriage return, and line feed
   but excluding the other C0 control characters, the surrogate blocks,
   and the noncharacters.  The character syntax is formally defined by
   the rule "yang-char" in Section 14.

LM: "legal" means than any other characters are illegal. The use of Unicode
    and ISO/IEC 10646 charactersis was only mentioned for "string" type.
    Not sure of what happens for implementations based on RFC6020...

6.1.3.  Quoting

[...]

   It is an error if any other character follows the backslash
   character.

LM: proposed aleternative:
    "The backslash MUST be followed by any other character"

6.2.  Identifiers

   Identifiers are used to identify different kinds of YANG items by
   name.  Each identifier starts with an uppercase or lowercase ASCII
   letter or an underscore character, followed by zero or more ASCII
   letters, digits, underscore characters, hyphens, and dots.
   Implementations MUST support identifiers up to 64 characters in
   length, and MAY support longer identifiers.  Identifiers are case
   sensitive.

LM: Incompatible change not listed in the section 1.1 (summary of changes), if
I'm correct.

   The identifier syntax is formally defined by the rule
   "identifier" in Section 14.  Identifiers can be specified as quoted
   or unquoted strings.

6.3.  Statements

   A YANG module contains a sequence of statements.  Each statement
   starts with a keyword, followed by zero or one argument, followed
   either by a semicolon (";") or a block of substatements enclosed
   within braces ("{ }"):

     statement = keyword [argument] (";" / "{" *statement "}")

   The argument is a string, as defined in Section 6.1.2.

LM: s/in Section 6.1.2./in Section 7.19.2.

6.3.1.  Language Extensions

   A module can introduce YANG extensions by using the "extension"
   keyword (see Section 7.19).  The extensions can be imported by other
   modules with the "import" statement (see Section 7.1.5).  When an
   imported extension is used, the extension's keyword MUST be qualified
   using the prefix with which the extension's module was imported.

LM: proposal: "using the prefix of the module from which the extension was
imported

   If
   an extension is used in the module where it is defined, the
   extension's keyword MUST be qualified with the module's prefix.

LM: proposal: "MUST be qualified with the prefix of this module"

   The processing of extensions depends on whether support for those
   extensions is claimed for a given YANG parser or the tool set in
   which it is embedded.  An unsupported extension, appearing in a YANG
   module as an unknown-statement (see Section 14) MAY be ignored in its
   entirety.

LM: what is the reason of "MAY" here if it is seen as unknown-statement?
    what if not ignored? is it "MAY be ignored or MAY be treated as an error"?

   Any supported extension MUST be processed in accordance
   with the specification governing that extension.

   Care must be taken when defining extensions so that modules that use
   the extensions are meaningful also for applications that do not
   support the extensions.

6.4.1.  XPath Context

[...]

   If a node that exists in the accessible tree has a non-presence
   container as a child, then the non-presence container also exists in
   the tree.

LM: "non-presence container" is not defined anywhere in the document.
    I can assume that it refers to a container that does not have a
    "presence" statement. If it is, it could be good to:
    define the term in the section 3 and to extend the existing text in
    the section 7.5.5
LM: be consistent along the document. Use either "non-presence container"
    or "non-presence-container". the first one has my preference.

7.1.  The module Statement

   The "module" statement defines the module's name, and groups all
   statements that belong to the module together.  The "module"
   statement's argument is the name of the module, followed by a block
   of substatements that hold detailed module information.  The module
   name follows the rules for identifiers in Section 6.2.

   Names of modules published in RFC streams [RFC4844] MUST be assigned
   by IANA, see section 14 in [RFC6020].

LM: Could be a reference to section 16 of this document, depending on the
answer on the IANA considerations

7.1.2.  The yang-version Statement

   The "yang-version" statement specifies which version of the YANG
   language was used in developing the module.  The statement's argument
   is a string.  It MUST contain the value "1.1", which is the current
   YANG version.

LM: The "MUST" seems not consistent with the fact that RFC6020 can be
    supported as described below "or one that contains the value "1"".

7.1.4.  The prefix Statement

[...]

   When used inside the "import" statement, the "prefix" statement
   defines the prefix to be used when accessing definitions inside the
   imported module.  When a reference to an identifier from the imported
   module is used, the prefix string for the imported module is used in
   combination with a colon (":") and the identifier, e.g.,
   "if:ifIndex".  To improve readability of YANG modules, the prefix
   defined by a module SHOULD be used when the module is imported,
   unless there is a conflict.  If there is a conflict, i.e., two
   different modules that both have defined the same prefix are
   imported, at least one of them MUST be imported with a different
   prefix.

LM: if there is only one possible conflict i.e." modules defining
    the same prefix are imported", the text can be maybe simpler:

    "To improve readability of YANG modules, the prefix defined by
     a module SHOULD be used when the module is imported, unless
     this prefix is already defined by another imported module. In
     that case, at least one of them MUST be imported with a
     different prefix."

7.1.5.  The import Statement

[...]

   Multiple revisions of the same module can be imported, provided that
   different prefixes are used.

LM: "Multiple revisions of the same module MAY be imported"?

7.1.6.  The include Statement

   The "include" statement is used to make content from a submodule
   available to that submodule's parent module.  The argument is an
   identifier that is the name of the submodule to include.  Modules are
   only allowed to include submodules that belong to that module, as
   defined by the "belongs-to" statement (see Section 7.2.2).

   When a module includes a submodule, it incorporates the contents of
   the submodule into the node hierarchy of the module.

   For backward compatibility with YANG version 1, a submodule is
   allowed to include another submodule belonging to the same module,
   but this is not necessary in YANG version 1.1.

LM: it should be explained why "it is not necessary" in version 1.1.
LM: If it is recommended to deprecate the use of submodule inside submodule,
    the guidance could be more directive e.g.:

    "A submodule developed for YANG 1.1 MUST NOT include another
     submodule belonging to the same module.
     A submodule developed for YANG 1 MAY include another submodule
     belonging to the same module."

7.2.  The submodule Statement

[...]

   Names of submodules published in RFC streams [RFC4844] MUST be
   assigned by IANA, see section 14 in [RFC6020].

LM: Same comment regarding IANA actions. See Section 16.

7.2.2.  The belongs-to Statement

[...]

   The mandatory "prefix" substatement assigns a prefix for the module
   to which the submodule belongs.  All definitions in the module that
   the submodule belongs to and all its submodules can be accessed by
   using the prefix.

LM: About "can be accessed", is it a possibility/capability
    or there is no other mean? If not, could be more appropriate to say:
    "are accessed"

7.5.1.  Containers with Presence

   YANG supports two styles of containers, those that exist only for
   organizing the hierarchy of data nodes, and those whose presence in
   the data tree has an explicit meaning.

   In the first style, the container has no meaning of its own, existing
   only to contain child nodes.  This is the default style.

LM: s/no meaning of its own/no meaning on its own"

   For example, the set of scrambling options for Synchronous Optical
   Network (SONET) interfaces may be placed inside a "scrambling"
   container to enhance the organization of the configuration hierarchy,
   and to keep these nodes together.  The "scrambling" node itself has
   no meaning, so removing the node when it becomes empty relieves the
   user from performing this task.

   In the second style, the presence of the container itself carries
   some meaning, representing a single bit of data.

   In configuration data, the container acts as both a configuration
   knob and a means of organizing related configuration.  These
   containers are explicitly created and deleted.

LM: s/In configuration data/In the case of of configuration data

7.5.3.  The must Statement

[...]

   All such constraints MUST evaluate to true for the data to be valid.

LM: s/evaluate to true/evaluate to "true"

7.5.4.1.  The error-message Statement

   The "error-message" statement, which is optional, takes a string as
   an argument.  If the constraint evaluates to false, the string is
   passed as <error-message> in the <rpc-error> in NETCONF.

LM: s/false/"false"

7.5.4.2.  The error-app-tag Statement

   The "error-app-tag" statement, which is optional, takes a string as
   an argument.  If the constraint evaluates to false, the string is
   passed as <error-app-tag> in the <rpc-error> in NETCONF.

LM: s/false/"false"

7.5.5.  The presence Statement

   The "presence" statement assigns a meaning to the presence of a
   container in the data tree.  It takes as an argument a string that
   contains a textual description of what the node's presence means.

   If a container has the "presence" statement, the container's
   existence in the data tree carries some meaning.  Otherwise, the
   container is used to give some structure to the data, and it carries
   no meaning by itself.

LM: If "non-presence container" refers to container without the "presence"
    statement, it could be useful to introduce the term in this section.

   See Section 7.5.1 for additional information.

7.5.7.  XML Encoding Rules

[...]

   If a non-presence container does not have any child nodes, the
   container may or may not be present in the XML encoding.

LM: s/may or may not be present/may not be present
LM: be consistent along the document. Use either "non-presence container"
    or "non-presence-container". the first one has my preference.

7.5.8.  NETCONF <edit-config> Operations

   Containers can be created, deleted, replaced, and modified through
   <edit-config>, by using the "operation" attribute (see [RFC6241],
   Section 7.2) in the container's XML element.

   If a container does not have a "presence" statement and the last
   child node is deleted, the NETCONF server MAY delete the container.

   When a NETCONF server processes an <edit-config> request, the
   elements of procedure for the container node are:

      If the operation is "merge" or "replace", the node is created if
      it does not exist.

      If the operation is "create", the node is created if it does not
      exist.  If the node already exists, a "data-exists" error is
      returned.

LM: is returned/MUST be returned

      If the operation is "delete", the node is deleted if it exists.
      If the node does not exist, a "data-missing" error is returned.

LM: is returned/MUST be returned

7.6.1.  The leaf's default value

   The default value of a leaf is the value that the server uses if the
   leaf does not exist in the data tree.  The usage of the default value
   depends on the leaf's closest ancestor node in the schema tree that
   is not a non-presence-container (see Section 7.5.1):

LM: be consistent along the document. Use either "non-presence container"
    or "non-presence-container". the first one has my preference.

7.6.4.  The leaf's default Statement

   The "default" statement, which is optional, takes as an argument a
   string that contains a default value for the leaf.

   The value of the "default" statement MUST be valid according to the
   type specified in the leaf's "type" statement.

   The "default" statement MUST NOT be present on nodes where
   "mandatory" is true.

LM: s/is true/is "true"

7.6.5.  The leaf's mandatory Statement

   The "mandatory" statement, which is optional, takes as an argument
   the string "true" or "false", and puts a constraint on valid data.
   If not specified, the default is "false".

   If "mandatory" is "true", the behavior of the constraint depends on
   the type of the leaf's closest ancestor node in the schema tree that
   is not a non-presence-container (see Section 7.5.1):

LM: be consistent along the document. Use either "non-presence container"
    or "non-presence-container". the first one has my preference.

7.6.7.  NETCONF <edit-config> Operations

   When a NETCONF server processes an <edit-config> request, the
   elements of procedure for the leaf node are:

      If the operation is "merge" or "replace", the node is created if
      it does not exist, and its value is set to the value found in the
      XML RPC data.

      If the operation is "create", the node is created if it does not
      exist.  If the node already exists, a "data-exists" error is
      returned.

LM: is returned/MUST be returned

      If the operation is "delete", the node is deleted if it exists.
      If the node does not exist, a "data-missing" error is returned.

LM: is returned/MUST be returned

7.7.  The leaf-list Statement

   Where the "leaf" statement is used to define a simple scalar variable
   of a particular type, the "leaf-list" statement is used to define an
   array of a particular type.  The "leaf-list" statement takes one
   argument, which is an identifier, followed by a block of
   substatements that holds detailed leaf-list information.

   In configuration data, the values in a leaf-list MUST be unique.

LM: s/In configuration data/when defining configuration data,

   The default values MUST NOT be marked with an "if-feature" statement.

   Conceptually, the values in the data tree are always in the canonical
   form (see Section 9.1).

LM: could be "the values in the data tree MUST be in the canonical form"?

7.7.2.  The leaf-list's default values

   The default values of a leaf-list are the values that the server uses
   if the leaf-list does not exist in the data tree.  The usage of the
   default values depends on the leaf-list's closest ancestor node in
   the schema tree that is not a non-presence-container (see
   Section 7.5.1):

LM: be consistent along the document. Use either "non-presence container"
    or "non-presence-container". the first one has my preference.

7.7.9.  NETCONF <edit-config> Operations

      If the operation is "create", the leaf-list entry is created if it
      does not exist.  If the leaf-list entry already exists, a
      "data-exists" error is returned.

LM: is returned/MUST be returned

      If the operation is "delete", the entry is deleted from the leaf-
      list if it exists.  If the leaf-list entry does not exist, a
      "data-missing" error is returned.

LM: is returned/MUST be returned

7.8.6.  NETCONF <edit-config> Operations

[...]

   When a NETCONF server processes an <edit-config> request, the
   elements of procedure for a list node are:

      If the operation is "merge" or "replace", the list entry is
      created if it does not exist.  If the list entry already exists
      and the "insert" and "key" attributes are present, the list entry
      is moved according to the values of the "insert" and "key"
      attributes.  If the list entry exists and the "insert" and "key"
      attributes are not present, the list entry is not moved.

      If the operation is "create", the list entry is created if it does
      not exist.  If the list entry already exists, a "data-exists"
      error is returned.

LM: is returned/MUST be returned

      If the operation is "delete", the entry is deleted from the list
      if it exists.  If the list entry does not exist, a "data-missing"
      error is returned.

LM: is returned/MUST be returned

7.9.3.  The choice's default Statement

   The "default" statement MUST NOT be present on choices where
   "mandatory" is true.

LM: s/is true/is "true"

7.9.4.  The choice's mandatory Statement

[...]

   The behavior of the constraint depends on the type of the choice's
   closest ancestor node in the schema tree that is not a non-presence-
   container (see Section 7.5.1):

LM: be consistent along the document. Use either "non-presence container"
    or "non-presence-container". the first one has my preference.

7.10.  The anydata Statement

[...]

   An anydata node cannot be augmented (see Section 7.17).

LM: "MUST NOT be augmented"?

   An anydata node exists in zero or one instances in the data tree.

LM: "MUST exist"?

   An implementation may or may not know the data model used to model a
   specific instance of an anydata node.

LM: "may or may not" --> "MAY NOT"?

   Since the use of anydata limits the manipulation of the content, it
   is RECOMMENDED that the "anydata" statement not be used to define
   configuration data.

LM: I would suggest:
   "the "anydata" statement SHOULD NOT be used to define configuration data"

7.10.3.  NETCONF <edit-config> Operations

   An anydata node is treated as an opaque chunk of data.  This data can
   be modified in its entirety only.

LM: It is not possible to modify a part of the data chunk.
    "This data MUST be modified in its entirety" seems more appropriate.

   Any "operation" attributes present on subelements of an anydata node
   are ignored by the NETCONF server.

LM: s/are ignored by the NETCONF server/MUST be ignored

   When a NETCONF server processes an <edit-config> request, the
   elements of procedure for the anydata node are:

      If the operation is "merge" or "replace", the node is created if
      it does not exist, and its value is set to the subelements of the
      anydata node found in the XML RPC data.

      If the operation is "create", the node is created if it does not
      exist, and its value is set to the subelements of the anydata node
      found in the XML RPC data.  If the node already exists, a
      "data-exists" error is returned.

LM: s/is returned/MUST be returned.

      If the operation is "delete", the node is deleted if it exists.
      If the node does not exist, a "data-missing" error is returned.

LM: s/is returned/MUST be returned

7.11.  The anyxml Statement

   The "anyxml" statement defines an interior node in the schema tree.
   It takes one argument, which is an identifier, followed by a block of
   substatements that holds detailed anyxml information.

   The "anyxml" statement is used to represent an unknown chunk of XML.
   No restrictions are placed on the XML.  This can be useful, for
   example, in RPC replies.  An example is the <filter> parameter in the
   <get-config> operation in NETCONF.

   An anyxml node cannot be augmented (see Section 7.17).

LM: "MUST NOT be augmented"?

   An anyxml node exists in zero or one instances in the data tree.

LM: "MUST exist"?

   Since the use of anyxml limits the manipulation of the content, it is
   RECOMMENDED that the "anyxml" statement not be used to define
   configuration data.

LM: I recommend:
    "the "anyxml" statement SHOULD NOT be used to define configuration data."

7.11.3.  NETCONF <edit-config> Operations

   An anyxml node is treated as an opaque chunk of data.  This data can
   be modified in its entirety only.

LM: It is not possible to modify a part of the data chunk.
    "This data MUST be modified in its entirety" seems more appropriate.

   Any "operation" attributes present on subelements of an anyxml node
   are ignored by the NETCONF server.

LM: s/are ignored by the NETCONF server/MUST be ignored by the NETCONF server

   When a NETCONF server processes an <edit-config> request, the
   elements of procedure for the anyxml node are:

      If the operation is "merge" or "replace", the node is created if
      it does not exist, and its value is set to the XML content of the
      anyxml node found in the XML RPC data.

      If the operation is "create", the node is created if it does not
      exist, and its value is set to the XML content of the anyxml node
      found in the XML RPC data.  If the node already exists, a
      "data-exists" error is returned.

LM: s/is returned/MUST be returned

      If the operation is "delete", the node is deleted if it exists.
      If the node does not exist, a "data-missing" error is returned.

LM: s/is returned/MUST be returned

7.14.2.  The input Statement

[...]

   If any node has a "when" statement that would evaluate to false, then
   this node MUST NOT be present in the input tree.

LM: s/false/"false"

7.14.3.  The output Statement

[...]

   If any node has a "when" statement that would evaluate to false, then
   this node MUST NOT be present in the output tree.

LM: s/false/"false"

7.15.  The action Statement

[...]

   Since an action cannot be defined an the top-level of a module or in
   a case statement, it is an error if a grouping that contains an
   action at the top of its node hierarchy is used at the top-level of a
   module or in a case definition.

LM: s/defined an the top-level/defined at the top-level
LM: Not sure if there is a previous explanation of why an action cannot
    be defined at the top-level of a module or in a case statement.
LM: if not explain, it could be said:

    "An action MUST NOT be defined an the top-level of a module or in
    a case statement. It is an error if a grouping that contains an
    action at the top of its node hierarchy is used at the top-level of a
    module or in a case definition."

7.16.  The notification Statement

[...]

   Since a notification cannot be defined in a case statement, it is an
   error if a grouping that contains a notification at the top of its
   node hierarchy is used in a case definition.

LM: Not sure if there is a previous explanation of why a notification cannot
    be defined in a case statement.
LM: if not explain, it could be said:
    "A notification MUST NOT be defined in a case statement. It is an
    error if a grouping that contains a notification at the top of its
    node hierarchy is used in a case definition."

7.17.  The augment Statement

   If the augmentation adds mandatory configuration nodes (see
   Section 3) to a target node in another module, the augmentation MUST
   be conditional with a "when" statement.  Care must be taken when
   defining the "when" expression, so that clients that do not know
   about the augmenting module do not break.

LM: To match the definition in section 3:
    s/adds mandatory configuration nodes/adds mandatory nodes

8.1.  Constraints on Data

   Several YANG statements define constraints on valid data.  These
   constraints are enforced in different ways, depending on what type of
   data the statement defines.

   o  If the constraint is defined on configuration data, it MUST be
      true in a valid configuration data tree.

LM: s/true/"true"

   o  If the constraint is defined on state data, it MUST be true in a
      valid state data tree.

LM: s/true/"true"

   o  If the constraint is defined on notification content, it MUST be
      true in any notification data tree.

LM: s/true/"true"

   o  If the constraint is defined on RPC or action input parameters, it
      MUST be true in an invocation of the RPC or action operation.

LM: s/true/"true"

   o  If the constraint is defined on RPC or action output parameters,
      it MUST be true in the RPC or action reply.

LM: s/true/"true"

[...]

   The following properties are true in a valid data tree:

LM: s/true/"true"?

   o  All "must" constraints MUST evaluate to "true".

   o  All referential integrity constraints defined via the "path"
      statement MUST be satisfied.

   o  All "unique" constraints on lists MUST be satisfied.

   o  The "mandatory" constraint is enforced for leafs and choices,
      unless the node or any of its ancestors has a "when" condition or
      "if-feature" expression that evaluates to "false".

LM: "The "mandatory" constraint MUST be enforced"?

   o  The "min-elements" and "max-elements" constraints are enforced for
      lists and leaf-lists, unless the node or any of its ancestors has
      a "when" condition or "if-feature" expression that evaluates to
      "false".

LM: "The "min-elements" and "max-elements" constraints MUST be enforced"?

   The running configuration datastore MUST always be valid.

8.2.  Configuration Data Modifications

   o  If a request creates configuration data nodes under a "choice",
      any existing nodes from other "case" branches are deleted by the
      server.

LM: s/are deleted/MUST be deleted

   o  If a request modifies a configuration data node such that any
      node's "when" expression becomes false, then the node with the
      "when" expression is deleted by the server.

LM: s/false/"false"
LM: s/is deleted by/MUST be deleted by

9.2.3.  Restrictions

   All integer types can be restricted with the "range" statement
   (Section 9.2.4).

LM: s/can be restricted/MAY be restricted
LM: apply to all the following "Restrictions" section

9.2.4.  The range Statement

[...]

   A range consists of an explicit value, or a lower-inclusive bound,
   two consecutive dots "..", and an upper-inclusive bound.  Multiple
   values or ranges can be given, separated by "|".

LM: s/ranges can be given/ranges MAY be given

10.2.1.  re-match()

     boolean re-match(string subject, string pattern)

   The re-match() function returns true if the "subject" string matches
   the regular expression "pattern"; otherwise it returns false.

LM: s/returns true/returns "true"
LM: s/returns falsereturns "false"

10.2.1.1.  Usage Example

   The expression:

     re-match('1.22.333', '\d{1,3}\.\d{1,3}\.\d{1,3}')

   returns true.

LM: s/true/"true"

   To count all logical interfaces called eth0.<number>, do:

     count(/interface[re-match(name, 'eth0\.\d+')])

10.4.1.  derived-from()

     boolean derived-from(node-set nodes, string identity)

   The derived-from() function returns true if any node in the argument
   "nodes" is a node of type identityref, and its value is an identity
   that is derived from (see Section 7.18.2) the identity "identity";
   otherwise it returns false.

LM: s/true/"true"
LM: s/false/"false"

10.4.2.  derived-from-or-self()

     boolean derived-from-or-self(node-set nodes, string identity)

   The derived-from-or-self() function returns true if any node in the
   argument "nodes" is a node of type identityref, and its value is an
   identity that is equal to or derived from (see Section 7.18.2) the
   identity "identity"; otherwise it returns false.

LM: s/true/"true"
LM: s/false/"false"

10.6.1.  bit-is-set()

     boolean bit-is-set(node-set nodes, string bit-name)

   The bit-is-set() function returns true if the first node in document
   order in the argument "nodes" is a node of type bits, and its value
   has the bit "'bit-name" set; otherwise it returns false.

LM: s/true/"true"
LM: s/false/"false"

11.  Updating a Module

[...]

   In statements that have any data definition statements as
   substatements, those data definition substatements MUST NOT be
   reordered.  If new data definition statements are added, they can be
   added anywhere in the sequence of existing substatement.

LM: s/they can be added anywhere/they MAY be added anywhere

12.  Coexistence with YANG version 1

   A YANG version 1.1 module MUST NOT include a YANG version 1
   submodule, and a YANG version 1 module MUST NOT include a YANG
   version 1.1 submodule.

   A YANG version 1 module or submodule MUST NOT import a YANG version
   1.1 module by revision.

   A YANG version 1.1 module or submodule MAY import a YANG version 1
   module by revision.

LM: based on previous statements, is there any limitation on the reusability
    of v1 based module? if yes, the text should be amended.

   If a YANG version 1 module A imports module B without revision, and
   module B is updated to YANG version 1.1, a server MAY implement both
   these modules (A and B) at the same time.  In such cases, a NETCONF
   server MUST advertise both modules using the rules defined in
   Section 5.6.5, and SHOULD advertise module A and the latest revision
   of module B that is specified with YANG version 1 according to the
   rules defined in [RFC6020].

LM: it is obviously assumed that the server supports both v1 and v1.1.

   This rule exists in order to allow implementations of existing YANG
   version 1 modules together with YANG version 1.1 modules.  Without
   this rule, updating a single module to YANG version 1.1 would have a
   cascading effect on modules that import it, requiring all of them to
   also be updated to YANG version 1.1, and so on.

LM: It could be stated again here how v1 based implementation can detect v1.1
and
    vice-versa (using the presence of "yang-version" statement)
LM: the proposed approach could leave to a very long period of coexistence of
the
    two versions and limit the spread of the version 1.1.

16.  IANA Considerations

LM: If the "bis" obsoletes the RFC6020, it could be better to find here
somethink like:
    "This document uses several registries that were originally created in
    RFC6020.
     IANA has updated these to reference this document.  The registries and
     their allocation policies (unchanged from RFC6020) are listed below."

     [...]

LM: And then, the following text is added.

   This document registers one capability identifier URN from the
   "Network Configuration Protocol (NETCONF) Capability URNs" registry:

     Index           Capability Identifier
     -------------   ---------------------------------------------------
     :yang-library   urn:ietf:params:netconf:capability:yang-library:1.0

_________________________________________________________________________________________________________________________

Ce message et ses pieces jointes peuvent contenir des informations
confidentielles ou privilegiees et ne doivent donc pas etre diffuses, exploites
ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez
le signaler a l'expediteur et le detruire ainsi que les pieces jointes. Les
messages electroniques etant susceptibles d'alteration, Orange decline toute
responsabilite si ce message a ete altere, deforme ou falsifie. Merci.

This message and its attachments may contain confidential or privileged
information that may be protected by law; they should not be distributed, used
or copied without authorisation. If you have received this email in error,
please notify the sender and delete this message and its attachments. As emails
may be altered, Orange is not liable for messages that have been modified,
changed or falsified. Thank you.