diff --git a/.github/workflows/pull_request_updated.yml b/.github/workflows/pull_request_updated.yml index a84b9d4..4d2dc52 100644 --- a/.github/workflows/pull_request_updated.yml +++ b/.github/workflows/pull_request_updated.yml @@ -94,7 +94,7 @@ jobs: } - name: Test summary line for changes run: | - echo "${{env.SUMMARY_LINE}}" | grep -qF "0 flaws (~~), 3 warnings (==), 6 comments (--)" || { + echo "${{env.SUMMARY_LINE}}" | grep -qF "0 flaws (~~), 3 warnings (==), 5 comments (--)" || { echo "::error::Idnits summary line different - examine why (fix workflow if needed)" exit 1 } diff --git a/draft-yn-netmod-yang2.xml b/draft-yn-netmod-yang2.xml index 4f3b489..314bd8c 100644 --- a/draft-yn-netmod-yang2.xml +++ b/draft-yn-netmod-yang2.xml @@ -30,12 +30,9 @@ YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and - semantics of 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. There are a small number - of backward incompatibilities from YANG version 1. This document - also specifies the YANG mappings to the Network Configuration - Protocol (NETCONF). + semantics of version 2.0 of the YANG language. YANG version 2.0 is + a major release of the YANG language, addressing issues found in + the original specification. @@ -52,269 +49,54 @@ -
+
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 . Since the publication of YANG -version 1 , YANG has been used or proposed to be -used for other protocols (e.g., RESTCONF and -CORECONF ). Further, encodings other than XML have been -proposed (e.g., JSON ). - - -This document describes the syntax and semantics of version 1.1 of the -YANG language. 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 are out of scope -for this specification. - - -In terms of developing YANG data models, -provides some guidelines and recommendations. - - -Note that this document does not obsolete RFC 6020 . - -
- 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 . - - -The following changes are not backward compatible with YANG version 1: - -
    -
  • - -Changed the rules for the interpretation of escaped characters in -double-quoted strings. This is a backward-incompatible change -from YANG version 1. When updating a YANG version 1 module to 1.1 -and the module uses a character sequence that is now illegal, the -string must be changed to match the new rules. -See for details. - -
    • -
  • - -An unquoted string cannot contain any single or double quote -characters. This is a backward-incompatible change from YANG -version 1. When updating a YANG version 1 module to 1.1 and the -module uses such quote characters, the string must be changed to match -the new rules. See for details. - -
    • -
  • - -Made "when" and "if‑feature" illegal on list keys. -This is a backward-incompatible change from YANG version 1. When updating a -YANG version 1 module to 1.1 and the module uses these constructs, -they must be removed to match the new rules. - -
    • -
  • - -Defined the legal characters in YANG modules. When updating a -YANG version 1 module to 1.1, any characters that are now illegal -must be removed. See for details. - -
    • -
  • - -Made noncharacters illegal in the built-in type "string". This -change affects the runtime behavior of YANG-based protocols. - -
    • -
- -The following additional changes have been done to YANG: - -
    -
  • - -Changed the YANG version from "1" to "1.1". - -
    • -
  • - -Made the "yang‑version" statement mandatory in YANG version "1.1". - -
    • -
  • - -Extended the "if‑feature" syntax to be a boolean expression over -feature names. - -
    • -
  • - -Allow "if‑feature" in "bit", "enum", and "identity". - -
    • -
  • - -Allow "if‑feature" in "refine". - -
    • -
  • - -Allow "choice" as a shorthand "case" statement (see ). - -
    • -
  • - -Added a new substatement "modifier" to the "pattern" -statement (see ). - -
    • -
  • - -Allow "must" in "input", "output", and "notification". - -
    • -
  • - -Allow "require‑instance" in leafref. - -
    • -
  • - -Allow "description" and "reference" in "import" and "include". - -
    • -
  • - -Allow imports of multiple revisions of a module. - -
    • -
  • - -Allow "augment" to add conditionally mandatory nodes (see ). - -
    • -
  • - -Added a set of new XML Path Language (XPath) functions -in . - -
    • -
  • - -Clarified the XPath context's tree in . - -
    • -
  • - -Defined the string value of an identityref in XPath expressions -(see ). - -
    • -
  • - -Clarified what unprefixed names mean in leafrefs in typedefs (see -Sections  and -). - -
    • -
  • - -Allow identities to be derived from multiple base identities (see -Sections  and -). - -
    • -
  • - -Allow enumerations and bits to be subtyped (see -Sections  -and ). - -
    • -
  • - -Allow leaf-lists to have default values (see -). - -
    • -
  • - -Allow non-unique values in non-configuration leaf-lists (see -). - - -
    • -
  • - -Use syntax for case-sensitive strings (as per ) in the grammar. - -
    • -
  • - -Changed the module advertisement mechanism (see ). - -
    • -
  • - -Changed the scoping rules for definitions in submodules. A -submodule can now reference all definitions in all submodules that -belong to the same module, without using the "include" statement. - -
    • -
  • - -Added a new statement "action", which is used to define operations -tied to data nodes. - -
    • -
  • - -Allow notifications to be tied to data nodes. - -
    • -
  • - -Added a new data definition statement "anydata" (see ), -which is RECOMMENDED to be used instead of "anyxml" when the data -can be modeled in YANG. - -
    • -
  • - -Allow types "empty" and "leafref" in unions. - -
    • -
  • - -Allow type "empty" in a key. - -
    • -
  • - -Removed the restriction that identifiers could not start with the -characters "xml". - -
    • -
- -The following changes have been done to the NETCONF mapping: - -
    -
  • - -A server advertises support for YANG 1.1 modules by using -ietf‑yang-library instead of listing -them as capabilities in the <hello> message. - -
    • -
+ YANG is a data modeling + language used to model configuration, operational state, asynchronous + notifications, and remote procedure calls (RPCs) for network management. + In this sense, YANG is a domain-specific data modeling language having, + e.g., first-class annotations for configuration and operational state, + with rules for how they relate. + Historically, YANG has been used to manage network elements such as + routers, switches, and firewalls. That said, YANG is suitable for defining + the API for any network application. The key being that, in defining an + application's data model, both its API and persistence layers can be + automatically generated. + YANG is high-level data modeling language, independent of any specific + encoding or any specific protocol. Encodings (e.g., XML , + JSON , CBOR , etc.) + and protocols (e.g., NETCONF , RESTCONF + , CORECONF , + etc.) are out of scope for this specification. + This document describes the syntax and semantics of version 2.0 + of the YANG language (YANG 1.1). YANG 2.0 is a major + release of the YANG language, addressing issues in the + original specification. + Note that this document does not obsolete RFC 6020 + or RFC 7950 . A mix of YANG module versions may be + used to describe a complete data model, as described in Section . + In terms of developing YANG data models, + provides some guidelines and recommendations. +
+ Summary of Changes from RFC 7950 + This document defines version 2.0 of the YANG language. YANG 2.0 + is a major release of the YANG language. Whilst it is by and large the + same as RFC 7950, the following changes exist: +
    +
  1. Removed the "XML Encoding Rules" sections. This content was moved to the 'yang-xml' document.
    2. +
  2. Removed the "NETCONF <edit-config> Operations" sections. This content was moved to the 'netconf-2' document.
    3. +
  3. Removed the "NETCONF XML Encoding Rules" sections. This content was moved to the 'netconf-2' document.
    4. +
  4. Removed the "Example Usage" sections. This content was deemed redundant.
    5. +
  5. Renamed the "NETCONF Constraint Enforcement Model" section to "Constraint Enforcement Model".
    6. +
  6. Each "XML Encoding Example" in (Language Overview) + now has a matching "JSON Encoding Example".
    7. +
  7. Each "NETCONF XML Example" in (Language Overview) + now has a matching "RESTCONF JSON Example".
    8. +
  8. Added a "Protocols Mappings" section.
    9. +
-
+
Key Words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", @@ -322,7 +104,7 @@ them as capabilities in the <hello> message. in BCP 14 when, and only when, they appear in all capitals, as shown here.
-
+
Terminology @@ -601,7 +383,7 @@ space of its data type. -The following terms are defined in : +The following terms are defined in :
  • @@ -633,31 +415,37 @@ data tree. When modeled with YANG, a configuration datastore is realized as an instantiated data tree with configuration data. -
    +
    A Note on Examples Throughout this document, there are many examples of YANG statements. These examples are supposed to illustrate certain features and are not supposed to be complete, valid YANG modules. + Also throughout this document, there are many usage examples. + These examples are sometimes out of context and therefore + incomplete.
    -
    +
    YANG Overview This non-normative section is intended to give a high-level overview of YANG to first-time readers. -
    +
    Functional Overview -YANG is a language originally designed to model data for the NETCONF -protocol. A YANG module defines hierarchies of data that can be used -for NETCONF-based operations, including configuration, state data, +YANG is primarily designed to model application data, which can be +used to automate the generation of both APIs and CLIs. YANG may +also be used to model document data, for use independent of an +application. + + +A YANG module defines hierarchies of data that can be used +for protocol operations including configuration, state data, RPCs, and notifications. This allows a complete description of all -data sent between a NETCONF client and server. Although out of scope -for this specification, YANG can also be used with protocols other -than NETCONF. +data sent between a protocol client and server. YANG models the hierarchical organization of data as a tree in which @@ -703,7 +491,7 @@ for manipulating the order of the list entries. YANG modules can be translated into an equivalent XML syntax called -YANG Independent Notation (YIN) (), allowing +YANG Independent Notation (YIN) (), allowing applications using XML parsers and Extensible Stylesheet Language Transformations (XSLT) scripts to operate on the models. The conversion from YANG to YIN is semantically lossless, so content in @@ -719,26 +507,26 @@ out sufficiently for the reader to notice them. YANG resists the tendency to solve all possible problems, limiting the problem space to allow expression of data models for network -management protocols such as NETCONF, not arbitrary XML documents or +management protocols such as NETCONF or RESTCONF, not arbitrary documents or arbitrary data models. To the extent possible, YANG maintains compatibility with the Simple Network Management Protocol's (SNMP's) SMIv2 (Structure of Management -Information version 2 ). +Information version 2 ). SMIv2-based MIB modules can be automatically translated into YANG modules -for read-only access . However, YANG is not +for read-only access . However, YANG is not concerned with reverse translation from YANG to SMIv2.
    -
    +
    Language Overview This section introduces some important constructs used in YANG that will aid in the understanding of the language specifics in later sections. -
    +
    Modules and Submodules YANG data models are defined in modules. A module contains a @@ -773,15 +561,15 @@ The "include" statement is used in a module to identify each submodule that belongs to it.
    -
    +
    Data Modeling Basics YANG defines four main types of data nodes for data modeling. In each of the following subsections, the examples show the YANG syntax as -well as a corresponding XML encoding. The syntax of YANG statements -is defined in . +well as corresponding XML and JSON encodings. The syntax of YANG statements +is defined in . -
    +
    Leaf Nodes A leaf instance contains simple data like an integer or a string. It has @@ -790,7 +578,7 @@ exactly one value of a particular type and no child nodes. YANG Example: - XML Encoding Example: - my.example.com + ]]> + JSON Encoding Example: + -The "leaf" statement is covered in . +The "leaf" statement is covered in .
    -
    +
    Leaf-List Nodes A leaf-list defines a sequence of values of a particular type. @@ -815,7 +607,7 @@ A leaf-list defines a sequence of values of a particular type. YANG Example: - XML Encoding Example: - high.example.com low.example.com everywhere.example.com + ]]> + JSON Encoding Example: + -The "leaf‑list" statement is covered in . +The "leaf‑list" statement is covered in .
    -
    +
    Container Nodes A container is used to group related nodes in a subtree. A @@ -845,7 +645,7 @@ leaf‑lists, actions, and notifications). YANG Example: - XML Encoding Example: - Good morning + ]]> + JSON Encoding Example: + -The "container" statement is covered in . +The "container" statement is covered in .
    -
    +
    List Nodes A list defines a sequence of list entries. Each entry is like a @@ -882,7 +692,7 @@ leafs, lists, containers, etc.). YANG Example: - XML Encoding Example: - glocks Goldie Locks @@ -916,16 +726,36 @@ XML Encoding Example: tower ]]> - -The "list" statement is covered in . + JSON Encoding Example: + + +The "list" statement is covered in .
    -
    +
    Example Module These statements are combined to define the module: -
    -
    +
    Configuration and State Data YANG can model state data, as well as configuration data, based on the @@ -993,7 +823,7 @@ for the state data. In this example, two leafs are defined for each interface, a configured speed and an observed speed. - -The "config" statement is covered in . +The "config" statement is covered in .
    -
    +
    Built-In Types YANG has a set of built-in types, similar to those of many programming languages, but with some differences due to special requirements of network management. The following table summarizes the built-in -types discussed in : +types discussed in : - +
    @@ -1113,10 +943,10 @@ types discussed in :
    Name
    -The "type" statement is covered in . +The "type" statement is covered in .
    -
    +
    Derived Types (typedef) YANG can define derived types from base types using the "typedef" @@ -1129,7 +959,7 @@ A derived type can be used as the argument for the "type" statement. YANG Example: - XML Encoding Example: - 20 ]]> + JSON Encoding Example: + -The "typedef" statement is covered in . +The "typedef" statement is covered in .
    -
    +
    Reusable Node Groups (grouping) Groups of nodes can be assembled into reusable collections using the @@ -1160,7 +994,7 @@ instantiated with the "uses" statement. YANG Example: - XML Encoding Example: -
    2001:db8::2
    @@ -1189,11 +1023,20 @@ XML Encoding Example:     ]]>     + JSON Encoding Example: + The grouping can be refined as it is used, allowing certain statements to be overridden. In this example, the description is refined: - -The "grouping" statement is covered in . +The "grouping" statement is covered in .
    -
    +
    Choices YANG allows the data model to segregate incompatible nodes into @@ -1247,7 +1090,7 @@ existing in the configuration. YANG Example: - XML Encoding Example: - ]]> + JSON Encoding Example: + -The "choice" statement is covered in . +The "choice" statement is covered in .
    -
    +
    Extending Data Models (augment) YANG allows a module to insert additional nodes into data models, @@ -1304,7 +1154,7 @@ contains the additional nodes. YANG Example: - -If a module augments another module, the XML elements that are added +If a module augments another module, the nodes that are added to the encoding are in the namespace of the augmenting module. For example, if the above augmentation were in a module with prefix -"other", the XML would look like: +"other", the encoding would look like: XML Encoding Example: - alicew Alice N. Wonderland @@ -1335,11 +1185,20 @@ XML Encoding Example: 1024 ]]> + JSON Encoding Example: + -The "augment" statement is covered in . +The "augment" statement is covered in .
    -
    +
    Operation Definitions YANG allows the definition of operations. The operations' names, input @@ -1352,7 +1211,7 @@ container or list data node. Such operations are defined with the YANG Example for an operation at the top level: - NETCONF XML Example: - @@ -1384,10 +1243,37 @@ NETCONF XML Example: ]]> + RESTCONF JSON Example: (see for details) + YANG Example for an operation tied to a list data node: - NETCONF XML Example: - @@ -1431,12 +1317,39 @@ NETCONF XML Example: 60 ]]> + RESTCONF JSON Example: (see for details) + -The "rpc" statement is covered in , and -the "action" statement is covered in . +The "rpc" statement is covered in , and +the "action" statement is covered in .
    -
    +
    Notification Definitions YANG allows the definition of notifications. YANG data definition @@ -1445,7 +1358,7 @@ statements are used to model the content of the notification. YANG Example: - NETCONF XML Example: - 2007-09-01T10:00:00Z @@ -1476,15 +1389,56 @@ NETCONF XML Example: ]]> + RESTCONF JSON SSE Example: (see for details) + -The "notification" statement is covered in . +The "notification" statement is covered in .
    +
    + Protocols Mappings + YANG data models are often conveyed by network management protocols, + expressing both the operations that can be performed and the content + conveyed by the operations. This section discusses the + behavior expected by protocols. +
    + Basic Conformance + For YANG data models having "config false" data nodes, there MUST be a way for + clients to get the "config false" data. + For YANG data models having "config true" data nodes, there MUST be a way for + clients to get and edit the "config true" data. For data models having + "ordered-by user" statements, there MUST be a way for clients to control the + order. + For YANG data models having "rpc" and "action" statements, there MUST be a way + for clients invoke the operation with the "input" data, if any, and get back + either "output" data, if any, or an error message, if needed. For errors, + an "rpc-error" containing the "error-tag", "error-message", and "error-app-tag" + values defined in this document MUST be supported. + For YANG data models having "notification" statements, there MUST be a way for + clients to receive notifications. +
    +
    + YANG 2.0 Conformance + This section specifies what behavior a server claiming to support YANG 2.0 must support. + Nothing yet... +
    +
    -
    +
    Language Concepts -
    +
    Modules and Submodules The module is the base unit of definition in YANG. A module defines a @@ -1563,9 +1517,9 @@ 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 . +"identifier‑ref" in . -
    +
    Import and Include by Revision Published modules evolve independently over time. In order to allow @@ -1589,7 +1543,7 @@ revision. For example, module "b" imports module "a". -
    -
    +
    Module Hierarchies YANG allows modeling of data in multiple hierarchies, where data may @@ -1635,111 +1589,46 @@ have more than one top-level node. Each top-level data node in a module defines a separate hierarchy. Models that have multiple top‑level nodes are sometimes convenient and are supported by YANG. -
    - NETCONF XML Encoding - -NETCONF is capable of carrying any XML content as the payload in the -<config> and <data> elements. The top-level nodes of YANG modules are -encoded as child elements, in any order, within these elements. This -encapsulation guarantees that the corresponding NETCONF messages are -always well-formed XML documents. - - -For example, an instance of: - - - -could be encoded in NETCONF as: - - - - - - - - - - - - - - - - - ]]> -
    -
    +
    File Layout YANG modules and submodules are typically stored in files, one "module" or "submodule" statement per file. The name of the file SHOULD be of the form: - "module‑or‑submodule‑name" is the name of the module or submodule, and the optional "revision‑date" is the latest revision of the module or -submodule, as defined by the "revision" statement (). +submodule, as defined by the "revision" statement (). The file extension ".yang" denotes that the contents of the file are -written with YANG syntax (), and ".yin" +written with YANG syntax (), and ".yin" denotes that the contents of the file are written with -YIN syntax (). +YIN syntax (). YANG parsers can find imported modules and included submodules via this convention.
    -
    - XML Namespaces +
    + Namespaces All YANG definitions are specified within a module. Each module is -bound to a distinct XML namespace , which is a globally -unique URI . A NETCONF client or server uses the namespace -during XML encoding of data. - - -XML namespaces for modules published in RFC streams -MUST be assigned by IANA; see Section 14 in . +bound to a distinct namespace. Network management protocols, such +as NETCONF or RESTCONF, uses the namespace during encoding of data. -XML namespaces for private modules are assigned by the organization -owning the module without a central registry. Namespace URIs MUST be -chosen so they cannot collide with standard or other enterprise -namespaces -- for example, by using the enterprise or organization name -in the namespace. +The "namespace" statement is covered in . - -The "namespace" statement is covered in . - -
    - YANG XML Namespace - -YANG defines an XML namespace for NETCONF <edit‑config> operations, -<error‑info> content, and the <action> element. The name of this -namespace is "urn:ietf:params:xml:ns:yang:1". - -
    -
    +
    Resolving Grouping, Type, and Identity Names Grouping, type, and identity names are resolved in the context in @@ -1756,7 +1645,7 @@ resolved in the context of the original module, not the second module. There is no ambiguity if both modules define the type.
    -
    +
    Nested Typedefs and Groupings Typedefs and groupings may appear nested under many YANG statements, @@ -1794,7 +1683,7 @@ matching "typedef" or "grouping" statement among the immediate substatements of each ancestor statement.
    -
    +
    Conformance Conformance to a model is a measure of how accurately a server follows the @@ -1827,7 +1716,7 @@ deviations from the model We will consider each of these in sequence. -
    +
    Basic Behavior The model defines a contract between a YANG-based client and server; @@ -1836,7 +1725,7 @@ the syntax and semantics behind the modeled data. The strength of YANG lies in the strength of this contract.
    -
    +
    Optional Features In many models, the modeler will allow sections of the model to be @@ -1873,10 +1762,10 @@ the module that are conditional to the feature are noted by the "if‑feature" statement. -Further details are available in . +Further details are available in .
    -
    +
    Deviations In an ideal world, all servers would be required to implement the @@ -1903,49 +1792,10 @@ The contents of the statement detail the manner in which the server implementation deviates from the contract as defined in the module. -Further details are available in . - -
    -
    - 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 MUST announce the modules it implements (see -) by implementing the YANG module -"ietf‑yang‑library" defined in - and listing all implemented modules in -the "/modules‑state/module" list. - - -The server also MUST advertise the following capability in the <hello> -message (line breaks and whitespaces are used for formatting reasons -only): - - &module-set-id= - ]]> - -The parameter "revision" has the same value as the revision date of -the "ietf‑yang‑library" module implemented by the server. This -parameter MUST be present. - - -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. +Further details are available in .
    -
    +
    Implementing a Module A server implements a module if it implements the module's data nodes, @@ -1966,7 +1816,7 @@ If a server implements a module A that imports a module C without specifying the revision date of module C and the server does not implement C (e.g., if C only defines some typedefs), the server MUST list module C in the "/modules‑state/module" list from -"ietf‑yang‑library" , and it MUST set +"ietf‑yang‑library" , and it MUST set the leaf "conformance‑type" to "import" for this module. @@ -1984,7 +1834,7 @@ implemented in a server. For example, with these modules: - - ee1ecb017370cafd @@ -2123,7 +1973,7 @@ The following XML encoding example shows valid data for the ]]>
    -
    +
    Datastore Modification Data models may allow the server to alter the configuration datastore @@ -2135,10 +1985,10 @@ changes are allowed is out of scope for this specification.
    -
    +
    YANG Syntax -The YANG syntax is similar to that of SMIng and +The YANG syntax is similar to that of SMIng 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 @@ -2147,25 +1997,25 @@ syntax. Legal characters in YANG modules are the Unicode and ISO/IEC 10646 - characters, including tab, carriage return, and line feed + 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 . +the rule "yang‑char" in . YANG modules and submodules are stored in files using the UTF-8 - character encoding. + character encoding. Lines in a YANG module end with a carriage return-line feed combination or with a line feed alone. A carriage return that is not followed by a line feed may only appear inside a quoted string -(). Note that carriage returns and line feeds that appear +(). Note that carriage returns and line feeds that appear inside quoted strings become part of the value of the string without modification; the value of a multi-line quoted string contains the same form of line ends as those lines of the YANG module. -
    +
    Lexical Tokenization YANG modules are parsed as a series of tokens. This section details @@ -2175,7 +2025,7 @@ driven by a need to keep the parsers easy to implement, while the power is driven by the fact that modelers need to express their models in readable formats. -
    +
    Comments Comments are C++ style. A single line comment starts with "//" and @@ -2183,22 +2033,22 @@ ends at the end of the line. A block comment starts with "/*" and ends with the nearest following "*/". -Note that inside a quoted string (), these character +Note that inside a quoted string (), these character pairs are never interpreted as the start or end of a comment.
    -
    +
    Tokens A token in YANG is either a keyword, a string, a semicolon (";"), or braces ("{" or "}"). A string can be quoted or unquoted. A keyword is either one of the YANG keywords defined in this document, or a prefix identifier, followed by a colon (":"), followed by a language extension -keyword. Keywords are case sensitive. See for a formal +keyword. Keywords are case sensitive. See for a formal definition of identifiers.
    -
    +
    Quoting An unquoted string is any sequence of characters that does not contain @@ -2237,7 +2087,7 @@ Within a double-quoted string (enclosed within " "), a backslash character introduces a representation of a special character, which depends on the character that immediately follows the backslash: - -
    +
    Quoting Examples The following strings are equivalent: - The following examples show some special strings: - The following examples show some illegal strings: - The following strings are equivalent: -
    -
    +
    Identifiers Identifiers are used to identify different kinds of YANG items by @@ -2309,10 +2159,10 @@ 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. The identifier syntax is formally defined by the rule -"identifier" in . Identifiers can be specified as quoted or +"identifier" in . Identifiers can be specified as quoted or unquoted strings. -
    +
    Identifiers and Their Namespaces Each identifier is valid in a namespace that depends on the type of @@ -2386,7 +2236,7 @@ Forward references are allowed in YANG.
    -
    +
    Statements A YANG module contains a sequence of statements. Each statement @@ -2394,18 +2244,18 @@ starts with a keyword, followed by zero or one argument, followed by either a semicolon (";") or a block of substatements enclosed within braces ("{ }"): - -The argument is a string, as defined in . +The argument is a string, as defined in . -
    +
    Language Extensions A module can introduce YANG extensions by using the "extension" -keyword (see ). The extensions can be imported by other -modules with the "import" statement (see ). When an imported +keyword (see ). The extensions can be imported by other +modules with the "import" statement (see ). When an imported extension is used, the extension's keyword MUST be qualified using the prefix with which the extension's module was imported. If an extension is used in the module where it is defined, the extension's @@ -2415,7 +2265,7 @@ keyword 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 ) MAY be ignored in its +as an unknown-statement (see ) MAY be ignored in its entirety. Any supported extension MUST be processed in accordance with the specification governing that extension. @@ -2426,23 +2276,23 @@ support the extensions.
    -
    +
    XPath Evaluations -YANG relies on XML Path Language (XPath) 1.0 as a notation for +YANG relies on XML Path Language (XPath) 1.0 as a notation for specifying many inter-node references and dependencies. An implementation is not required to implement an XPath interpreter but MUST ensure that the requirements encoded in the data model are enforced. The manner of enforcement is an implementation decision. The XPath expressions MUST be syntactically correct, and all prefixes used MUST be present in the XPath -context (see ). An implementation may +context (see ). An implementation may choose to implement them by hand, rather than using the XPath expression directly. The data model used in the XPath expressions is the same as that used -in XPath 1.0 , with the same extension for root node -children as used by XSLT 1.0 (see Section 3.1 in ). +in XPath 1.0 , with the same extension for root node +children as used by XSLT 1.0 (see Section 3.1 in ). Specifically, it means that the root node may have any number of element nodes as its children. @@ -2453,9 +2303,9 @@ implementation decision. This means that XPath expressions in YANG modules SHOULD NOT rely on any specific document order. -Numbers in XPath 1.0 are IEEE 754 +Numbers in XPath 1.0 are IEEE 754 double-precision floating-point values; see Section 3.5 -in . This means that some values of int64, +in . This means that some values of int64, uint64, and decimal64 types (see Sections  and ) cannot be exactly @@ -2467,7 +2317,7 @@ may yield unexpected results. For example, consider the following definition: - -
    +
    XPath Context All YANG XPath expressions share the following XPath context @@ -2499,16 +2349,16 @@ statement's prefix for the "namespace" statement's URI. Names without a namespace prefix belong to the same namespace as the identifier of the current node. Inside a grouping, that namespace is affected by where the grouping is used (see -). Inside a typedef, that namespace is affected by +). Inside a typedef, that namespace is affected by where the typedef is referenced. If a typedef is defined and referenced within a grouping, the namespace is affected by where the -grouping is used (see ). +grouping is used (see ).
  • The function library is the core function library defined in - and the functions defined in . + and the functions defined in .
  • @@ -2519,7 +2369,7 @@ The set of variable bindings is empty.
The mechanism for handling unprefixed names is adopted from XPath 2.0 - and helps simplify XPath expressions in YANG. No + and helps simplify XPath expressions in YANG. No ambiguity may ever arise, because YANG node identifiers are always qualified names with a non-null namespace URI. @@ -2600,12 +2450,12 @@ The context node varies with the YANG XPath expression and is specified where the YANG statement with the XPath expression is defined. -
+
Examples Given the following module: - and given the following data tree, specified in XML: - 1 @@ -2661,7 +2511,7 @@ and given the following data tree, specified in XML: The accessible tree for a notification "down" on /a/b[id="2"] is: - 1 @@ -2680,7 +2530,7 @@ The accessible tree for an action invocation of "reset" on ⁠/a⁠/b[id="1"] with the "when" parameter set to "10" would be: - 1 @@ -2697,7 +2547,7 @@ with the "when" parameter set to "10" would be: The accessible tree for the action output of this action is: - 1 @@ -2714,7 +2564,7 @@ The accessible tree for the action output of this action is: The accessible tree for a notification "failure" could be: - 1 @@ -2731,13 +2581,13 @@ The accessible tree for a notification "failure" could be:
-
+
Schema Node Identifier A schema node identifier is a string that identifies a node in the schema tree. It has two forms, "absolute" and "descendant", defined by the rules "absolute‑schema‑nodeid" and "descendant‑schema‑nodeid" -in , respectively. A schema node identifier consists of a +in , respectively. A schema node identifier consists of a path of identifiers, separated by slashes ("/"). In an absolute schema node identifier, the first identifier after the leading slash is any top-level schema node in the local module or in an imported @@ -2754,7 +2604,7 @@ string "/a/b" can be used.
-
+
YANG Statements The following sections describe all of the YANG statements. @@ -2766,33 +2616,33 @@ substatements. For example, the "description" statement does not have any substatements defined in YANG, but the following is legal: - -
+
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 holds detailed module information. The module name -is an identifier (see ). +is an identifier (see ). -Names of modules published in RFC streams -MUST be assigned by IANA; see Section 14 in . +Names of modules published in RFC streams +MUST be assigned by IANA; see Section 14 in . Private module names are assigned by the organization owning the -module without a central registry. See for recommendations +module without a central registry. See for recommendations on how to name modules. A module typically has the following layout: - { // header information @@ -2817,9 +2667,9 @@ A module typically has the following layout: } ]]> -
+
The module's Substatements - +
@@ -2993,44 +2843,54 @@ A module typically has the following layout:
substatement
-
+
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" for YANG modules defined +is a string. It MUST contain the value "2.0" for YANG modules defined based on this specification. A module or submodule that doesn't contain the "yang‑version" statement, or one that contains the value "1", is developed for YANG -version 1, defined in . +version 1, defined in . A module or submodule that +contains the "yang‑version" with value "1.1" is developed +for YANG version 1.1, defined in . -Handling of the "yang‑version" statement for versions other than "1.1" +Handling of the "yang‑version" statement for versions other than "2.0" (the version defined here) is out of scope for this specification. Any document that defines a higher version will need to define the backward compatibility of such a higher version. -For compatibility between YANG versions 1 and 1.1, see . +For compatibility between YANG versions, see .
-
+
The "namespace" Statement - -The "namespace" statement defines the XML namespace that all -identifiers defined by the module are qualified by in the XML -encoding, with the exception of identifiers for data nodes, action -nodes, and notification nodes defined inside a grouping (see -for details). The argument to the "namespace" statement is the URI of -the namespace. - - -See also . - -
-
+ The "namespace" statement defines the XML namespace + , which is a globally unique URI + , that all identifiers defined by the module + are qualified by in the XML encoding , + with the exception of identifiers for data nodes, action nodes, + and notification nodes defined inside a grouping (see + for details). The argument to the "namespace" statement + is the URI of the namespace. See + for details. + For modules published in RFC streams , the + namespace MUST be assigned by IANA; see Section 14 in . + XML namespaces for private modules are assigned by the organization + owning the module without a central registry. Namespace URIs MUST be + chosen so they cannot collide with standard or other enterprise + namespaces -- for example, by using the enterprise or organization name + in the namespace. + +See also . + +
+
The "prefix" Statement The "prefix" statement is used to define the prefix associated with @@ -3038,19 +2898,13 @@ the module and its namespace. The "prefix" statement's argument is the prefix string that is used as a prefix to access a module. The prefix string MAY be used with the module to refer to definitions contained in the module, e.g., "if:ifName". A prefix is an identifier (see -). +). When used inside the "module" statement, the "prefix" statement defines the prefix suggested to be used when this module is imported. -To improve readability of the NETCONF XML, a NETCONF client or server -that generates XML or XPath that uses prefixes SHOULD use the prefix -defined by the module as the XML namespace prefix, unless there is a -conflict. - - 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 @@ -3067,7 +2921,7 @@ All prefixes, including the prefix for the module itself, MUST be unique within the module or submodule.
-
+
The "import" Statement The "import" statement makes definitions from one module available @@ -3115,7 +2969,7 @@ module they are taken. Multiple revisions of the same module can be imported, provided that different prefixes are used. - +
The import's Substatements @@ -3151,7 +3005,7 @@ different prefixes are used.
-
+
The import's "revision-date" Statement The import's "revision‑date" statement is used to specify the @@ -3159,23 +3013,23 @@ version of the module to import.
-
+
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 ). +defined by the "belongs‑to" statement (see ). 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 +For backward compatibility with YANG version 1.1, a submodule is allowed to include another submodule belonging to the same module, but -this is not necessary in YANG version 1.1 (see ). +this is not necessary in YANG version 2.0 (see ). When the optional "revision‑date" substatement is present, the @@ -3187,7 +3041,7 @@ revision of the submodule is included. Multiple revisions of the same submodule MUST NOT be included. - +
The includes's Substatements @@ -3218,7 +3072,7 @@ Multiple revisions of the same submodule MUST NOT be included.
-
+
The "organization" Statement The "organization" statement defines the party responsible for this @@ -3227,7 +3081,7 @@ description of the organization(s) under whose auspices this module was developed.
-
+
The "contact" Statement The "contact" statement provides contact information for the module. @@ -3237,7 +3091,7 @@ module should be sent, such as their name, postal address, telephone number, and electronic mail address.
-
+
The "revision" Statement The "revision" statement specifies the editorial revision history of @@ -3250,9 +3104,9 @@ every published editorial change, a new one SHOULD be added in front of the revisions sequence so that all revisions are in reverse chronological order. -
+
The revision's Substatements - +
@@ -3277,12 +3131,12 @@ chronological order.
substatement
-
+
Usage Example - The following example relies on . + The following example relies on . -
-
+
The "submodule" Statement While the primary unit in YANG is a module, a YANG module can itself @@ -3334,27 +3188,27 @@ and it groups all statements that belong to the submodule together. The "submodule" statement's argument is the name of the submodule, followed by a block of substatements that holds detailed submodule information. The submodule name is an identifier -(see ). +(see ). -Names of submodules published in RFC streams MUST be -assigned by IANA; see Section 14 in . +Names of submodules published in RFC streams MUST be +assigned by IANA; see Section 14 in . Private submodule names are assigned by the organization owning the -submodule without a central registry. See for recommendations +submodule without a central registry. See for recommendations on how to name submodules. A submodule typically has the following layout: - { ]]> - ]]> - @@ -3374,9 +3228,9 @@ A submodule typically has the following layout: } ]]> -
+
The submodule's Substatements - +
@@ -3544,7 +3398,7 @@ A submodule typically has the following layout:
substatement
-
+
The "belongs-to" Statement The "belongs‑to" statement specifies the module to which the submodule @@ -3561,7 +3415,7 @@ 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. - +
The belongs-to's Substatement @@ -3580,9 +3434,9 @@ the prefix.
-
+
Usage Example -
-
+
The "typedef" Statement The "typedef" statement defines a new type that may be used locally in the module or submodule, and by other modules that import from it, -according to the rules in . The new type is called +according to the rules in . The new type is called the "derived type", and the type from which it was derived is called the "base type". All derived types can be traced back to a YANG built-in type. @@ -3637,9 +3491,9 @@ The name of the type MUST NOT be one of the YANG built-in types. If the typedef is defined at the top level of a YANG module or submodule, the name of the type to be defined MUST be unique within the module. -
+
The typedef's Substatements - +
@@ -3687,14 +3541,14 @@ the name of the type to be defined MUST be unique within the module.
substatement
-
+
The typedef's "type" Statement The "type" statement, which MUST be present, defines the base type -from which this type is derived. See for details. +from which this type is derived. See for details.
-
+
The "units" Statement The "units" statement, which is optional, takes as an argument a @@ -3702,7 +3556,7 @@ string that contains a textual definition of the units associated with the type.
-
+
The typedef's "default" Statement The "default" statement takes as an argument a string that contains a @@ -3724,9 +3578,9 @@ derived type or leaf definition MUST specify a new default value compatible with the restrictions.
-
+
Usage Example -
-
+
The "type" Statement The "type" statement takes as an argument a string that is the -name of a YANG built-in type (see ) or a derived type (see -), followed by an optional block of substatements +name of a YANG built-in type (see ) or a derived type (see +), followed by an optional block of substatements that is used to put further restrictions on the type. The restrictions that can be applied depend on the type being restricted. The restriction statements for all built-in types are -described in the subsections of . +described in the subsections of . -
+
The type's Substatements - +
@@ -3822,7 +3676,7 @@ described in the subsections of .
substatement
-
+
The "container" Statement The "container" statement is used to define an interior data node @@ -3835,7 +3689,7 @@ A container node does not have a value, but it has a list of child nodes in the data tree. The child nodes are defined in the container's substatements. -
+
Containers with Presence YANG supports two styles of containers, those that exist only for @@ -3877,13 +3731,13 @@ the server using Secure SHell (SSH) but can also contain any SSH‑related configuration knobs, such as connection rates or retry limits. -The "presence" statement (see ) is used to give semantics to +The "presence" statement (see ) is used to give semantics to the existence of the container in the data tree.
-
+
The container's Substatements - +
@@ -4015,25 +3869,25 @@ the existence of the container in the data tree.
substatement
-
+
The "must" Statement The "must" statement, which is optional, takes as an argument a string -that contains an XPath expression (see ). It is used to +that contains an XPath expression (see ). It is used to formally declare a constraint on valid data. The constraint is -enforced according to the rules in . +enforced according to the rules in . When a datastore is validated, all "must" constraints are conceptually evaluated once for each node in the accessible tree (see -). +). All such constraints MUST evaluate to "true" for the data to be valid. The XPath expression is conceptually evaluated in the following -context, in addition to the definition in : +context, in addition to the definition in :
  • @@ -4070,7 +3924,7 @@ using the standard XPath rules. Note that since all leaf values in the data tree are conceptually -stored in their canonical form (see ), any XPath +stored in their canonical form (see ), any XPath comparisons are done on the canonical value. @@ -4080,9 +3934,9 @@ server. How the evaluation is done in practice is an implementation decision.
-
+
The must's Substatements - +
@@ -4117,25 +3971,27 @@ implementation decision.
substatement
-
+
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. +passed as <error‑message> in the <rpc‑error> returned +by a validator.
-
+
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. +passed as <error‑app‑tag> in the <rpc‑error> returned +by a validator.
-
+
Usage Example of must and error-message -
-
+
The "presence" Statement The "presence" statement assigns a meaning to the presence of a @@ -4171,10 +4027,10 @@ used to give some structure to the data, and it carries no meaning by itself. -See for additional information. +See for additional information.
-
+
The container's Child Node Statements Within a container, the "container", "leaf", "list", "leaf‑list", @@ -4182,74 +4038,12 @@ Within a container, the "container", "leaf", "list", "leaf‑list", define child nodes to the container.
-
- XML Encoding Rules - -A container node is encoded as an XML element. The element's local -name is the container's identifier, and its namespace is the -module's XML namespace (see ). - - -The container's child nodes are encoded as subelements to the -container element. If the container defines RPC or -action input or output parameters, these subelements are encoded in -the same order as they are defined within the "container" statement. -Otherwise, the subelements are encoded in any order. - - -Any whitespace between the subelements to the container is -insignificant, i.e., an implementation MAY insert whitespace -characters between subelements. - - -If a non-presence container does not have any child nodes, the -container may or may not be present in the XML encoding. - -
-
- NETCONF <edit-config> Operations - -Containers can be created, deleted, replaced, and modified through -<edit‑config> by using the "operation" attribute -(see Section 7.2 in ) 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 as follows: - -
    -
  • - -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. - -
    • -
  • - -If the operation is "delete", the node is deleted if it exists. If -the node does not exist, a "data‑missing" error is returned. - -
    • -
-
-
+
Usage Example Given the following container definition: - A corresponding XML instance example: - @@ -4276,32 +4070,21 @@ A corresponding XML instance example: ]]> -Since the <ssh> element is present, SSH is enabled. +A corresponding JSON instance example: + -To delete a container with an <edit‑config>: +Since the <ssh> element is present, SSH is enabled. - - - - - - - - - - - - - - - ]]>
-
+
The "leaf" Statement The "leaf" statement is used to define a leaf node in the schema tree. @@ -4311,7 +4094,7 @@ substatements that holds detailed leaf information. A leaf node has a value, but no child nodes, in the data tree. Conceptually, the value in the data tree is always in the canonical -form (see ). +form (see ). A leaf node exists in zero or one instance in the data tree. @@ -4320,13 +4103,13 @@ A leaf node exists in zero or one instance in the data tree. The "leaf" statement is used to define a scalar variable of a particular built-in or derived type. -
+
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 ): +is not a non-presence container (see ):
  • @@ -4371,9 +4154,9 @@ leaf's default value is the type's default value. In all other cases, the leaf does not have a default value.
-
+
The leaf's Substatements - +
@@ -4451,15 +4234,15 @@ cases, the leaf does not have a default value.
substatement
-
+
The leaf's "type" Statement The "type" statement, which MUST be present, takes as an argument the name of an existing built-in or derived type. The optional substatements -specify restrictions on this type. See for details. +specify restrictions on this type. See for details.
-
+
The leaf's "default" Statement The "default" statement, which is optional, takes as an argument a @@ -4477,7 +4260,7 @@ The "default" statement MUST NOT be present on nodes where The definition of the default value MUST NOT be marked with an "if‑feature" statement. For example, the following is illegal: -
-
+
The leaf's "mandatory" Statement The "mandatory" statement, which is optional, takes as an argument the @@ -4497,7 +4280,7 @@ 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 ): +is not a non-presence container (see ):
  • @@ -4519,60 +4302,15 @@ data tree.
-This constraint is enforced according to the rules in . - -
-
- XML Encoding Rules - -A leaf node is encoded as an XML element. The element's local name is -the leaf's identifier, and its namespace is the module's XML -namespace (see ). - - -The value of the leaf node is encoded to XML according to the type and is -sent as character data in the element. +This constraint is enforced according to the rules in . - -See for an example. - -
-
- NETCONF <edit-config> Operations - -When a NETCONF server processes an <edit‑config> request, the -elements of procedure for the leaf node are as follows: - -
    -
  • - -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. - -
    • -
  • - -If the operation is "delete", the node is deleted if it exists. If -the node does not exist, a "data‑missing" error is returned. - -
    • -
-
+
Usage Example -Given the following "leaf" statement, placed in the previously defined -"ssh" container (see ): +Given the following "leaf" statement: - A corresponding XML instance example: - 2022 ]]> -To set the value of a leaf with an <edit‑config>: +A corresponding JSON instance example: - - - - - - - - - - 2022 - - - - - - +
-
+
The "leaf-list" Statement Where the "leaf" statement is used to define a simple scalar variable @@ -4629,9 +4350,9 @@ The definitions of the default values MUST NOT be marked with an Conceptually, the values in the data tree MUST be in the canonical -form (see ). +form (see ). -
+
Ordering YANG supports two styles for ordering the entries within lists and @@ -4664,23 +4385,23 @@ traffic from trusted interfaces. The choice of order would be crucial. -YANG provides a rich set of facilities within NETCONF's <edit‑config> -operation that allows the order of list entries in user-ordered lists +YANG requires management protocols +allow the order of list entries in user-ordered lists to be controlled. List entries may be inserted or rearranged, positioned as the first or last entry in the list, or positioned before or after another specific entry. -The "ordered‑by" statement is covered in . +The "ordered‑by" statement is covered in .
-
+
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 ): +is not a non-presence container (see ):
  • @@ -4728,9 +4449,9 @@ leaf‑list's default value is one instance of the type's default value. In all other cases, the leaf-list does not have any default values.
-
+
The leaf-list's Substatements - +
@@ -4820,7 +4541,7 @@ In all other cases, the leaf-list does not have any default values.
substatement
-
+
The leaf-list's "default" Statement The "default" statement, which is optional, takes as an argument a @@ -4835,7 +4556,7 @@ The "default" statement MUST NOT be present on nodes where "min‑elements" has a value greater than or equal to one.
-
+
The "min-elements" Statement The "min‑elements" statement, which is optional, takes as an argument @@ -4848,7 +4569,7 @@ If no "min‑elements" statement is present, it defaults to zero. The behavior of the constraint depends on the type of the leaf-list's or list's closest ancestor node in the schema tree that is not a -non‑presence container (see ): +non‑presence container (see ):
  • @@ -4871,10 +4592,10 @@ Otherwise, it is enforced if the ancestor node exists.
The constraint is further enforced according to the rules in -. +.
-
+
The "max-elements" Statement The "max‑elements" statement, which is optional, takes as an argument a @@ -4887,10 +4608,10 @@ If no "max‑elements" statement is present, it defaults to "unbounded". The "max‑elements" constraint is enforced according to the rules in -. +.
-
+
The "ordered-by" Statement The "ordered‑by" statement defines whether the order of entries within @@ -4903,9 +4624,9 @@ This statement is ignored if the list represents state data, RPC output parameters, or notification content. -See for additional information. +See for additional information. -
+
ordered-by system The entries in the list are ordered according to an order determined by @@ -4920,103 +4641,17 @@ possible using simple tools like "diff". This is the default order.
-
+
ordered-by user The entries in the list are ordered according to an order defined by -the user. In NETCONF, this order is controlled by using special XML -attributes in the <edit‑config> request. See for details. +the user. Management protocols MUST allow this order to be controlled.
-
- XML Encoding Rules - -A leaf-list node is encoded as a series of XML elements. Each -element's local name is the leaf-list's identifier, and its namespace -is the module's XML namespace (see ). - - -The value of each leaf-list entry is encoded to XML according to the -type and is sent as character data in the element. - - -The XML elements representing leaf-list entries MUST appear in the -order specified by the user if the leaf-list is "ordered-by user"; -otherwise, the order is implementation dependent. The XML elements -representing leaf-list entries MAY be interleaved with elements for -siblings of the leaf-list, unless the leaf-list defines RPC or action -input or output parameters. - - -See for an example. - -
-
- NETCONF <edit-config> Operations - -Leaf-list entries can be created and deleted, but not modified, -through <edit‑config>, by using the "operation" attribute in the -leaf-list entry's XML element. - - -In an "ordered-by user" leaf-list, the attributes "insert" and "value" -in the YANG XML namespace () can be used to control where -in the leaf-list the entry is inserted. These can be used during -"create" operations to insert a new leaf-list entry, or during "merge" -or "replace" operations to insert a new leaf-list entry or move an -existing one. - - -The "insert" attribute can take the values "first", "last", "before", -and "after". If the value is "before" or "after", the "value" -attribute MUST also be used to specify an existing entry in the -leaf‑list. - - -If no "insert" attribute is present in the "create" operation, it -defaults to "last". - - -If several entries in an "ordered-by user" leaf-list are modified -in the same <edit‑config> request, the entries are modified -one at a time, in the order of the XML elements in the request. - - -In a <copy‑config> or in an <edit‑config> with a "replace" operation -that covers the entire leaf-list, the leaf-list order is the same as -the order of the XML elements in the request. - - -When a NETCONF server processes an <edit‑config> request, the -elements of procedure for a leaf-list node are as follows: - -
    -
  • - -If the operation is "merge" or "replace", the leaf-list entry is -created if it does not exist. - -
    • -
  • - -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. - -
    • -
  • - -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. - -
    • -
-
-
+
Usage Example - A corresponding XML instance example: - alice bob ]]> -To create a new element in this list, using the default <edit‑config> -operation "merge": - - - - - - - - - - - eric - - - - - - - ]]> - -Given the following ordered-by user leaf-list: +A corresponding JSON instance example: - - -The following would be used to insert a new cipher "blowfish‑cbc" after -"3des‑cbc": - - - - - - - - - - - blowfish-cbc - - - - - - +
-
+
The "list" Statement The "list" statement is used to define an interior data node in the @@ -5107,9 +4686,9 @@ block of substatements that holds detailed list information. A list entry is uniquely identified by the values of the list's keys, if defined. -
+
The list's Substatements - +
@@ -5265,7 +4844,7 @@ if defined.
substatement
-
+
The list's "key" Statement The "key" statement, which MUST be present if the list represents @@ -5292,17 +4871,17 @@ the list itself. The key string syntax is formally defined by the rule "key‑arg" in -. +.
-
+
The list's "unique" Statement The "unique" statement is used to put constraints on valid list entries. It takes as an argument a string that contains a space-separated list of schema node identifiers, which MUST be given in the descendant form (see the rule "descendant‑schema‑nodeid" in -). Each such schema node identifier MUST refer to a leaf. +). Each such schema node identifier MUST refer to a leaf. If one of the referenced leafs represents configuration data, then all @@ -5313,18 +4892,18 @@ The "unique" constraint specifies that the combined values of all the leaf instances specified in the argument string, including leafs with default values, MUST be unique within all list entry instances in which all referenced leafs exist or have default values. The -constraint is enforced according to the rules in . +constraint is enforced according to the rules in . The unique string syntax is formally defined by the rule "unique‑arg" -in . +in . -
+
Usage Example With the following list: - the following configuration is not valid: - smtp 192.0.2.1 @@ -5360,7 +4939,7 @@ The following configuration is valid, since the "http" and "ftp" list entries do not have a value for all referenced leafs and are thus not taken into account when the "unique" constraint is enforced: - smtp 192.0.2.1 @@ -5379,7 +4958,7 @@ taken into account when the "unique" constraint is enforced: ]]>
-
+
The list's Child Node Statements Within a list, the "container", "leaf", "list", "leaf‑list", "uses", @@ -5387,269 +4966,54 @@ Within a list, the "container", "leaf", "list", "leaf‑list", "uses", child nodes to the list.
-
- XML Encoding Rules - -A list is encoded as a series of XML elements, one for each entry in -the list. Each element's local name is the list's identifier, and its -namespace is the module's XML namespace (see ). There is -no XML element surrounding the list as a whole. - - -The list's key nodes are encoded as subelements to the list's -identifier element, in the same order as they are defined within the -"key" statement. - - -The rest of the list's child nodes are encoded as subelements to the -list element, after the keys. If the list defines RPC or action input or output -parameters, the subelements are encoded in the same order as they are -defined within the "list" statement. Otherwise, the subelements are -encoded in any order. - - -Any whitespace between the subelements to the list entry is -insignificant, i.e., an implementation MAY insert whitespace -characters between subelements. - - -The XML elements representing list entries MUST appear in the order -specified by the user if the list is "ordered-by user"; -otherwise, the order is implementation dependent. The XML elements -representing list entries MAY be interleaved with elements for siblings -of the list, unless the list defines RPC or action input or output -parameters. - -
-
- NETCONF <edit-config> Operations - -List entries can be created, deleted, replaced, and modified through -<edit‑config> by using the "operation" attribute in the list's XML -element. In each case, the values of all keys are used to -uniquely identify a list entry. If all keys are not specified for a -list entry, a "missing‑element" error is returned. - - -In an "ordered-by user" list, the attributes "insert" and "key" in the -YANG XML namespace () can be used to control where in the -list the entry is inserted. These can be used during "create" -operations to insert a new list entry, or during "merge" or "replace" -operations to insert a new list entry or move an existing one. - - -The "insert" attribute can take the values "first", "last", "before", -and "after". If the value is "before" or "after", the "key" attribute -MUST also be used, to specify an existing element in the list. The -value of the "key" attribute is the key predicates of the full -instance identifier (see ) for the list entry. - - -If no "insert" attribute is present in the "create" operation, it -defaults to "last". - - -If several entries in an "ordered-by user" list are modified -in the same <edit‑config> request, the entries are modified -one at a time, in the order of the XML elements in the request. - - -In a <copy‑config> or in an <edit‑config> with a "replace" operation -that covers the entire list, the list entry order is the same as the -order of the XML elements in the request. - - -When a NETCONF server processes an <edit‑config> request, the -elements of procedure for a list node are as follows: - -
    -
  • - -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. - -
    • -
  • - -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. - -
    • -
-
-
- Usage Example - -Given the following list: - - - -A corresponding XML instance example: - - - fred - admin - Fred Flintstone - - ]]> - -To create a new user "barney": - - - - - - - - - - barney - admin - Barney Rubble - - - - - - ]]> - -To change the type of "fred" to "superuser": - - - - - - - - - - fred - superuser - - - - - - ]]> +
+ Usage Example -Given the following ordered-by user list: +Given the following list: - -The following would be used to insert a new user "barney rubble" after -the user "fred flintstone": +A corresponding XML instance example: - - - - - - - - - barney - rubble - admin - - - - - + + fred + admin + Fred Flintstone + ]]> -The following would be used to move the user "barney rubble" before the user -"fred flintstone": +A corresponding JSON instance example: - - - - - - - - - barney - rubble - - - - - +
-
+
The "choice" Statement The "choice" statement defines a set of alternatives, only one of @@ -5672,9 +5036,9 @@ nodes from all other cases. If a request creates a node from a case, the server will delete any existing nodes that are defined in other cases inside the choice. -
+
The choice's Substatements - +
@@ -5782,7 +5146,7 @@ cases inside the choice.
substatement
-
+
The choice's "case" Statement The "case" statement is used to define branches of the choice. It @@ -5800,7 +5164,7 @@ define child nodes to the case node. The identifiers of all these child nodes MUST be unique within all cases in a choice. For example, the following is illegal: - ) MUST always explicitly include case node +() MUST always explicitly include case node identifiers. The following example: - is equivalent to: - The case identifier MUST be unique within a choice. -
+
The case's Substatements - +
@@ -5930,7 +5294,7 @@ The case identifier MUST be unique within a choice.
substatement
-
+
The choice's "default" Statement The "default" statement indicates if a case should be considered as @@ -5950,7 +5314,7 @@ and nested default cases under the default case are used if none of the nodes under any of the cases are present. -There MUST NOT be any mandatory nodes () directly +There MUST NOT be any mandatory nodes () directly under the default case. @@ -5966,7 +5330,7 @@ value will be used if none of "daily", "time‑of‑day", or "manual" are present. If "daily" is present, the default value for "time‑of‑day" will be used. -
-
+
The choice's "mandatory" Statement The "mandatory" statement, which is optional, takes as an argument the @@ -6010,7 +5374,7 @@ If not specified, the default is "false". 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 ): +non-presence container (see ):
  • @@ -6033,13 +5397,14 @@ Otherwise, it is enforced if the ancestor node exists.
The constraint is further enforced according to the rules in -. +.
-
- XML Encoding Rules - -The choice and case nodes are not visible in XML. +
+ Encoding Rules + + +The choice and case nodes are not visible in encodings. The child nodes of the selected "case" statement MUST be encoded in @@ -6048,12 +5413,12 @@ part of an RPC or action input or output parameter definition. Otherwise, the subelements are encoded in any order.
-
+
Usage Example Given the following choice: - A corresponding XML instance example: - ]]> -To change the protocol from TCP to UDP: +A corresponding JSON instance example: - - - - - - - - - - - - - - +
-
+
The "anydata" Statement The "anydata" statement defines an interior node in the schema tree. @@ -6121,7 +5473,7 @@ notifications where the specific notifications are not known at design time. -An anydata node cannot be augmented (see ). +An anydata node cannot be augmented (see ). An anydata node exists in zero or one instance in the data tree. @@ -6135,9 +5487,9 @@ Since the use of anydata limits the manipulation of the content, the "anydata" statement SHOULD NOT be used to define configuration data. -
+
The anydata's Substatements - +
@@ -6197,60 +5549,12 @@ configuration data.
substatement
-
- XML Encoding Rules - -An anydata node is encoded as an XML element. The element's local name -is the anydata's identifier, and its namespace is the module's XML -namespace (see ). The value of the anydata node is a set -of nodes, which are encoded as XML subelements to the -anydata element. - -
-
- NETCONF <edit-config> Operations - -An anydata node is treated as an opaque chunk of data. This data can -be modified in its entirety only. - - -Any "operation" attributes present on subelements of an anydata node -are ignored by the NETCONF server. - - -When a NETCONF server processes an <edit‑config> request, the -elements of procedure for the anydata node are as follows: - -
    -
  • - -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. - -
    • -
  • - -If the operation is "delete", the node is deleted if it exists. If -the node does not exist, a "data‑missing" error is returned. - -
    • -
-
-
+
Usage Example Given the following "anydata" statement: - The following is a valid encoding of such a list instance: - @@ -6282,7 +5586,7 @@ The following is a valid encoding of such a list instance: ]]>
-
+
The "anyxml" Statement The "anyxml" statement defines an interior node in the schema tree. @@ -6296,7 +5600,7 @@ in RPC replies. An example is the <filter> parameter in the <get‑config> operation in NETCONF. -An anyxml node cannot be augmented (see ). +An anyxml node cannot be augmented (see ). An anyxml node exists in zero or one instance in the data tree. @@ -6312,11 +5616,11 @@ only statement that could model an unknown hierarchy of data. In many cases, this unknown hierarchy of data is actually modeled in YANG, but the specific YANG data model is not known at design time. In these situations, it is RECOMMENDED to use "anydata" -() instead of "anyxml". +() instead of "anyxml". -
+
The anyxml's Substatements - +
@@ -6376,70 +5680,18 @@ situations, it is RECOMMENDED to use "anydata"
substatement
-
- XML Encoding Rules - -An anyxml node is encoded as an XML element. The element's local name -is the anyxml's identifier, and its namespace is the module's XML -namespace (see ). The value of the anyxml node is encoded -as XML content of this element. - - -Note that any XML prefixes used in the encoding are local to each -instance encoding. This means that the same XML may be encoded -differently by different implementations. - -
-
- NETCONF <edit-config> Operations - -An anyxml node is treated as an opaque chunk of data. This data can -be modified in its entirety only. - - -Any "operation" attributes present on subelements of an anyxml node -are ignored by the NETCONF server. - - -When a NETCONF server processes an <edit‑config> request, the -elements of procedure for the anyxml node are as follows: - -
    -
  • - -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. - -
    • -
  • - -If the operation is "delete", the node is deleted if it exists. If -the node does not exist, a "data‑missing" error is returned. - -
    • -
-
-
+
Usage Example Given the following "anyxml" statement: - The following are two valid encodings of the same anyxml value: -

This is very cool. @@ -6454,13 +5706,13 @@ The following are two valid encodings of the same anyxml value: ]]>

-
+
The "grouping" Statement The "grouping" statement is used to define a reusable block of nodes, which may be used locally in the module or submodule, and by other modules that import from it, according to the rules in -. It takes one argument, which is an identifier, +. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed grouping information. @@ -6474,7 +5726,7 @@ programming languages. Once a grouping is defined, it can be referenced in a "uses" -statement (see ). A grouping MUST NOT reference itself, neither +statement (see ). A grouping MUST NOT reference itself, neither directly nor indirectly through a chain of other groupings. @@ -6498,9 +5750,9 @@ it cannot be used in an rpc definition. See Sections  and . -
+
The grouping's Substatements - +
@@ -6602,9 +5854,9 @@ Sections  and
substatement
-
+
Usage Example - and ]]>
-
+
The "uses" Statement The "uses" statement is used to reference a "grouping" @@ -6638,9 +5890,9 @@ until the contents of the grouping are added to the schema tree via a "uses" statement that does not appear inside a "grouping" statement, at which point they are bound to the namespace of the current module. -
+
The uses's Substatements - +
@@ -6694,7 +5946,7 @@ at which point they are bound to the namespace of the current module.
substatement
-
+
The "refine" Statement Some of the properties of each node in the grouping can be refined @@ -6706,7 +5958,7 @@ exactly as it was defined in the grouping. The argument string is a descendant schema node identifier (see -). +). The following refinements can be done: @@ -6772,26 +6024,27 @@ node may get additional "if‑feature" expressions.
  • Any node can get refined extensions, if the extension allows -refinement. See for details. +refinement. See for details.
    • -
    - XML Encoding Rules - +
    + Encoding Rules + + Each node in the grouping is encoded as if it was defined inline, -even if it is imported from another module with another XML +even if it is imported from another module with another namespace.
    -
    +
    Usage Example -To use the "endpoint" grouping defined in in a +To use the "endpoint" grouping defined in in a definition of an HTTP server in some other module, we can do: - A corresponding XML instance example: - extern-web 192.0.2.1 @@ -6814,10 +6067,20 @@ A corresponding XML instance example: ]]> +A corresponding JSON instance example: + + + If port 80 should be the default for the HTTP server, a default can be added: - - The following is an error: -
    -
    +
    The "rpc" Statement The "rpc" statement is used to define an RPC operation. It takes @@ -6869,9 +6132,9 @@ rpc node, a schema node with the name "input" and a schema node with the name "output" are also defined. The nodes "input" and "output" are defined in the module's namespace. -
    +
    The rpc's Substatements - +
    @@ -6931,7 +6194,7 @@ defined in the module's namespace.
    substatement
    -
    +
    The "input" Statement The "input" statement, which is optional, is used to define input @@ -6945,14 +6208,14 @@ If a leaf in the input tree has a "mandatory" statement with the value If a leaf in the input tree has a default value, the server MUST use this value in the same cases as those described in -. In these cases, the server +. In these cases, the server MUST operationally behave as if the leaf was present in the RPC invocation with the default value as its value. If a leaf-list in the input tree has one or more default values, the server MUST use these values in the same cases as those described in -. In these cases, the server MUST +. In these cases, the server MUST operationally behave as if the leaf-list was present in the RPC invocation with the default values as its values. @@ -6964,9 +6227,9 @@ statements for nodes in the input tree are ignored. If any node has a "when" statement that would evaluate to "false", then this node MUST NOT be present in the input tree. -
    +
    The input's Substatements - +
    @@ -7045,7 +6308,7 @@ If any node has a "when" statement that would evaluate to
    substatement
    -
    +
    The "output" Statement The "output" statement, which is optional, is used to define output @@ -7061,14 +6324,14 @@ reply. If a leaf in the output tree has a default value, the client MUST use this value in the same cases as those described in -. In these cases, the client MUST operationally +. In these cases, the client MUST operationally behave as if the leaf was present in the RPC reply with the default value as its value. If a leaf-list in the output tree has one or more default values, the client MUST use these values in the same cases as those described in -. In these cases, the client MUST +. In these cases, the client MUST operationally behave as if the leaf-list was present in the RPC reply with the default values as its values. @@ -7080,9 +6343,9 @@ statements for nodes in the output tree are ignored. If any node has a "when" statement that would evaluate to "false", then this node MUST NOT be present in the output tree. -
    +
    The output's Substatements - +
    @@ -7161,67 +6424,9 @@ If any node has a "when" statement that would evaluate to
    substatement
    -
    - NETCONF XML Encoding Rules - -An rpc node is encoded as a child XML element to the <rpc> element, as -designated by the substitution group "rpcOperation" in . The -element's local name is the rpc's identifier, and its namespace is the -module's XML namespace (see ). - - -Input parameters are encoded as child XML elements to the rpc node's -XML element, in the same order as they are defined within the -"input" statement. - - -If the RPC operation invocation succeeded and no output parameters are -returned, the <rpc‑reply> contains a single <ok/> element -defined in . If output parameters are returned, -they are encoded as child elements to the <rpc‑reply> element -defined in , in the same order as they are -defined within the "output" statement. - -
    -
    - Usage Example - -The following example defines an RPC operation: - - - -A corresponding XML instance example of the complete rpc and rpc‑reply: - - - - 27606-0100 - - - - - - - ]]> -
    -
    -
    + +
    +
    The "action" Statement The "action" statement is used to define an operation connected to a @@ -7259,9 +6464,9 @@ to a node in the datastore, whereas an rpc is not. When an action is invoked, the node in the datastore is specified along with the name of the action and the input parameters. -
    +
    The action's Substatements - +
    @@ -7321,104 +6526,9 @@ the action and the input parameters.
    substatement
    -
    - NETCONF XML Encoding Rules - -When an action is invoked, an element with the local name "action" in -the namespace "urn:ietf:params:xml:ns:yang:1" (see ) -is encoded as a child XML element to the <rpc> element defined in -, as designated by the substitution group "rpcOperation" in -. - - -The <action> element contains a hierarchy of nodes that identifies -the node in the datastore. It MUST contain all containers and list -nodes in the direct path from the top level down to the list or -container containing the action. For lists, all key leafs MUST also -be included. The innermost container or list contains an XML element that -carries the name of the defined action. Within this element, the input -parameters are encoded as child XML elements, in the same order as -they are defined within the "input" statement. - - -Only one action can be invoked in one <rpc>. If more than -one action is present in the <rpc>, the server MUST reply with -a "bad‑element" <error‑tag> in -the <rpc‑error>. - - -If the action operation invocation succeeded and no output parameters are -returned, the <rpc‑reply> contains a single <ok/> element -defined in . If output parameters are returned, -they are encoded as child elements to the <rpc‑reply> element -defined in , in the same order as they are -defined within the "output" statement. - -
    -
    - Usage Example - -The following example defines an action to reset one server at a -server farm: - - - -A corresponding XML instance example of the complete rpc and rpc‑reply: - - - - - apache-1 - - 2014-07-29T13:42:00Z - - - - - - - - 2014-07-29T13:42:12Z - - - ]]> -
    -
    -
    + +
    +
    The "notification" Statement The "notification" statement is used to define a notification. @@ -7456,14 +6566,14 @@ the value "true", the leaf MUST be present in a notification instance. If a leaf in the notification tree has a default value, the client MUST use this value in the same cases as those described in -. In these cases, the client MUST operationally +. In these cases, the client MUST operationally behave as if the leaf was present in the notification instance with the default value as its value. If a leaf-list in the notification tree has one or more default values, the client MUST use these values in the same cases as those described in -. In these cases, the client +. In these cases, the client MUST operationally behave as if the leaf-list was present in the notification instance with the default values as its values. @@ -7471,9 +6581,9 @@ notification instance with the default values as its values. Since the notification tree is not part of any datastore, all "config" statements for nodes in the notification tree are ignored. -
    +
    The notification's Substatements - +
    @@ -7575,115 +6685,9 @@ statements for nodes in the notification tree are ignored.
    substatement
    -
    - NETCONF XML Encoding Rules - -A notification node that is defined on the top level of a module is -encoded as a child XML element to the <notification> element defined -in "NETCONF Event Notifications" . -The element's local name is the notification's identifier, and -its namespace is the module's XML namespace (see ). - - -When a notification node is defined as a child to a data node, the -<notification> element defined in -contains a hierarchy of nodes that identifies the node in -the datastore. It MUST contain all containers and list nodes from the -top level down to the list or container containing the notification. -For lists, all key leafs MUST also be included. The innermost -container or list contains an XML element that carries the name of the -defined notification. - - -The notification's child nodes are encoded as subelements to the -notification node's XML element, in any order. - -
    -
    - Usage Example - -The following example defines a notification at the top level of a -module: - - - -A corresponding XML instance example of the complete notification: - - - 2008-07-08T00:01:00Z - - fault - - /ex:interface[ex:name='Ethernet0'] - - major - - - ]]> - -The following example defines a notification in a data node: - - - -A corresponding XML instance example of the complete notification: - - - 2008-07-08T00:01:00Z - - - eth1 - - fred - - - - - ]]> -
    -
    -
    + +
    +
    The "augment" Statement The "augment" statement allows a module or submodule to add to a @@ -7697,12 +6701,12 @@ in the substatements that follow the "augment" statement. The argument string is a schema node identifier (see -). If the "augment" statement is on the top level in +). If the "augment" statement is on the top level in a module or submodule, the absolute form (defined by the rule -"absolute‑schema‑nodeid" in ) of a schema node identifier +"absolute‑schema‑nodeid" in ) of a schema node identifier MUST be used. If the "augment" statement is a substatement to the "uses" statement, the descendant form (defined by the rule -"descendant‑schema‑nodeid" in ) MUST be used. +"descendant‑schema‑nodeid" in ) MUST be used. If the target node is a container, list, case, input, output, or @@ -7717,7 +6721,7 @@ statement. If the target node is a choice node, the "case" statement or a -shorthand "case" statement (see ) can be +shorthand "case" statement (see ) can be used within the "augment" statement. @@ -7725,7 +6729,7 @@ The "augment" statement MUST NOT add multiple nodes with the same name from the same module to the target node. -If the augmentation adds mandatory nodes (see ) that +If the augmentation adds mandatory nodes (see ) that represent configuration to a target node in another module, the augmentation MUST be made conditional with a "when" statement. Care must be taken when defining the "when" expression so that clients that do @@ -7738,7 +6742,7 @@ with "mandatory‑leaf" because the augmentation depends on support for would never select this type and would therefore not be adding a mandatory data node. - -
    +
    The augment's Substatements - +
    @@ -7872,24 +6876,25 @@ data node.
    substatement
    -
    - XML Encoding Rules - -All data nodes defined in the "augment" statement are defined as XML -elements in the XML namespace of the module where the "augment" is + +
    Usage Example In namespace urn:example:interface-module, we have: - Then, in namespace urn:example:ds0, we have: - A corresponding XML instance example: - @@ -7944,11 +6949,32 @@ A corresponding XML instance example: ]]> +A corresponding JSON instance example: + + + As another example, suppose we have the choice defined in -. The following construct can be used to extend the +. The following construct can be used to extend the protocol definition: - A corresponding XML instance example: - @@ -7970,16 +6996,36 @@ A corresponding XML instance example: or - ]]> + +A corresponding JSON instance example: + + + +or + +
    -
    +
    The "identity" Statement The "identity" statement is used to define a new globally unique, @@ -7991,12 +7037,12 @@ It is followed by a block of substatements that holds detailed identity information. -The built-in datatype "identityref" (see ) can be used to +The built-in datatype "identityref" (see ) can be used to reference identities within a data model. -
    +
    The identity's Substatements - +
    @@ -8038,7 +7084,7 @@ reference identities within a data model.
    substatement
    -
    +
    The "base" Statement The "base" statement, which is optional, takes as an argument a string @@ -8076,9 +7122,9 @@ and C is derived from B, then C is also derived from A.
    -
    +
    Usage Example -
    -
    +
    The "extension" Statement The "extension" statement allows the definition of new statements @@ -8152,16 +7198,16 @@ extension are defined by the "extension" statement, using some mechanism outside the scope of this specification. Syntactically, the substatements MUST be YANG statements, including extensions defined using "extension" statements. YANG statements in extensions -MUST follow the syntactical rules in . +MUST follow the syntactical rules in . -An extension can allow refinement (see ) and deviations -(), but the mechanism for how this is defined is outside the +An extension can allow refinement (see ) and deviations +(), but the mechanism for how this is defined is outside the scope of this specification. -
    +
    The extension's Substatements - +
    @@ -8197,7 +7243,7 @@ scope of this specification.
    substatement
    -
    +
    The "argument" Statement The "argument" statement, which is optional, takes as an argument a @@ -8210,9 +7256,9 @@ The argument's name is used in the YIN mapping, where it is used as an XML attribute or element name, depending on the argument's "yin‑element" statement. -
    +
    The argument's Substatement - +
    @@ -8230,25 +7276,25 @@ statement.
    substatement
    -
    +
    The "yin-element" Statement The "yin‑element" statement, which is optional, takes as an argument the string "true" or "false". This statement indicates whether the argument is mapped to an XML element in YIN or to an XML attribute -(see ). +(see ). If no "yin‑element" statement is present, it defaults to "false".
    -
    +
    Usage Example To define an extension: - To use the extension: -
    -
    +
    Conformance-Related Statements This section defines statements related to conformance, as described -in . +in . -
    +
    The "feature" Statement The "feature" statement is used to define a mechanism by which portions of the schema are marked as conditional. A feature name is defined that can later be referenced using the "if‑feature" statement -(see ). Schema nodes tagged with an "if‑feature" +(see ). Schema nodes tagged with an "if‑feature" statement are ignored by the server unless the server supports the given feature expression. This allows portions of the YANG module to be conditional based on conditions in the server. The model can @@ -8304,7 +7350,7 @@ richer model that allows for differing server abilities and roles. The argument to the "feature" statement is the name of the new -feature and follows the rules for identifiers in . This +feature and follows the rules for identifiers in . This name is used by the "if‑feature" statement to tie the schema nodes to the feature. @@ -8316,7 +7362,7 @@ conditional on the presence of some sort of local storage. If the server does not report that it supports this feature, the "local‑storage‑limit" node is not supported. - -
    +
    The feature's Substatements - +
    @@ -8395,7 +7441,7 @@ features.
    substatement
    -
    +
    The "if-feature" Statement The "if‑feature" statement makes its parent statement conditional. @@ -8407,7 +7453,7 @@ implemented by servers where the boolean expression evaluates to The if-feature boolean expression syntax is formally defined by the -rule "if‑feature‑expr" in . Parentheses are used to group +rule "if‑feature‑expr" in . Parentheses are used to group expressions. When the expression is evaluated, the order of precedence is (highest precedence first): grouping (parentheses), "not", "and", "or". @@ -8422,14 +7468,14 @@ name MUST be defined in the current module or an included submodule. A leaf that is a list key MUST NOT have any "if‑feature" statements. -
    +
    Usage Example In this example, the container "target" is implemented if either the "outbound‑tls" or "outbound‑ssh" feature is supported by the server. - The following examples are equivalent: -
    -
    +
    The "deviation" Statement The "deviation" statement defines a hierarchy of a module that the @@ -8456,7 +7502,7 @@ contents of the "deviation" statement give details about the deviation. The argument string is an absolute schema node identifier (see -). +). Deviations define the way a server or class of servers deviate from @@ -8488,9 +7534,9 @@ by using the "deviation" statement. After applying all deviations announced by a server, in any order, the resulting data model MUST still be valid. -
    +
    The deviation's Substatements - +
    @@ -8520,7 +7566,7 @@ resulting data model MUST still be valid.
    substatement
    -
    +
    The "deviate" Statement The "deviate" statement defines how the server's implementation of the @@ -8549,7 +7595,7 @@ statement. The substatement's keyword MUST match a corresponding keyword in the target node, and the argument's string MUST be equal to the corresponding keyword's argument string in the target node. - +
    The deviate's Substatements @@ -8618,16 +7664,16 @@ the corresponding keyword's argument string in the target node. If the target node has a property defined by an extension, this property can be deviated if the extension allows deviations. See - for details. + for details. -
    +
    Usage Example In this example, the server is informing client applications that it does not support the "daytime" service in the style of RFC 867. - - In this example, the server limits the number of name servers to 3: - If the original definition is: - a server might remove this "must" constraint by doing: -
    -
    +
    Common Statements This section defines substatements common to several other statements. -
    +
    The "config" Statement The "config" statement takes as an argument the string "true" or @@ -8720,7 +7766,7 @@ If a node has "config" set to "false", no node underneath it can have "config" set to "true".
    -
    +
    The "status" Statement The "status" statement takes as an argument one of the strings "current", @@ -8760,7 +7806,7 @@ definition within the same module. For example, the following is illegal: -
    -
    +
    The "description" Statement The "description" statement takes as an argument a string that @@ -8783,7 +7829,7 @@ RECOMMENDED to choose a language that is widely understood among the community of network administrators who will use the module.
    -
    +
    The "reference" Statement The "reference" statement takes as an argument a string that is a @@ -8794,7 +7840,7 @@ provides additional information relevant to this definition. For example, a typedef for a "uri" data type could look like: -
    -
    +
    The "when" Statement The "when" statement makes its parent data definition statement conditional. The node defined by the parent data definition statement is only valid when the condition specified by the "when" statement is satisfied. The statement's argument is an XPath expression (see -), which is used to formally specify this condition. If the +), which is used to formally specify this condition. If the XPath expression conceptually evaluates to "true" for a particular instance, then the node defined by the parent data definition statement is valid; otherwise, it is not. @@ -8823,11 +7869,11 @@ If a key leaf is defined in a grouping that is used in a list, the "uses" statement MUST NOT have a "when" statement. -See for additional information. +See for additional information. The XPath expression is conceptually evaluated in the following -context, in addition to the definition in : +context, in addition to the definition in :
    • @@ -8885,9 +7931,9 @@ specially written code.
    -
    +
    Constraints -
    +
    Constraints on Data Several YANG statements define constraints on valid data. These @@ -9000,7 +8046,7 @@ lists and leaf-lists, unless the node or any of its ancestors has a The running configuration datastore MUST always be valid.
    -
    +
    Configuration Data Modifications
    • @@ -9019,8 +8065,8 @@ the "when" expression is deleted by the server.
    -
    - NETCONF Constraint Enforcement Model +
    + Constraint Enforcement Model For configuration data, there are three windows when constraints MUST be enforced: @@ -9033,7 +8079,7 @@ during parsing of RPC payloads
  • -during processing of the <edit‑config> operation +during processing of a configuration operation
  • @@ -9045,10 +8091,10 @@ during validation Each of these scenarios is considered in the following sections. -
    +
    Payload Parsing -When content arrives in RPC payloads, it MUST be well-formed XML, +When content arrives in RPC payloads, it MUST be well-formed document, following the hierarchy and content rules defined by the set of models the server implements. @@ -9060,8 +8106,8 @@ leaf, including those defined in the type's "range", "length", and "pattern" properties, the server MUST reply with an "invalid‑value" <error‑tag> in the <rpc‑error>, and with the error‑app‑tag -() and -error‑message () associated with the +() and +error‑message () associated with the constraint, if any exist.
    • @@ -9114,11 +8160,11 @@ element that is not a list whose "ordered‑by" property is
    -
    - NETCONF <edit-config> Processing +
    + Configuration Processing -After the incoming data is parsed, the NETCONF server performs the -<edit‑config> operation by applying the data to the configuration +After the incoming data is parsed, the server performs the +configuration operation by applying the data to the configuration datastore. During this processing, the following errors MUST be detected: @@ -9149,7 +8195,7 @@ with an "unknown‑element" <error‑tag> in the
    -
    +
    Validation When datastore processing is complete, the final contents MUST obey @@ -9163,7 +8209,7 @@ or <validate> operation takes place.
    -
    +
    Built-In Types YANG has a set of built-in types, similar to those of many programming @@ -9180,14 +8226,14 @@ The different built-in types and their derived types allow different kinds of subtyping, namely length and regular expression restrictions of strings (Sections  and ) and range restrictions of -numeric types (). +numeric types (). The lexical representation of a value of a certain type is used -in the XML encoding and when specifying default values +in the encoding and when specifying default values and numerical ranges in YANG modules. -
    +
    Canonical Representation For most types, there is a single canonical representation of the @@ -9197,7 +8243,7 @@ represented as "+17" or "17". Implementations MUST support all lexical representations specified in this document. -When a server sends XML-encoded data, it MUST use the canonical +When a server sends encoded data, it MUST use the canonical form defined in this section. Other encodings may introduce alternate representations. Note, however, that values in the data tree are conceptually stored in the canonical representation as defined in this @@ -9208,12 +8254,11 @@ MUST match the data type's lexical representation, but the exact format is implementation dependent. -Some types have a lexical representation that depends on the encoding, -e.g., the XML context in which they occur. These types do not have a -canonical form. +Some types have a lexical representation that depends on the encoding +These types do not have a canonical form.
    -
    +
    The Integer Built-In Types The integer built-in types are int8, int16, int32, int64, uint8, uint16, @@ -9255,7 +8300,7 @@ represents integer values between 0 and 4294967295, inclusively. represents integer values between 0 and 18446744073709551615, inclusively. -
    +
    Lexical Representation An integer value is lexically represented as an optional sign @@ -9275,14 +8320,14 @@ followed by the character "0", followed by a number of octal digits. Note that if a default value in a YANG module has a leading zero -("0"), it is interpreted as an octal number. In the XML encoding, an +("0"), it is interpreted as an octal number. In the encoding, an integer is always interpreted as a decimal number, and leading zeros are allowed. Examples: -
    -
    +
    Canonical Form The canonical form of a positive integer does not include the sign @@ -9303,13 +8348,13 @@ The canonical form of a positive integer does not include the sign represented as "0".
    -
    +
    Restrictions -All integer types can be restricted with the "range" statement (). +All integer types can be restricted with the "range" statement ().
    -
    +
    The "range" Statement The "range" statement, which is an optional substatement to the "type" @@ -9334,11 +8379,11 @@ values accepted for the type being restricted, respectively. The range expression syntax is formally defined by the rule -"range‑arg" in . +"range‑arg" in . -
    +
    The range's Substatements -
    +
    @@ -9375,9 +8420,9 @@ The range expression syntax is formally defined by the rule
    substatement
    -
    +
    Usage Example -
    -
    +
    The decimal64 Built-In Type The decimal64 built-in type represents a subset of the real numbers, @@ -9410,7 +8455,7 @@ a 64-bit signed integer by a negative power of ten, i.e., expressible as "i x 10^-n" where i is an integer64 and n is an integer between 1 and 18, inclusively. -
    +
    Lexical Representation A decimal64 value is lexically represented as an optional sign @@ -9419,7 +8464,7 @@ followed by a period ('.') as a decimal indicator and a sequence of decimal digits. If no sign is specified, "+" is assumed.
    -
    +
    Canonical Form The canonical form of a positive decimal64 value does not include the sign @@ -9429,14 +8474,14 @@ before and after the decimal point. The value zero is represented as "0.0".
    -
    +
    Restrictions A decimal64 type can be restricted with the "range" statement -(). +().
    -
    +
    The "fraction-digits" Statement The "fraction‑digits" statement, which is a substatement to the @@ -9451,7 +8496,7 @@ argument. The following table lists the minimum and maximum values for each fraction-digit value: - +
    @@ -9553,9 +8598,9 @@ fraction-digit value:
    fraction-digit
    -
    +
    Usage Example -
    -
    +
    The string Built-In Type The string built-in type represents human-readable strings in YANG. Legal characters are the Unicode and ISO/IEC 10646 - characters, including tab, carriage return, and line feed + characters, including tab, carriage return, and line feed but excluding the other C0 control characters, the surrogate blocks, and the noncharacters. The string syntax is formally defined by -the rule "yang‑string" in . +the rule "yang‑string" in . -
    +
    Lexical Representation A string value is lexically represented as character data in -the XML encoding. +the encoding.
    -
    +
    Canonical Form The canonical form is the same as the lexical representation. No Unicode normalization of string values is performed.
    -
    +
    Restrictions -A string can be restricted with the "length" () and "pattern" -() statements. +A string can be restricted with the "length" () and "pattern" +() statements.
    -
    +
    The "length" Statement The "length" statement, which is an optional substatement to the @@ -9626,11 +8671,11 @@ larger than 18446744073709551615. The length expression syntax is formally defined by the rule -"length‑arg" in . +"length‑arg" in . -
    +
    The length's Substatements - +
    @@ -9667,12 +8712,12 @@ The length expression syntax is formally defined by the rule
    substatement
    -
    +
    The "pattern" Statement The "pattern" statement, which is an optional substatement to the "type" statement, takes as an argument a regular expression string, as -defined in . It is used to restrict the built-in type +defined in . It is used to restrict the built-in type "string", or types derived from "string", to values that match the pattern. @@ -9685,9 +8730,9 @@ If a pattern restriction is applied to a type that is already pattern-restricted, values must match all patterns in the base type, in addition to the new patterns. -
    +
    The pattern's Substatements - +
    @@ -9730,7 +8775,7 @@ in addition to the new patterns.
    substatement
    -
    +
    The "modifier" Statement The "modifier" statement, which is an optional substatement to the @@ -9741,12 +8786,12 @@ If a pattern has the "invert‑match" modifier present, the type is restricted to values that do not match the pattern.
    -
    +
    Usage Example With the following typedef: - the following refinement is legal: - and the following refinement is illegal: - With the following type: - the following strings match: - and the following strings do not match: - With the following type: - the following string matches: - and the following strings do not match: -
    -
    +
    The boolean Built-In Type The boolean built-in type represents a boolean value. -
    +
    Lexical Representation The lexical representation of a boolean value is a string with a value of "true" or "false". These values MUST be in lowercase.
    -
    +
    Canonical Form The canonical form is the same as the lexical representation.
    -
    +
    Restrictions A boolean cannot be restricted.
    -
    +
    The enumeration Built-In Type The enumeration built-in type represents values from a set of assigned names. -
    +
    Lexical Representation The lexical representation of an enumeration value is the assigned name string.
    -
    +
    Canonical Form The canonical form is the assigned name string.
    -
    +
    Restrictions -An enumeration can be restricted with one or more "enum" () +An enumeration can be restricted with one or more "enum" () statements, which enumerate a subset of the values for the base type.
    -
    +
    The "enum" Statement The "enum" statement, which is a substatement to the "type" statement, @@ -9896,9 +8941,9 @@ names in the new type MUST be a subset of the base type's set of assigned names. The value of such an assigned name MUST NOT be changed. -
    +
    The enum's Substatements - +
    @@ -9940,7 +8985,7 @@ changed.
    substatement
    -
    +
    The "value" Statement The "value" statement, which is optional, is used to associate an @@ -9972,9 +9017,9 @@ present, in which case the value is the same as in the base type.
    -
    +
    Usage Example - - seven ]]> With the following typedef: - the following refinement is legal: - and the following refinement is illegal: - -
    -
    +
    The bits Built-In Type The bits built-in type represents a bit set. That is, a bits value is @@ -10065,13 +9110,13 @@ names in the new type MUST be a subset of the base type's set of assigned names. The bit position of such an assigned name MUST NOT be changed. -
    +
    Restrictions -A bits type can be restricted with the "bit" () statement. +A bits type can be restricted with the "bit" () statement.
    -
    +
    Lexical Representation The lexical representation of the bits type is a space-separated list @@ -10079,14 +9124,14 @@ of the names of the bits that are set. A zero-length string thus represents a value where no bits are set.
    -
    +
    Canonical Form In the canonical form, the bit values are separated by a single space -character and they appear ordered by their position (see ). +character and they appear ordered by their position (see ).
    -
    +
    The "bit" Statement The "bit" statement, which is a substatement to the "type" statement, @@ -10095,14 +9140,14 @@ specify each assigned named bit of a bits type. It takes as an argument a string that is the assigned name of the bit. It is followed by a block of substatements that holds detailed bit information. The assigned name follows the same syntax rules as an -identifier (see ). +identifier (see ). All assigned names in a bits type MUST be unique. -
    +
    The bit's Substatements - +
    @@ -10144,7 +9189,7 @@ All assigned names in a bits type MUST be unique.
    substatement
    -
    +
    The "position" Statement The "position" statement, which is optional, takes as an argument @@ -10178,12 +9223,12 @@ present, in which case the value is the same as in the base type.
    -
    +
    Usage Example Given the following typedef and leaf: - - disable-nagle ten-mb-only ]]> The following example shows a legal refinement of this type: - and the following refinement is illegal: -
    -
    +
    The binary Built-In Type The binary built-in type represents any binary data, i.e., a sequence of octets. -
    +
    Restrictions -A binary type can be restricted with the "length" () +A binary type can be restricted with the "length" () statement. The length of a binary value is the number of octets it contains.
    -
    +
    Lexical Representation Binary values are encoded with the base64 encoding scheme (see -Section 4 in ). +Section 4 in ).
    -
    +
    Canonical Form The canonical form of a binary value follows the rules of "Base 64 -Encoding" in . +Encoding" in .
    -
    +
    The leafref Built-In Type The leafref built-in type is restricted to the value space of some leaf or leaf-list node in the schema tree and optionally further restricted by corresponding instance nodes in the data tree. The "path" -substatement () is used to identify the referred leaf or +substatement () is used to identify the referred leaf or leaf-list node in the schema tree. The value space of the referring node is the value space of the referred node. -If the "require‑instance" property () is "true", +If the "require‑instance" property () is "true", there MUST exist a node in the data tree, or a node with a default value in use (see Sections  and ), of the referred schema tree leaf or leaf-list node with the same value @@ -10286,7 +9331,7 @@ as the leafref value in a valid data tree. If the referring node represents configuration data and the -"require‑instance" property () is "true", the +"require‑instance" property () is "true", the referred node MUST also represent configuration. @@ -10294,17 +9339,17 @@ There MUST NOT be any circular chains of leafrefs. If the leaf that the leafref refers to is conditional based on one or -more features (see ), then the leaf with the leafref type MUST +more features (see ), then the leaf with the leafref type MUST also be conditional based on at least the same set of features. -
    +
    Restrictions A leafref can be restricted with the "require‑instance" statement -(). +().
    -
    +
    The "path" Statement The "path" statement, which is a substatement to the "type" statement, @@ -10317,7 +9362,7 @@ syntax. Predicates are used only for constraining the values for the key nodes for list entries. Each predicate consists of exactly one equality test per key, and multiple adjacent predicates MAY be present if a list has multiple keys. The syntax is formally defined by the -rule "path‑arg" in . +rule "path‑arg" in . The predicates are only used when more than one key reference is @@ -10333,7 +9378,7 @@ node set MUST be non-empty. The "path" XPath expression is conceptually evaluated in the following -context, in addition to the definition in : +context, in addition to the definition in :
    • @@ -10351,7 +9396,7 @@ which the "path" statement is defined.
    -
    +
    The "require-instance" Statement The "require‑instance" statement, which is a substatement to the @@ -10362,33 +9407,36 @@ If this statement is not present, it defaults to "true". If "require‑instance" is "true", it means that the instance being referred to MUST exist for the data to be valid. This constraint is -enforced according to the rules in . +enforced according to the rules in . If "require‑instance" is "false", it means that the instance being referred to MAY exist in valid data.
    -
    +
    Lexical Representation A leafref value is lexically represented the same way as the leaf it references represents its value.
    -
    +
    Canonical Form The canonical form of a leafref is the same as the canonical form of the leaf it references.
    -
    +
    Usage Example + Instance examples in this secton use the XML encoding. XML is + just one possible encoding. See the for + more information about encodings. With the following list: - the following leafref refers to an existing interface: - An example of a corresponding XML snippet: - eth0 @@ -10431,7 +9479,7 @@ An example of a corresponding XML snippet: The following leafrefs refer to an existing address of an interface: - An example of a corresponding XML snippet: - eth0 up @@ -10477,7 +9525,7 @@ An example of a corresponding XML snippet: The following list uses a leafref for one of its keys. This is similar to a foreign key in a relational database. - An example of a corresponding XML snippet: - eth0 up @@ -10521,7 +9569,7 @@ An example of a corresponding XML snippet: The following notification defines two leafrefs to refer to an existing admin-status: - An example of a corresponding XML notification: - 2008-04-01T00:01:00Z @@ -10551,19 +9599,19 @@ An example of a corresponding XML notification: ]]>
    -
    +
    The identityref Built-In Type The identityref built-in type is used to reference an existing identity -(see ). +(see ). -
    +
    Restrictions An identityref cannot be restricted.
    -
    +
    The identityref's "base" Statement The "base" statement, which is a substatement to the "type" statement, @@ -10581,14 +9629,11 @@ values are further restricted to the set of identities defined in the modules implemented by the server.
    -
    +
    Lexical Representation An identityref is lexically represented as the referred identity's -qualified name as defined in . If the -prefix is not present, the namespace of the identityref is the default -namespace in effect on the element that contains the identityref -value. +namespace qualified name. When an identityref is given a default value using the "default" @@ -10609,20 +9654,23 @@ corresponding "import" statement. Otherwise, the prefix in the string value is the prefix for the current module.
    -
    +
    Canonical Form -Since the lexical form depends on the XML context in which the +Since the lexical form depends on the encoding context in which the value occurs, this type does not have a canonical form. +Specifically, the value may or may not be prefixed. Furthermore, +in some encodings, the prefix used may be locally defined (see +).
    -
    +
    Usage Example -With the identity definitions in and the following +With the identity definitions in and the following module: - - -the following is an example of how the leaf "crypto" can be -encoded, if the value is the "des3" identity defined in -the "des" module: - - des:des3 - ]]> - -Any prefixes used in the encoding are local to each instance encoding. -This means that the same identityref may be encoded differently by -different implementations. For example, the following example encodes -the same leaf as above: - - x:des3 - ]]> - -If the "crypto" leaf's value is instead "aes", -defined in the "example‑my‑crypto" module, it can -be encoded as: - - mc:aes - ]]> - -or, using the default namespace: - - aes - ]]>
    -
    +
    The empty Built-In Type The empty built-in type represents a leaf that does not have any value; @@ -10690,50 +9707,56 @@ it conveys information by its presence or absence. An empty type cannot have a default value. -
    +
    Restrictions An empty type cannot be restricted.
    -
    +
    Lexical Representation Not applicable.
    -
    +
    Canonical Form Not applicable.
    -
    +
    Usage Example With the following leaf: - -the following is an example of a valid encoding if the leaf exists: +the following is an XML example if the leaf exists: - ]]> + +the following is an JSON example if the leaf exists: + +
    -
    +
    The union Built-In Type The union built-in type represents a value that corresponds to one of its member types. -When the type is "union", the "type" statement () MUST be +When the type is "union", the "type" statement () MUST be present. It is repeatedly used to specify each member type of the union. It takes as an argument a string that is the name of a member type. @@ -10742,9 +9765,9 @@ type. A member type can be of any built-in or derived type. -When generating an XML encoding, a value is encoded according to the +When generating an encoding, a value is encoded according to the rules of the member type to which the value belongs. When -interpreting an XML encoding, a value is validated consecutively +interpreting an encoding, a value is validated consecutively against each member type, in the order they are specified in the "type" statement, until a match is found. The type that matched will be the type of the value for the node that was validated, and the @@ -10754,33 +9777,33 @@ encoding is interpreted according to the rules for that type. Any default value or "units" property defined in the member types is not inherited by the union type. -
    +
    Restrictions A union cannot be restricted. However, each member type can be -restricted, based on the rules defined in . +restricted, based on the rules defined in .
    -
    +
    Lexical Representation The lexical representation of a union is a value that corresponds to the representation of any one of the member types.
    -
    +
    Canonical Form The canonical form of a union value is the same as the canonical form of the member type of the value.
    -
    +
    Usage Example The following is a union of an int32 and an enumeration: - Care must be taken when a member type is a leafref where -the "require‑instance" property () is +the "require‑instance" property () is "true". If a leaf of such a type refers to an existing instance, the leaf's value must be revalidated if the target instance is deleted. For example, with the following definitions: - assume that there exists an entry in the filter list with the name -"http" and that the outbound-filter leaf has this value: +"http" and that the outbound-filter leaf has this value. - - http - - http - ]]> If the filter entry "http" is removed, the outbound-filter leaf's value doesn't match the leafref, and the next member type is @@ -10839,7 +9856,7 @@ the resulting configuration would have been valid.
    -
    +
    The instance-identifier Built-In Type The instance-identifier built-in type is used to uniquely identify a @@ -10848,7 +9865,7 @@ particular instance node in the data tree. The syntax for an instance-identifier is a subset of the XPath abbreviated syntax, formally defined by the rule "instance‑identifier" -in . It is used to uniquely identify a node in the data +in . It is used to uniquely identify a node in the data tree. Predicates are used only for specifying the values for the key nodes for list entries, a value of a leaf-list entry, or a positional index for a list without keys. For identifying list entries with keys, @@ -10858,18 +9875,18 @@ is represented as a zero‑length string (""). If the leaf with the instance-identifier type represents configuration -data and the "require‑instance" property () is +data and the "require‑instance" property () is "true", the node it refers to MUST also represent configuration. Such a leaf puts a constraint on valid data. All such leaf nodes MUST reference existing nodes or leaf or leaf-list nodes with their default value in use (see Sections  and ) for the data to be valid. This constraint is enforced according to -the rules in . +the rules in . The "instance‑identifier" XPath expression is conceptually evaluated in the following context, in addition to the definition in -: +:
    • @@ -10878,41 +9895,36 @@ The context node is the root node in the accessible tree.
    -
    +
    Restrictions An instance-identifier can be restricted with the "require‑instance" -statement (). +statement ().
    -
    +
    Lexical Representation An instance-identifier value is lexically represented as a string. All node names in an instance-identifier value MUST be -qualified with explicit namespace prefixes, and these prefixes MUST be -declared in the XML namespace scope in the instance-identifier's XML -element. - - -Any prefixes used in the encoding are local to each instance encoding. -This means that the same instance-identifier may be encoded -differently by different implementations. +namespace qualified. See encoding for details for how to qualify +node names.
    -
    +
    Canonical Form -Since the lexical form depends on the XML context in which the +Since the lexical form depends on the context in which the value occurs, this type does not have a canonical form.
    -
    +
    Usage Example -The following are examples of instance identifiers: +The following are examples of instance identifiers, assuming +the encoding requires a prefix ("ex") on every node name: -
    -
    +
    XPath Functions This document defines two generic XPath functions and five YANG type‑specific XPath functions. The function signatures are specified -with the syntax used in . +with the syntax used in . -
    +
    Function for Node Sets -
    +
    current() - The current() function takes no input parameters and returns a node set with the initial context node as its only member. -
    +
    Usage Example With this list: - -
    -
    +
    Function for Strings -
    +
    re-match() - @@ -11003,15 +10015,15 @@ the regular expression "pattern"; otherwise, it returns "false". The re-match() function checks to see if a string matches a given regular expression. The regular expressions used are the XML Schema regular -expressions . Note that this includes implicit anchoring +expressions . Note that this includes implicit anchoring of the regular expression at the head and tail. -
    +
    Usage Example The expression: - @@ -11020,17 +10032,17 @@ returns "true". To count all logical interfaces called eth0.<number>, do: -
    -
    +
    Function for the YANG Types "leafref" and "instance-identifier" -
    +
    deref() - @@ -11048,16 +10060,16 @@ an empty node set is returned. If the first argument node is of type "leafref", the function returns a node set that contains the nodes that the leafref refers to. Specifically, this set contains the nodes selected by the leafref's -"path" statement () that have the same +"path" statement () that have the same value as the first argument node. If the first argument node is of any other type, an empty node set is returned. -
    +
    Usage Example -
    -
    +
    Functions for the YANG Type "identityref" -
    +
    derived-from() - 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 ) +value is an identity that is derived from (see ) the identity "identity"; otherwise, it returns "false". The parameter "identity" is a string matching the rule -"identifier‑ref" in . If a prefix is present on the +"identifier‑ref" in . If a prefix is present on the identity, it refers to an identity defined in the module that was imported with that prefix, or the local module if the prefix matches the local module's prefix. If no prefix is present, the identity refers to an identity defined in the current module or an included submodule. -
    +
    Usage Example -
    -
    +
    derived-from-or-self() - 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 ) the identity "identity"; otherwise, +(see ) the identity "identity"; otherwise, it returns "false". The parameter "identity" is a string matching the rule -"identifier‑ref" in . If a prefix is present on the +"identifier‑ref" in . If a prefix is present on the identity, it refers to an identity defined in the module that was imported with that prefix, or the local module if the prefix matches the local module's prefix. If no prefix is present, the identity refers to an identity defined in the current module or an included submodule. -
    +
    Usage Example -The module defined in might also have: +The module defined in might also have: - might al
    -
    +
    Function for the YANG Type "enumeration" -
    +
    enum-value() - @@ -11200,12 +10212,12 @@ and returns the enum's integer value. If the "nodes" node set is empty or if the first node in "nodes" is not of type "enumeration", it returns NaN (not a number). -
    +
    Usage Example With this data model: - - = 5] ]]>
    -
    +
    Function for the YANG Type "bits" -
    +
    bit-is-set() - @@ -11255,12 +10267,12 @@ 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". -
    +
    Usage Example If an interface has this leaf: - -
    -
    +
    Updating a Module As experience is gained with a module, it may be desirable to revise @@ -11290,7 +10302,7 @@ client using an original specification and a server using an updated specification. -For any published change, a new "revision" statement () MUST +For any published change, a new "revision" statement () MUST be included in front of the existing "revision" statements. If there are no existing "revision" statements, then one MUST be added to identify the new revision. Furthermore, any necessary changes MUST be @@ -11409,7 +10421,7 @@ and identities may be added.
  • New data definition statements may be added if they do not add -mandatory nodes () to existing nodes or at the +mandatory nodes () to existing nodes or at the top level in a module or submodule, or if they are conditionally dependent on a new feature (i.e., have an "if‑feature" statement that refers to a new feature). @@ -11423,13 +10435,13 @@ A new "case" statement may be added.
  • A node that represented state data may be changed to represent -configuration, provided it is not mandatory (). +configuration, provided it is not mandatory ().
  • An "if‑feature" statement may be removed, provided its node is not -mandatory (). +mandatory ().
  • @@ -11483,39 +10495,40 @@ reordered. If new data definition statements are added, they can be added anywhere in the sequence of existing substatements.
    • -
    - Coexistence with YANG Version 1 +
    + Coexistence with YANG Version 1 and 1.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 +A YANG version 2.0 module MUST only include YANG version 2.0 submodules. +A YANG version 1 or 1.1 module MUST NOT include a YANG version 2.0 submodule. -A YANG version 1 module or submodule MUST NOT import a YANG version 1.1 +A YANG version 1 or 1.1 module or submodule MUST NOT import a YANG version 2.0 module by revision. -A YANG version 1.1 module or submodule MAY import a YANG version -1 module by revision. +A YANG version 2.0 module or submodule MAY import a YANG version +1.1 or 1 module by revision. -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 -of these modules (A and B) at the same time. In such cases, a NETCONF -server MUST advertise both modules using the rules defined in -, and SHOULD advertise module A and the +If a YANG version 1 or 1.1 module A imports module B without revision and +module B is updated to YANG version 2.0, a server MAY implement both +of these modules (A and B) at the same time. In such cases, a +server MUST advertise both modules using the rules (see +), 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 . +according to the rules defined in or version 1.1 +according to the rules defined in . 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 +version 1 and version 1.1 modules together with YANG version 2.0 modules. Without +this rule, updating a single module to YANG version 2.0 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. +also be updated to YANG version 2.0, and so on.
    -
    +
    YIN A YANG module can be translated into an alternative XML-based @@ -11535,7 +10548,7 @@ can be utilized. The mapping between YANG and YIN does not modify the information content of the model. Comments and whitespace are not preserved. -
    +
    Formal YIN Definition There is a one-to-one correspondence between YANG keywords and YIN @@ -11556,15 +10569,15 @@ via the "extension" statement. The names of all YIN elements MUST be properly qualified with their namespaces (as specified above) using the standard mechanisms of -, i.e., "xmlns" and "xmlns:xxx" +, i.e., "xmlns" and "xmlns:xxx" attributes. The argument of a YANG statement is represented in YIN as either an XML -attribute or a subelement of the keyword element. defines the +attribute or a subelement of the keyword element. defines the mapping for the set of YANG keywords. For extensions, the argument mapping is specified within the "extension" statement (see -). The following rules hold for arguments: +). The following rules hold for arguments:
    • @@ -11594,7 +10607,7 @@ the order of substatements in YANG. Comments in YANG MAY be mapped to XML comments. - +
      Mapping of Arguments of the YANG Statements @@ -11946,12 +10959,12 @@ Comments in YANG MAY be mapped to XML comments.
      -
      +
      Usage Example The following YANG module: - -where the extension "c‑define" is defined in , is +where the extension "c‑define" is defined in , is translated into the following YIN: -
      -
      +
      YANG ABNF Grammar In YANG, almost all statements are unordered. The ABNF grammar - defines the canonical order. To improve module + defines the canonical order. To improve module readability, it is RECOMMENDED that clauses be entered in this order. @@ -12026,7 +11039,7 @@ This grammar assumes that the scanner replaces YANG comments with a single space character. <CODE BEGINS> file "yang.abnf" - <CODE ENDS>
      -
      +
      NETCONF Error Responses for YANG-Related Errors A number of NETCONF error responses are defined for error cases @@ -13185,14 +12198,14 @@ an "error‑app‑tag" substatement, that overrides the default value specified below. -
      +
      Error Message for Data That Violates a "unique" Statement If a NETCONF operation would result in configuration data where a "unique" constraint is invalidated, the following error MUST be returned: - : Contains an instance identifier that @@ -13204,14 +12217,14 @@ MUST be returned: namespace ("urn:ietf:params:xml:ns:yang:1"). ]]>
      -
      +
      Error Message for Data That Violates a "max-elements" Statement If a NETCONF operation would result in configuration data where a list or a leaf-list would have too many entries, the following error MUST be returned: - @@ -13220,14 +12233,14 @@ This error is returned once, with the error-path identifying the list node, even if there is more than one extra child present.
      -
      +
      Error Message for Data That Violates a "min-elements" Statement If a NETCONF operation would result in configuration data where a list or a leaf-list would have too few entries, the following error MUST be returned: - @@ -13236,7 +12249,7 @@ This error is returned once, with the error-path identifying the list node, even if there is more than one child missing.
      -
      +
      Error Message for Data That Violates a "must" Statement If a NETCONF operation would result in configuration data where the @@ -13245,12 +12258,12 @@ following error MUST be returned, unless a specific "error‑app‑tag" substatement is present for the "must" statement. -
      -
      +
      Error Message for Data That Violates a "require-instance" Statement If a NETCONF operation would result in configuration data where a leaf @@ -13258,19 +12271,19 @@ of type "instance‑identifier" or "leafref" marked with require‑instance "true" refers to an instance that does not exist, the following error MUST be returned: -
      -
      +
      Error Message for Data That Violates a Mandatory "choice" Statement If a NETCONF operation would result in configuration data where no nodes exists in a mandatory choice, the following error MUST be returned: -
      -
      +
      Error Message for the "insert" Operation If the "insert" and "key" or "value" @@ -13289,25 +12302,25 @@ attributes are used in an <edit‑config> for a list or leaf-list node and the "key" or "value" refers to an instance that does not exist, the following error MUST be returned: -
      -
      +
      IANA Considerations This document registers one capability identifier URN from the "Network Configuration Protocol (NETCONF) Capability URNs" registry: -
      -
      +
      Security Considerations This document defines a language with which to write and read @@ -13316,7 +12329,7 @@ security impact on the Internet. The same considerations are relevant as those for the base NETCONF protocol -(see Section 9 in ). +(see Section 9 in ). Data modeled in YANG might contain sensitive information. RPCs @@ -13370,25 +12383,10 @@ compromised. - - - - - Extensible Markup Language (XML) 1.0 (Fifth Edition) - - - - - - - - - - Namespaces in XML 1.0 (Third Edition) @@ -13411,7 +12409,6 @@ compromised. - XML Schema Part 2: Datatypes Second Edition @@ -13425,7 +12422,6 @@ compromised. - XML Path Language (XPath) Version 1.0 @@ -13439,7 +12435,6 @@ compromised. - Information Technology - Universal Multiple-Octet Coded Character Set (UCS) @@ -13451,10 +12446,8 @@ compromised. - Informative References - IEEE Standard for Floating-Point Arithmetic @@ -13466,19 +12459,20 @@ compromised. - + - + + XSL Transformations (XSLT) Version 1.0 @@ -13489,7 +12483,6 @@ compromised. - XML Path Language (XPath) 2.0 (Second Edition) @@ -13518,10 +12511,9 @@ compromised. - -
      +
      Acknowledgements The editor wishes to thank the following individuals, who all provided helpful comments on various draft versions of this document: (sorted by @@ -13532,7 +12524,7 @@ compromised. This document builds on top RFC 7950. Please see that document's "Acknowledgements" section for additional acknowledgements.
      -
      +
      Contributors The following individuals contributed to this document: (sorted by amount of contribution)