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 operation, not the 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 operations, but not with operations. The observed speed is not configuration data, and it cannot be manipulated using . 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: 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= 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 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 in the 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 in the 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 Operations Containers can be created, deleted, replaced, and modified through , 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 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 Operations When a NETCONF server processes an 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 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 Operations [...] When a NETCONF server processes an 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 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 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 parameter in the 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 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 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., 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.