Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7950

The YANG 1.1 Data Modeling Language

Pages: 217
Proposed Standard
Errata
Updated by:  8342
Part 8 of 9 – Pages 163 to 183
First   Prev   Next

Top   ToC   RFC7950 - Page 163   prevText

9.10. The identityref Built-In Type

The identityref built-in type is used to reference an existing identity (see Section 7.18).

9.10.1. Restrictions

An identityref cannot be restricted.

9.10.2. The identityref's "base" Statement

The "base" statement, which is a substatement to the "type" statement, MUST be present at least once if the type is "identityref". The argument is the name of an identity, as defined by an "identity" statement. If a prefix is present on the identity name, it refers to an identity defined in the module that was imported with that prefix. Otherwise, an identity with the matching name MUST be defined in the current module or an included submodule. Valid values for an identityref are any identities derived from all the identityref's base identities. On a particular server, the valid values are further restricted to the set of identities defined in the modules implemented by the server.

9.10.3. Lexical Representation

An identityref is lexically represented as the referred identity's qualified name as defined in [XML-NAMES]. 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. When an identityref is given a default value using the "default" statement, the identity name in the default value MAY have a prefix. If a prefix is present on the identity name, it refers to an identity defined in the module that was imported with that prefix, or the prefix for the current module if the identity is defined in the
Top   ToC   RFC7950 - Page 164
   current module or one of its submodules.  Otherwise, an identity with
   the matching name MUST be defined in the current module or one of its
   submodules.

   The string value of a node of type "identityref" in a "must" or
   "when" XPath expression is the referred identity's qualified name
   with the prefix present.  If the referred identity is defined in an
   imported module, the prefix in the string value is the prefix defined
   in the corresponding "import" statement.  Otherwise, the prefix in
   the string value is the prefix for the current module.

9.10.4. Canonical Form

Since the lexical form depends on the XML context in which the value occurs, this type does not have a canonical form.

9.10.5. Usage Example

With the identity definitions in Section 7.18.3 and the following module: module example-my-crypto { yang-version 1.1; namespace "urn:example:my-crypto"; prefix mc; import "example-crypto-base" { prefix "crypto"; } identity aes { base "crypto:crypto-alg"; } leaf crypto { type identityref { base "crypto:crypto-alg"; } } container aes-parameters { when "../crypto = 'mc:aes'"; ... } }
Top   ToC   RFC7950 - Page 165
   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:

     <crypto xmlns:des="urn:example:des">des:des3</crypto>

   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:

     <crypto xmlns:x="urn:example:des">x:des3</crypto>

   If the "crypto" leaf's value is instead "aes", defined in the
   "example-my-crypto" module, it can be encoded as:

     <crypto xmlns:mc="urn:example:my-crypto">mc:aes</crypto>

   or, using the default namespace:

     <crypto>aes</crypto>

9.11. The empty Built-In Type

The empty built-in type represents a leaf that does not have any value; it conveys information by its presence or absence. An empty type cannot have a default value.

9.11.1. Restrictions

An empty type cannot be restricted.

9.11.2. Lexical Representation

Not applicable.

9.11.3. Canonical Form

Not applicable.
Top   ToC   RFC7950 - Page 166

9.11.4. Usage Example

With the following leaf: leaf enable-qos { type empty; } the following is an example of a valid encoding if the leaf exists: <enable-qos/>

9.12. 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 (Section 7.4) 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. A member type can be of any built-in or derived type. When generating an XML 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 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 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.

9.12.1. Restrictions

A union cannot be restricted. However, each member type can be restricted, based on the rules defined in Section 9.

9.12.2. Lexical Representation

The lexical representation of a union is a value that corresponds to the representation of any one of the member types.
Top   ToC   RFC7950 - Page 167

9.12.3. Canonical Form

The canonical form of a union value is the same as the canonical form of the member type of the value.

9.12.4. Usage Example

The following is a union of an int32 and an enumeration: type union { type int32; type enumeration { enum "unbounded"; } } Care must be taken when a member type is a leafref where the "require-instance" property (Section 9.9.3) 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: list filter { key name; leaf name { type string; } ... } leaf outbound-filter { type union { type leafref { path "/filter/name"; } type enumeration { enum default-filter; } } } assume that there exists an entry in the filter list with the name "http" and that the outbound-filter leaf has this value: <filter> <name>http</name> </filter> <outbound-filter>http</outbound-filter>
Top   ToC   RFC7950 - Page 168
   If the filter entry "http" is removed, the outbound-filter leaf's
   value doesn't match the leafref, and the next member type is checked.
   The current value ("http") doesn't match the enumeration, so the
   resulting configuration is invalid.

   If the second member type in the union had been of type "string"
   instead of an enumeration, the current value would have matched, and
   the resulting configuration would have been valid.

9.13. The instance-identifier Built-In Type

The instance-identifier built-in type is used to uniquely identify a 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 Section 14. 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, each predicate consists of one equality test per key, and each key MUST have a corresponding predicate. If a key is of type "empty", it is represented as a zero-length string (""). If the leaf with the instance-identifier type represents configuration data and the "require-instance" property (Section 9.9.3) 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 7.6.1 and 7.7.2) for the data to be valid. This constraint is enforced according to the rules in Section 8. The "instance-identifier" XPath expression is conceptually evaluated in the following context, in addition to the definition in Section 6.4.1: o The context node is the root node in the accessible tree.

9.13.1. Restrictions

An instance-identifier can be restricted with the "require-instance" statement (Section 9.9.3).
Top   ToC   RFC7950 - Page 169

9.13.2. 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.

9.13.3. Canonical Form

Since the lexical form depends on the XML context in which the value occurs, this type does not have a canonical form.

9.13.4. Usage Example

The following are examples of instance identifiers: /* instance-identifier for a container */ /ex:system/ex:services/ex:ssh /* instance-identifier for a leaf */ /ex:system/ex:services/ex:ssh/ex:port /* instance-identifier for a list entry */ /ex:system/ex:user[ex:name='fred'] /* instance-identifier for a leaf in a list entry */ /ex:system/ex:user[ex:name='fred']/ex:type /* instance-identifier for a list entry with two keys */ /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] /* instance-identifier for a list entry where the second key ("enabled") is of type "empty" */ /ex:system/ex:service[ex:name='foo'][ex:enabled=''] /* instance-identifier for a leaf-list entry */ /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] /* instance-identifier for a list entry without keys */ /ex:stats/ex:port[3]
Top   ToC   RFC7950 - Page 170

10. 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 [XPATH].

10.1. Function for Node Sets

10.1.1. current()

node-set current() The current() function takes no input parameters and returns a node set with the initial context node as its only member.
10.1.1.1. Usage Example
With this list: list interface { key "name"; ... leaf enabled { type boolean; } ... } the following leaf defines a "must" expression that ensures that the referred interface is enabled: leaf outgoing-interface { type leafref { path "/interface/name"; } must '/interface[name=current()]/enabled = "true"'; }

10.2. Function for Strings

10.2.1. re-match()

boolean re-match(string subject, string pattern) The re-match() function returns "true" if the "subject" string matches the regular expression "pattern"; otherwise, it returns "false".
Top   ToC   RFC7950 - Page 171
   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 [XSD-TYPES].  Note that this includes implicit
   anchoring of the regular expression at the head and tail.

10.2.1.1. Usage Example
The expression: re-match("1.22.333", "\d{1,3}\.\d{1,3}\.\d{1,3}") returns "true". To count all logical interfaces called eth0.<number>, do: count(/interface[re-match(name, "eth0\.\d+")])

10.3. Function for the YANG Types "leafref" and "instance-identifier"

10.3.1. deref()

node-set deref(node-set nodes) The deref() function follows the reference defined by the first node in document order in the argument "nodes" and returns the nodes it refers to. If the first argument node is of type "instance-identifier", the function returns a node set that contains the single node that the instance identifier refers to, if it exists. If no such node exists, 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 (Section 9.9.2) 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.
Top   ToC   RFC7950 - Page 172
10.3.1.1. Usage Example
list interface { key "name type"; leaf name { ... } leaf type { ... } leaf enabled { type boolean; } ... } container mgmt-interface { leaf name { type leafref { path "/interface/name"; } } leaf type { type leafref { path "/interface[name=current()/../name]/type"; } must 'deref(.)/../enabled = "true"' { error-message "The management interface cannot be disabled."; } } }

10.4. Functions for the YANG Type "identityref"

10.4.1. derived-from()

boolean derived-from(node-set nodes, string identity) The derived-from() function returns "true" if any node in the argument "nodes" is a node of type "identityref" and its value is an identity that is derived from (see Section 7.18.2) the identity "identity"; otherwise, it returns "false". The parameter "identity" is a string matching the rule "identifier-ref" in Section 14. 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.
Top   ToC   RFC7950 - Page 173
10.4.1.1. Usage Example
module example-interface { yang-version 1.1; ... identity interface-type; identity ethernet { base interface-type; } identity fast-ethernet { base ethernet; } identity gigabit-ethernet { base ethernet; } list interface { key name; ... leaf type { type identityref { base interface-type; } } ... } augment "/interface" { when 'derived-from(type, "exif:ethernet")'; // generic Ethernet definitions here } ... }
Top   ToC   RFC7950 - Page 174

10.4.2. derived-from-or-self()

boolean derived-from-or-self(node-set nodes, string identity) The derived-from-or-self() function returns "true" if any node in the argument "nodes" is a node of type "identityref" and its value is an identity that is equal to or derived from (see Section 7.18.2) the identity "identity"; otherwise, it returns "false". The parameter "identity" is a string matching the rule "identifier-ref" in Section 14. 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.
10.4.2.1. Usage Example
The module defined in Section 10.4.1.1 might also have: augment "/interface" { when 'derived-from-or-self(type, "exif:fast-ethernet"); // Fast-Ethernet-specific definitions here }

10.5. Function for the YANG Type "enumeration"

10.5.1. enum-value()

number enum-value(node-set nodes) The enum-value() function checks to see if the first node in document order in the argument "nodes" is a node of type "enumeration" 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).
Top   ToC   RFC7950 - Page 175
10.5.1.1. Usage Example
With this data model: list alarm { ... leaf severity { type enumeration { enum cleared { value 1; } enum indeterminate { value 2; } enum minor { value 3; } enum warning { value 4; } enum major { value 5; } enum critical { value 6; } } } } the following XPath expression selects only alarms that are of severity "major" or higher: /alarm[enum-value(severity) >= 5]

10.6. Function for the YANG Type "bits"

10.6.1. bit-is-set()

boolean bit-is-set(node-set nodes, string bit-name) The bit-is-set() function returns "true" if the first node in document order in the argument "nodes" is a node of type "bits" and its value has the bit "bit-name" set; otherwise, it returns "false".
Top   ToC   RFC7950 - Page 176
10.6.1.1. Usage Example
If an interface has this leaf: leaf flags { type bits { bit UP; bit PROMISCUOUS bit DISABLED; } } the following XPath expression can be used to select all interfaces with the UP flag set: /interface[bit-is-set(flags, "UP")]

11. Updating a Module

As experience is gained with a module, it may be desirable to revise that module. However, changes to published modules are not allowed if they have any potential to cause interoperability problems between a client using an original specification and a server using an updated specification. For any published change, a new "revision" statement (Section 7.1.9) 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 applied to any metadata statements, including the "organization" and "contact" statements (Sections 7.1.7 and 7.1.8). Note that definitions contained in a module are available to be imported by any other module and are referenced in "import" statements via the module name. Thus, a module name MUST NOT be changed. Furthermore, the "namespace" statement MUST NOT be changed, since all XML elements are qualified by the namespace. Obsolete definitions MUST NOT be removed from published modules, since their identifiers may still be referenced by other modules.
Top   ToC   RFC7950 - Page 177
   A definition in a published module may be revised in any of the
   following ways:

   o  An "enumeration" type may have new enums added, provided the old
      enums's values do not change.  Note that inserting a new enum
      before an existing enum or reordering existing enums will result
      in new values for the existing enums, unless they have explicit
      values assigned to them.

   o  A "bits" type may have new bits added, provided the old bit
      positions do not change.  Note that inserting a new bit before an
      existing bit or reordering existing bits will result in new
      positions for the existing bits, unless they have explicit
      positions assigned to them.

   o  A "range", "length", or "pattern" statement may expand the allowed
      value space.

   o  A "default" statement may be added to a leaf that does not have a
      default value (either directly or indirectly through its type).

   o  A "units" statement may be added.

   o  A "reference" statement may be added or updated.

   o  A "must" statement may be removed or its constraint relaxed.

   o  A "when" statement may be removed or its constraint relaxed.

   o  A "mandatory" statement may be removed or changed from "true" to
      "false".

   o  A "min-elements" statement may be removed, or changed to require
      fewer elements.

   o  A "max-elements" statement may be removed, or changed to allow
      more elements.

   o  A "description" statement may be added or changed without changing
      the semantics of the definition.

   o  A "base" statement may be added to an "identity" statement.

   o  A "base" statement may be removed from an "identityref" type,
      provided there is at least one "base" statement left.

   o  New typedefs, groupings, rpcs, notifications, extensions,
      features, and identities may be added.
Top   ToC   RFC7950 - Page 178
   o  New data definition statements may be added if they do not add
      mandatory nodes (Section 3) 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).

   o  A new "case" statement may be added.

   o  A node that represented state data may be changed to represent
      configuration, provided it is not mandatory (Section 3).

   o  An "if-feature" statement may be removed, provided its node is not
      mandatory (Section 3).

   o  A "status" statement may be added, or changed from "current" to
      "deprecated" or "obsolete", or changed from "deprecated" to
      "obsolete".

   o  A "type" statement may be replaced with another "type" statement
      that does not change the syntax or semantics of the type.  For
      example, an inline type definition may be replaced with a typedef,
      but an int8 type cannot be replaced by an int16, since the syntax
      would change.

   o  Any set of data definition nodes may be replaced with another set
      of syntactically and semantically equivalent nodes.  For example,
      a set of leafs may be replaced by a "uses" statement of a grouping
      with the same leafs.

   o  A module may be split into a set of submodules or a submodule may
      be removed, provided the definitions in the module do not change
      in any way other than those allowed here.

   o  The "prefix" statement may be changed, provided all local uses of
      the prefix are also changed.

   Otherwise, if the semantics of any previous definition are changed
   (i.e., if a non-editorial change is made to any definition other than
   those specifically allowed above), then this MUST be achieved by a
   new definition with a new identifier.

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

12. Coexistence with YANG Version 1

A YANG version 1.1 module MUST NOT include a YANG version 1 submodule, and a YANG version 1 module MUST NOT include a YANG version 1.1 submodule. A YANG version 1 module or submodule MUST NOT import a YANG version 1.1 module by revision. A YANG version 1.1 module or submodule MAY import a YANG version 1 module by revision. 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 Section 5.6.4, and SHOULD advertise module A and the latest revision of module B that is specified with YANG version 1 according to the rules defined in [RFC6020]. This rule exists in order to allow implementations of existing YANG version 1 modules together with YANG version 1.1 modules. Without this rule, updating a single module to YANG version 1.1 would have a cascading effect on modules that import it, requiring all of them to also be updated to YANG version 1.1, and so on.

13. YIN

A YANG module can be translated into an alternative XML-based syntax called YIN. The translated module is called a YIN module. This section describes bidirectional mapping rules between the two formats. The YANG and YIN formats contain equivalent information using different notations. The YIN notation enables developers to represent YANG data models in XML and therefore use the rich set of XML-based tools for data filtering and validation, automated generation of code and documentation, and other tasks. Tools like XSLT or XML validators can be utilized. The mapping between YANG and YIN does not modify the information content of the model. Comments and whitespace are not preserved.
Top   ToC   RFC7950 - Page 180

13.1. Formal YIN Definition

There is a one-to-one correspondence between YANG keywords and YIN elements. The local name of a YIN element is identical to the corresponding YANG keyword. This means, in particular, that the document element (root) of a YIN document is always <module> or <submodule>. YIN elements corresponding to the YANG keywords belong to the namespace whose associated URI is "urn:ietf:params:xml:ns:yang:yin:1". YIN elements corresponding to extension keywords belong to the namespace of the YANG module where the extension keyword is declared 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 [XML-NAMES], 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. Table 1 defines the mapping for the set of YANG keywords. For extensions, the argument mapping is specified within the "extension" statement (see Section 7.19). The following rules hold for arguments: o If the argument is represented as an attribute, this attribute has no namespace. o If the argument is represented as an element, it is qualified by the same namespace as its parent keyword element. o If the argument is represented as an element, it MUST be the first child of the keyword element. Substatements of a YANG statement are represented as (additional) children of the keyword element, and their relative order MUST be the same as the order of substatements in YANG. Comments in YANG MAY be mapped to XML comments.
Top   ToC   RFC7950 - Page 181
            +------------------+---------------+-------------+
            | keyword          | argument name | yin-element |
            +------------------+---------------+-------------+
            | action           | name          | false       |
            | anydata          | name          | false       |
            | anyxml           | name          | false       |
            | argument         | name          | false       |
            | augment          | target-node   | false       |
            | base             | name          | false       |
            | belongs-to       | module        | false       |
            | bit              | name          | false       |
            | case             | name          | false       |
            | choice           | name          | false       |
            | config           | value         | false       |
            | contact          | text          | true        |
            | container        | name          | false       |
            | default          | value         | false       |
            | description      | text          | true        |
            | deviate          | value         | false       |
            | deviation        | target-node   | false       |
            | enum             | name          | false       |
            | error-app-tag    | value         | false       |
            | error-message    | value         | true        |
            | extension        | name          | false       |
            | feature          | name          | false       |
            | fraction-digits  | value         | false       |
            | grouping         | name          | false       |
            | identity         | name          | false       |
            | if-feature       | name          | false       |
            | import           | module        | false       |
            | include          | module        | false       |
            | input            | <no argument> | n/a         |
            | key              | value         | false       |
            | leaf             | name          | false       |
            | leaf-list        | name          | false       |
            | length           | value         | false       |
            | list             | name          | false       |
            | mandatory        | value         | false       |
            | max-elements     | value         | false       |
            | min-elements     | value         | false       |
            | modifier         | value         | false       |
            | module           | name          | false       |
            | must             | condition     | false       |
            | namespace        | uri           | false       |
            | notification     | name          | false       |
            | ordered-by       | value         | false       |
            | organization     | text          | true        |
            | output           | <no argument> | n/a         |
Top   ToC   RFC7950 - Page 182
            | path             | value         | false       |
            | pattern          | value         | false       |
            | position         | value         | false       |
            | prefix           | value         | false       |
            | presence         | value         | false       |
            | range            | value         | false       |
            | reference        | text          | true        |
            | refine           | target-node   | false       |
            | require-instance | value         | false       |
            | revision         | date          | false       |
            | revision-date    | date          | false       |
            | rpc              | name          | false       |
            | status           | value         | false       |
            | submodule        | name          | false       |
            | type             | name          | false       |
            | typedef          | name          | false       |
            | unique           | tag           | false       |
            | units            | name          | false       |
            | uses             | name          | false       |
            | value            | value         | false       |
            | when             | condition     | false       |
            | yang-version     | value         | false       |
            | yin-element      | value         | false       |
            +------------------+---------------+-------------+

           Table 1: Mapping of Arguments of the YANG Statements

13.1.1. Usage Example

The following YANG module: module example-foo { yang-version 1.1; namespace "urn:example:foo"; prefix "foo"; import example-extensions { prefix "myext"; } list interface { key "name"; leaf name { type string; }
Top   ToC   RFC7950 - Page 183
         leaf mtu {
           type uint32;
           description "The MTU of the interface.";
           myext:c-define "MY_MTU";
         }
       }
     }

   where the extension "c-define" is defined in Section 7.19.3, is
   translated into the following YIN:

     <module name="example-foo"
             xmlns="urn:ietf:params:xml:ns:yang:yin:1"
             xmlns:foo="urn:example:foo"
             xmlns:myext="urn:example:extensions">

       <namespace uri="urn:example:foo"/>
       <prefix value="foo"/>

       <import module="example-extensions">
         <prefix value="myext"/>
       </import>

       <list name="interface">
         <key value="name"/>
         <leaf name="name">
           <type name="string"/>
         </leaf>
         <leaf name="mtu">
           <type name="uint32"/>
           <description>
             <text>The MTU of the interface.</text>
           </description>
           <myext:c-define name="MY_MTU"/>
         </leaf>
       </list>
     </module>


(next page on part 9)

Next Section