The YANG 1.1 Data Modeling Language

6.3.1. Language Extensions

A module can introduce YANG extensions by using the "extension" keyword (see Section 7.19). The extensions can be imported by other modules with the "import" statement (see Section 7.1.5). When an imported extension is used, the extension's keyword MUST be qualified using the prefix with which the extension's module was imported. If an extension is used in the module where it is defined, the extension's 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 Section 14) MAY be ignored in its entirety. Any supported extension MUST be processed in accordance with the specification governing that extension.¶

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

6.4.1. XPath Context

All YANG XPath expressions share the following XPath context definition:¶

• The set of namespace declarations is the set of all "import" statements' prefix and namespace pairs in the module where the XPath expression is specified, and the "prefix" 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 Section 7.13). 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 Section 7.13).¶

• The function library is the core function library defined in [XPATH] and the functions defined in Section 10.¶

• The set of variable bindings is empty.¶

The mechanism for handling unprefixed names is adopted from XPath 2.0 [XPATH2.0] 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.¶

The accessible tree depends on where the statement with the XPath expression is defined:¶

• If the XPath expression is defined in a substatement to a data node that represents configuration, the accessible tree is the data in the datastore where the context node exists. The root node has all top-level configuration data nodes in all modules as children.¶

• If the XPath expression is defined in a substatement to a data node that represents state data, the accessible tree is all state data in the server, and the running configuration datastore. The root node has all top-level data nodes in all modules as children.¶

• If the XPath expression is defined in a substatement to a "notification" statement, the accessible tree is the notification instance, all state data in the server, and the running configuration datastore. If the notification is defined on the top level in a module, then the root node has the node representing the notification being defined and all top-level data nodes in all modules as children. Otherwise, the root node has all top-level data nodes in all modules as children.¶

• If the XPath expression is defined in a substatement to an "input" statement in an "rpc" or "action" statement, the accessible tree is the RPC or action operation instance, all state data in the server, and the running configuration datastore. The root node has top-level data nodes in all modules as children. Additionally, for an RPC, the root node also has the node representing the RPC operation being defined as a child. The node representing the operation being defined has the operation's input parameters as children.¶

• If the XPath expression is defined in a substatement to an "output" statement in an "rpc" or "action" statement, the accessible tree is the RPC or action operation instance, all state data in the server, and the running configuration datastore. The root node has top-level data nodes in all modules as children. Additionally, for an RPC, the root node also has the node representing the RPC operation being defined as a child. The node representing the operation being defined has the operation's output parameters as children.¶

In the accessible tree, all leafs and leaf-lists with default values in use exist (see Sections 7.6.1 and 7.7.2).¶

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

The context node varies with the YANG XPath expression and is specified where the YANG statement with the XPath expression is defined.¶

  module example-a {
    yang-version 1.1;
    namespace urn:example:a;
    prefix a;

    container a {
      list b {
        key id;
        leaf id {
          type string;
        }
        notification down {
          leaf reason {
            type string;
          }
        }
        action reset {
          input {
            leaf delay {
              type uint32;
            }
          }
          output {
            leaf result {
              type string;
            }
          }
        }
      }
    }
    notification failure {
      leaf b-ref {
        type leafref {
          path "/a/b/id";
        }
      }
    }
  }

  <a xmlns="urn:example:a">
    <b>
      <id>1</id>
    </b>
    <b>
      <id>2</id>
    </b>
  </a>

  <a xmlns="urn:example:a">
    <b>
      <id>1</id>
    </b>
    <b>
      <id>2</id>
      <down>
        <reason>error</reason>
      </down>
    </b>
  </a>
  // possibly other top-level nodes here

  <a xmlns="urn:example:a">
    <b>
      <id>1</id>
      <reset>
        <delay>10</delay>
      </reset>
    </b>
    <b>
      <id>2</id>
    </b>
  </a>
  // possibly other top-level nodes here

  <a xmlns="urn:example:a">
    <b>
      <id>1</id>
      <reset>
        <result>ok</result>
      </reset>
    </b>
    <b>
      <id>2</id>
    </b>
  </a>
  // possibly other top-level nodes here

  <a xmlns="urn:example:a">
    <b>
      <id>1</id>
    </b>
    <b>
      <id>2</id>
    </b>
  </a>
  <failure>
    <b-ref>2</b-ref>
  </failure>
  // possibly other top-level nodes here

7.1.2. The "yang-version" Statement

The "yang‑version" statement specifies which version of the YANG language was used in developing the module. The statement's argument is a string. It MUST contain the value "1.1" 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 [RFC6020].¶

Handling of the "yang‑version" statement for versions other than "1.1" (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 Section 12.¶

7.1.3. 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 Section 7.13 for details). The argument to the "namespace" statement is the URI of the namespace.¶

See also Section 5.3.¶

7.1.4. The "prefix" Statement

The "prefix" statement is used to define the prefix associated with 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 Section 6.2).¶

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 module is used, the prefix string for the imported module followed by a colon (":") and the identifier is used, e.g., "if:ifIndex". To improve readability of YANG modules, the prefix defined by a module SHOULD be used when the module is imported, unless there is a conflict. If there is a conflict, i.e., two different modules that both have defined the same prefix are imported, at least one of them MUST be imported with a different prefix.¶

All prefixes, including the prefix for the module itself, MUST be unique within the module or submodule.¶

7.1.5. The "import" Statement

The "import" statement makes definitions from one module available inside another module or submodule. The argument is the name of the module to import, and the statement is followed by a block of substatements that holds detailed import information. When a module is imported, the importing module may:¶

• use any grouping and typedef defined at the top level in the imported module or its submodules.¶

• use any extension, feature, and identity defined in the imported module or its submodules.¶

• use any node in the imported module's schema tree in "must", "path", and "when" statements, or as the target node in "augment" and "deviation" statements.¶

The mandatory "prefix" substatement assigns a prefix for the imported module that is scoped to the importing module or submodule. Multiple "import" statements may be specified to import from different modules.¶

When the optional "revision‑date" substatement is present, any typedef, grouping, extension, feature, and identity referenced by definitions in the local module are taken from the specified revision of the imported module. It is an error if the specified revision of the imported module does not exist. If no "revision‑date" substatement is present, it is undefined from which revision of the module they are taken.¶

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

7.1.6. The "include" Statement

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

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

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

When the optional "revision‑date" substatement is present, the specified revision of the submodule is included in the module. It is an error if the specified revision of the submodule does not exist. If no "revision‑date" substatement is present, it is undefined which revision of the submodule is included.¶

Multiple revisions of the same submodule MUST NOT be included.¶

7.1.7. The "organization" Statement

The "organization" statement defines the party responsible for this module. The argument is a string that is used to specify a textual description of the organization(s) under whose auspices this module was developed.¶

7.1.8. The "contact" Statement

The "contact" statement provides contact information for the module. The argument is a string that is used to specify contact information for the person or persons to whom technical queries concerning this module should be sent, such as their name, postal address, telephone number, and electronic mail address.¶

7.1.9. The "revision" Statement

The "revision" statement specifies the editorial revision history of the module, including the initial revision. A series of "revision" statements detail the changes in the module's definition. The argument is a date string in the format "YYYY‑MM‑DD", followed by a block of substatements that holds detailed revision information. A module SHOULD have at least one "revision" statement. For 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.¶

7.3.2. The typedef's "type" Statement

The "type" statement, which MUST be present, defines the base type from which this type is derived. See Section 7.4 for details.¶

7.3.3. The "units" Statement

The "units" statement, which is optional, takes as an argument a string that contains a textual definition of the units associated with the type.¶

7.3.4. The typedef's "default" Statement

The "default" statement takes as an argument a string that contains a default value for the new type.¶

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

If the base type has a default value and the new derived type does not specify a new default value, the base type's default value is also the default value of the new derived type.¶

If the type's default value is not valid according to the new restrictions specified in a derived type or leaf definition, the derived type or leaf definition MUST specify a new default value compatible with the restrictions.¶

7.5.1. Containers with Presence

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

In the first style, the container has no meaning of its own, existing only to contain child nodes. In particular, the presence of the container node with no child nodes is semantically equivalent to the absence of the container node. YANG calls this style a "non-presence container". This is the default style.¶

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

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

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

YANG calls this style a "presence container", and it is indicated using the "presence" statement, which takes as its argument a text string indicating what the presence of the node means.¶

For example, an "ssh" container may turn on the ability to log into 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 Section 7.5.5) is used to give semantics to the existence of the container in the data tree.¶

7.5.3. The "must" Statement

The "must" statement, which is optional, takes as an argument a string that contains an XPath expression (see Section 6.4). It is used to formally declare a constraint on valid data. The constraint is enforced according to the rules in Section 8.¶

When a datastore is validated, all "must" constraints are conceptually evaluated once for each node in the accessible tree (see Section 6.4.1).¶

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 Section 6.4.1:¶

• If the "must" statement is a substatement of a "notification" statement, the context node is the node representing the notification in the accessible tree.¶

• If the "must" statement is a substatement of an "input" statement, the context node is the node representing the operation in the accessible tree.¶

• If the "must" statement is a substatement of an "output" statement, the context node is the node representing the operation in the accessible tree.¶

• Otherwise, the context node is the node in the accessible tree for which the "must" statement is defined.¶

The result of the XPath expression is converted to a boolean value using the standard XPath rules.¶

Note that since all leaf values in the data tree are conceptually stored in their canonical form (see Section 9.1), any XPath comparisons are done on the canonical value.¶

Also note that the XPath expression is conceptually evaluated. This means that an implementation does not have to use an XPath evaluator in the server. How the evaluation is done in practice is an implementation decision.¶

7.5.5. The "presence" Statement

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

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

See Section 7.5.1 for additional information.¶

7.5.8. Usage Example

Given the following container definition:¶

  container system {
    description
      "Contains various system parameters.";
    container services {
      description
        "Configure externally available services.";
      container "ssh" {
        presence "Enables SSH";
        description
          "SSH service-specific configuration.";
        // more leafs, containers, and stuff here...
      }
    }
  }

A corresponding XML instance example:¶

  <system>
    <services>
      <ssh/>
    </services>
  </system>

Since the <ssh> element is present, SSH is enabled.¶

To delete a container with an <edit‑config>:¶

  <rpc message-id="101"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
       xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
    <edit-config>
      <target>
        <running/>
      </target>
      <config>
        <system xmlns="urn:example:config">
          <services>
            <ssh nc:operation="delete"/>
          </services>
        </system>
      </config>
    </edit-config>
  </rpc>

7.6.1. The leaf's Default Value

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

• If no such ancestor exists in the schema tree, the default value MUST be used.¶

• Otherwise, if this ancestor is a case node, the default value MUST be used if any node from the case exists in the data tree or the case node is the choice's default case, and if no nodes from any other case exist in the data tree.¶

• Otherwise, the default value MUST be used if the ancestor node exists in the data tree.¶

In these cases, the default value is said to be in use.¶

Note that if the leaf or any of its ancestors has a "when" condition or "if‑feature" expression that evaluates to "false", then the default value is not in use.¶

When the default value is in use, the server MUST operationally behave as if the leaf was present in the data tree with the default value as its value.¶

If a leaf has a "default" statement, the leaf's default value is the value of the "default" statement. Otherwise, if the leaf's type has a default value and the leaf is not mandatory, then the leaf's default value is the type's default value. In all other cases, the leaf does not have a default value.¶

7.6.3. 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 Section 7.4 for details.¶

7.6.4. The leaf's "default" Statement

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

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

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

The definition of the default value MUST NOT be marked with an "if‑feature" statement. For example, the following is illegal:¶

  leaf color {
    type enumeration {
      enum blue { if-feature blue; }
      ...
    }
    default blue; // illegal - enum value is conditional
  }

7.6.5. The leaf's "mandatory" Statement

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

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

• If no such ancestor exists in the schema tree, the leaf MUST exist.¶

• Otherwise, if this ancestor is a case node, the leaf MUST exist if any node from the case exists in the data tree.¶

• Otherwise, the leaf MUST exist if the ancestor node exists in the data tree.¶

This constraint is enforced according to the rules in Section 8.¶

7.6.6. 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.¶

7.6.7. Usage Example

Given the following "leaf" statement, placed in the previously defined "ssh" container (see Section 7.5.8):¶

  leaf port {
    type inet:port-number;
    default 22;
    description
      "The port to which the SSH server listens.";
  }

A corresponding XML instance example:¶

  <port>2022</port>

To set the value of a leaf with an <edit‑config>:¶

  <rpc message-id="101"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
       xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
    <edit-config>
      <target>
        <running/>
      </target>
      <config>
        <system xmlns="urn:example:config">
          <services>
            <ssh>
              <port>2022</port>
            </ssh>
          </services>
        </system>
      </config>
    </edit-config>
  </rpc>

7.7.1. Ordering

YANG supports two styles for ordering the entries within lists and leaf-lists. In many lists, the order of list entries does not impact the implementation of the list's configuration, and the server is free to sort the list entries in any reasonable order. The "description" string for the list may suggest an order to the server implementor. YANG calls this style of list "system ordered"; such lists are indicated with the statement "ordered-by system".¶

For example, a list of valid users would typically be sorted alphabetically, since the order in which the users appeared in the configuration would not impact the creation of those users' accounts.¶

In the other style of lists, the order of list entries matters for the implementation of the list's configuration and the user is responsible for ordering the entries, while the server maintains that order. YANG calls this style of list "user ordered"; such lists are indicated with the statement "ordered-by user".¶

For example, the order in which packet filter entries are applied to incoming traffic may affect how that traffic is filtered. The user would need to decide if the filter entry that discards all TCP traffic should be applied before or after the filter entry that allows all 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 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 Section 7.7.7.¶

7.7.2. The leaf-list's Default Values

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

• If no such ancestor exists in the schema tree, the default values MUST be used.¶

• Otherwise, if this ancestor is a case node, the default values MUST be used if any node from the case exists in the data tree or the case node is the choice's default case, and if no nodes from any other case exist in the data tree.¶

• Otherwise, the default values MUST be used if the ancestor node exists in the data tree.¶

In these cases, the default values are said to be in use.¶

Note that if the leaf-list or any of its ancestors has a "when" condition or "if‑feature" expression that evaluates to "false", then the default values are not in use.¶

When the default values are in use, the server MUST operationally behave as if the leaf-list was present in the data tree with the default values as its values.¶

If a leaf-list has one or more "default" statements, the leaf-list's default values are the values of the "default" statements, and if the leaf-list is user ordered, the default values are used in the order of the "default" statements. Otherwise, if the leaf-list's type has a default value and the leaf-list does not have a "min‑elements" statement with a value greater than or equal to one, then the 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.¶

7.7.4. The leaf-list's "default" Statement

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

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

The "default" statement MUST NOT be present on nodes where "min‑elements" has a value greater than or equal to one.¶

7.7.5. The "min-elements" Statement

The "min‑elements" statement, which is optional, takes as an argument a non-negative integer that puts a constraint on valid list entries. A valid leaf-list or list MUST have at least min-elements entries.¶

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 Section 7.5.1):¶

• If no such ancestor exists in the schema tree, the constraint is enforced.¶

• Otherwise, if this ancestor is a case node, the constraint is enforced if any other node from the case exists.¶

• Otherwise, it is enforced if the ancestor node exists.¶

The constraint is further enforced according to the rules in Section 8.¶

7.7.6. The "max-elements" Statement

The "max‑elements" statement, which is optional, takes as an argument a positive integer or the string "unbounded", which puts a constraint on valid list entries. A valid leaf-list or list always has at most max-elements entries.¶

If no "max‑elements" statement is present, it defaults to "unbounded".¶

The "max‑elements" constraint is enforced according to the rules in Section 8.¶

7.7.7. The "ordered-by" Statement

The "ordered‑by" statement defines whether the order of entries within a list are determined by the user or the system. The argument is one of the strings "system" or "user". If not present, ordering defaults to "system".¶

This statement is ignored if the list represents state data, RPC output parameters, or notification content.¶

See Section 7.7.1 for additional information.¶

7.7.8. 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 (Section 5.3.1) 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.¶

7.7.9. Usage Example

  leaf-list allow-user {
    type string;
    description
      "A list of user name patterns to allow.";
  }

A corresponding XML instance example:¶

  <allow-user>alice</allow-user>
  <allow-user>bob</allow-user>

To create a new element in this list, using the default <edit‑config> operation "merge":¶

  <rpc message-id="101"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
       xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
    <edit-config>
      <target>
        <running/>
      </target>
      <config>
        <system xmlns="urn:example:config">
          <services>
            <ssh>
              <allow-user>eric</allow-user>
            </ssh>
          </services>
        </system>
      </config>
    </edit-config>
  </rpc>

Given the following ordered-by user leaf-list:¶

  leaf-list cipher {
    type string;
    ordered-by user;
    description
      "A list of ciphers.";
  }

The following would be used to insert a new cipher "blowfish‑cbc" after "3des‑cbc":¶

  <rpc message-id="102"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
       xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
       xmlns:yang="urn:ietf:params:xml:ns:yang:1">
    <edit-config>
      <target>
        <running/>
      </target>
      <config>
        <system xmlns="urn:example:config">
          <services>
            <ssh>
              <cipher nc:operation="create"
                      yang:insert="after"
                      yang:value="3des-cbc">blowfish-cbc</cipher>
            </ssh>
          </services>
        </system>
      </config>
    </edit-config>
  </rpc>

7.8.2. The list's "key" Statement

The "key" statement, which MUST be present if the list represents configuration and MAY be present otherwise, takes as an argument a string that specifies a space-separated list of one or more leaf identifiers of this list. A leaf identifier MUST NOT appear more than once in the key. Each such leaf identifier MUST refer to a child leaf of the list. The leafs can be defined directly in substatements to the list or in groupings used in the list.¶

The combined values of all the leafs specified in the key are used to uniquely identify a list entry. All key leafs MUST be given values when a list entry is created. Thus, any default values in the key leafs or their types are ignored. Any "mandatory" statements in the key leafs are ignored.¶

A leaf that is part of the key can be of any built-in or derived type.¶

All key leafs in a list MUST have the same value for their "config" as the list itself.¶

The key string syntax is formally defined by the rule "key‑arg" in Section 14.¶

7.8.3. 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 Section 14). Each such schema node identifier MUST refer to a leaf.¶

If one of the referenced leafs represents configuration data, then all of the referenced leafs MUST represent configuration data.¶

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 Section 8.¶

The unique string syntax is formally defined by the rule "unique‑arg" in Section 14.¶

  list server {
    key "name";
    unique "ip port";
    leaf name {
      type string;
    }
    leaf ip {
      type inet:ip-address;
    }
    leaf port {
      type inet:port-number;
    }
  }

  <server>
    <name>smtp</name>
    <ip>192.0.2.1</ip>
    <port>25</port>
  </server>

  <server>
    <name>http</name>
    <ip>192.0.2.1</ip>
    <port>25</port>
  </server>

  <server>
    <name>smtp</name>
    <ip>192.0.2.1</ip>
    <port>25</port>
  </server>

  <server>
    <name>http</name>
    <ip>192.0.2.1</ip>
  </server>

  <server>
    <name>ftp</name>
    <ip>192.0.2.1</ip>
  </server>

7.9.2. The choice's "case" Statement

The "case" statement is used to define branches of the choice. It takes as an argument an identifier, followed by a block of substatements that holds detailed case information.¶

The identifier is used to identify the case node in the schema tree. A case node does not exist in the data tree.¶

Within a "case" statement, the "anydata", "anyxml", "choice", "container", "leaf", "list", "leaf‑list", and "uses" statements can be used to 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:¶

  choice interface-type {     // This example is illegal YANG
    case a {
      leaf ethernet { ... }
    }
    case b {
      container ethernet { ...}
    }
  }

As a shorthand, the "case" statement can be omitted if the branch contains a single "anydata", "anyxml", "choice", "container", "leaf", "list", or "leaf‑list" statement. In this case, the case node still exists in the schema tree, and its identifier is the same as the identifier of the child node. Schema node identifiers ( Section 6.5) MUST always explicitly include case node identifiers. The following example:¶

  choice interface-type {
    container ethernet { ... }
  }

is equivalent to:¶

  choice interface-type {
    case ethernet {
      container ethernet { ... }
    }
  }

The case identifier MUST be unique within a choice.¶

7.9.3. The choice's "default" Statement

The "default" statement indicates if a case should be considered as the default if no child nodes from any of the choice's cases exist. The argument is the identifier of the default "case" statement. If the "default" statement is missing, there is no default case.¶

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

The default case is only important when considering the "default" statements of nodes under the cases (i.e., default values of leafs and leaf-lists, and default cases of nested choices). The default values 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 (Section 3) directly under the default case.¶

Default values for child nodes under a case are only used if one of the nodes under that case is present or if that case is the default case. If none of the nodes under a case are present and the case is not the default case, the default values of the cases' child nodes are ignored.¶

In this example, the choice defaults to "interval", and the default 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.¶

  container transfer {
    choice how {
      default interval;
      case interval {
        leaf interval {
          type uint16;
          units minutes;
          default 30;
        }
      }
      case daily {
        leaf daily {
          type empty;
        }
        leaf time-of-day {
          type string;
          units 24-hour-clock;
          default "01.00";
        }
      }
      case manual {
        leaf manual {
          type empty;
        }
      }
    }
  }

7.9.4. The choice's "mandatory" Statement

The "mandatory" statement, which is optional, takes as an argument the string "true" or "false" and puts a constraint on valid data. If "mandatory" is "true", at least one node from exactly one of the choice's case branches MUST exist.¶

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 Section 7.5.1):¶

• If no such ancestor exists in the schema tree, the constraint is enforced.¶

• Otherwise, if this ancestor is a case node, the constraint is enforced if any other node from the case exists.¶

• Otherwise, it is enforced if the ancestor node exists.¶

The constraint is further enforced according to the rules in Section 8.¶

7.9.6. Usage Example

Given the following choice:¶

  container protocol {
    choice name {
      case a {
        leaf udp {
          type empty;
        }
      }
      case b {
        leaf tcp {
          type empty;
        }
      }
    }
  }

A corresponding XML instance example:¶

  <protocol>
    <tcp/>
  </protocol>

To change the protocol from TCP to UDP:¶

  <rpc message-id="101"
       xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
       xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
    <edit-config>
      <target>
        <running/>
      </target>
      <config>
        <system xmlns="urn:example:config">
          <protocol>
            <udp nc:operation="create"/>
          </protocol>
        </system>
      </config>
    </edit-config>
  </rpc>

7.12.2. Usage Example

  import ietf-inet-types {
    prefix "inet";
  }

  grouping endpoint {
    description "A reusable endpoint group.";
    leaf ip {
      type inet:ip-address;
    }
    leaf port {
      type inet:port-number;
    }
  }

7.13.2. The "refine" Statement

Some of the properties of each node in the grouping can be refined with the "refine" statement. The argument is a string that identifies a node in the grouping. This node is called the refine's target node. If a node in the grouping is not present as a target node of a "refine" statement, it is not refined and thus is used exactly as it was defined in the grouping.¶

The argument string is a descendant schema node identifier (see Section 6.5).¶

The following refinements can be done:¶

• A leaf or choice node may get a default value, or a new default value if it already had one.¶

• A leaf-list node may get a set of default values, or a new set of default values if it already had defaults; i.e., the set of refined default values replaces the defaults already given.¶

• Any node may get a specialized "description" string.¶

• Any node may get a specialized "reference" string.¶

• Any node may get a different "config" statement.¶

• A leaf, anydata, anyxml, or choice node may get a different "mandatory" statement.¶

• A container node may get a "presence" statement.¶

• A leaf, leaf-list, list, container, anydata, or anyxml node may get additional "must" expressions.¶

• A leaf-list or list node may get a different "min‑elements" or "max‑elements" statement.¶

• A leaf, leaf-list, list, container, choice, case, anydata, or anyxml node may get additional "if‑feature" expressions.¶

• Any node can get refined extensions, if the extension allows refinement. See Section 7.19 for details.¶

7.14.2. The "input" Statement

The "input" statement, which is optional, is used to define input parameters to the operation. It does not take an argument. The substatements to "input" define nodes under the operation's input node.¶

If a leaf in the input tree has a "mandatory" statement with the value "true", the leaf MUST be present in an RPC invocation.¶

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 Section 7.6.1. 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 Section 7.7.2. 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.¶

Since the input tree is not part of any datastore, all "config" 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.¶

7.14.3. The "output" Statement

The "output" statement, which is optional, is used to define output parameters to the RPC operation. It does not take an argument. The substatements to "output" define nodes under the operation's output node.¶

If a leaf in the output tree has a "mandatory" statement with the value "true", the leaf MUST be present in an RPC 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 Section 7.6.1. 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 Section 7.7.2. 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.¶

Since the output tree is not part of any datastore, all "config" 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.¶

7.18.2. The "base" Statement

The "base" statement, which is optional, takes as an argument a string that is the name of an existing identity, from which the new identity is derived. If no "base" statement is present, the identity is defined from scratch. If multiple "base" statements are present, the identity is derived from all of them.¶

If a prefix is present on the base name, 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. Otherwise, an identity with the matching name MUST be defined in the current module or an included submodule.¶

An identity MUST NOT reference itself, neither directly nor indirectly through a chain of other identities.¶

The derivation of identities has the following properties:¶

• It is irreflexive, which means that an identity is not derived from itself.¶

• It is transitive, which means that if identity B is derived from A and C is derived from B, then C is also derived from A.¶

7.18.3. Usage Example

  module example-crypto-base {
    yang-version 1.1;
    namespace "urn:example:crypto-base";
    prefix "crypto";

    identity crypto-alg {
      description
        "Base identity from which all crypto algorithms
         are derived.";
    }

    identity symmetric-key {
      description
        "Base identity used to identify symmetric-key crypto
         algorithms.";
      }

    identity public-key {
      description
        "Base identity used to identify public-key crypto
         algorithms.";
      }
  }

  module example-des {
    yang-version 1.1;
    namespace "urn:example:des";
    prefix "des";

    import "example-crypto-base" {
      prefix "crypto";
    }

    identity des {
      base "crypto:crypto-alg";
      base "crypto:symmetric-key";
      description "DES crypto algorithm.";
    }

    identity des3 {
      base "crypto:crypto-alg";
      base "crypto:symmetric-key";
      description "Triple DES crypto algorithm.";
    }
  }

7.19.2. The "argument" Statement

The "argument" statement, which is optional, takes as an argument a string that is the name of the argument to the keyword. If no "argument" statement is present, the keyword expects no argument when it is used.¶

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

7.19.3. Usage Example

To define an extension:¶

  module example-extensions {
    yang-version 1.1;
    ...

    extension c-define {
      description
        "Takes as an argument a name string.
         Makes the code generator use the given name
         in the #define.";
      argument "name";
    }
  }

To use the extension:¶

  module example-interfaces {
    yang-version 1.1;

    ...
    import example-extensions {
      prefix "myext";
    }
    ...

    container interfaces {
      ...
      myext:c-define "MY_INTERFACES";
    }
  }

7.20.1. 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 Section 7.20.2). 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 represent the abilities of the server within the model, giving a 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 Section 6.2. This name is used by the "if‑feature" statement to tie the schema nodes to the feature.¶

In this example, a feature called "local‑storage" represents the ability for a server to store syslog messages on local storage of some sort. This feature is used to make the "local‑storage‑limit" leaf 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.¶

  module example-syslog {
    yang-version 1.1;

    ...
    feature local-storage {
      description
        "This feature means that the server supports local
         storage (memory, flash, or disk) that can be used to
         store syslog messages.";
    }

    container syslog {
      leaf local-storage-limit {
        if-feature local-storage;
        type uint64;
        units "kilobyte";
        config false;
        description
          "The amount of local storage that can be
           used to hold syslog messages.";
      }
    }
  }

The "if‑feature" statement can be used in many places within the YANG syntax. Definitions tagged with "if‑feature" are ignored when the server does not support that feature.¶

A feature MUST NOT reference itself, neither directly nor indirectly through a chain of other features.¶

In order for a server to support a feature that is dependent on any other features (i.e., the feature has one or more "if‑feature" substatements), the server MUST also support all the dependent features.¶

7.20.2. The "if-feature" Statement

The "if‑feature" statement makes its parent statement conditional. The argument is a boolean expression over feature names. In this expression, a feature name evaluates to "true" if and only if the feature is supported by the server. The parent statement is implemented by servers where the boolean expression evaluates to "true".¶

The if-feature boolean expression syntax is formally defined by the rule "if‑feature‑expr" in Section 14. Parentheses are used to group expressions. When the expression is evaluated, the order of precedence is (highest precedence first): grouping (parentheses), "not", "and", "or".¶

If a prefix is present on a feature name in the boolean expression, the prefixed name refers to a feature defined in the module that was imported with that prefix, or the local module if the prefix matches the local module's prefix. Otherwise, a feature with the matching 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.¶

  container target {
    if-feature "outbound-tls or outbound-ssh";
    ...
  }

  if-feature "not foo or bar and baz";

  if-feature "(not foo) or (bar and baz)";

7.20.3. The "deviation" Statement

The "deviation" statement defines a hierarchy of a module that the server does not implement faithfully. The argument is a string that identifies the node in the schema tree where a deviation from the module occurs. This node is called the deviation's target node. The contents of the "deviation" statement give details about the deviation.¶

The argument string is an absolute schema node identifier (see Section 6.5).¶

Deviations define the way a server or class of servers deviate from a standard. This means that deviations MUST never be part of a published standard, since they are the mechanism for learning how implementations vary from the standards.¶

Server deviations are strongly discouraged and MUST only be used as a last resort. Telling the application how a server fails to follow a standard is no substitute for implementing the standard correctly. A server that deviates from a module is not fully compliant with the module.¶

However, in some cases, a particular device may not have the hardware or software ability to support parts of a standard module. When this occurs, the server makes a choice to either treat attempts to configure unsupported parts of the module as an error that is reported back to the unsuspecting application or ignore those incoming requests. Neither choice is acceptable.¶

Instead, YANG allows servers to document portions of a base module that are not supported, or that are supported but with different syntax, by using the "deviation" statement.¶

After applying all deviations announced by a server, in any order, the resulting data model MUST still be valid.¶

  module example-deviations {
    yang-version 1.1;
    namespace "urn:example:deviations";
    prefix md;

    import example-base {
      prefix base;
    }

    deviation /base:system/base:daytime {
      deviate not-supported;
    }
    ...
  }

  deviation /base:system/base:user/base:type {
    deviate add {
      default "admin"; // new users are 'admin' by default
    }
  }

  deviation /base:system/base:name-server {
    deviate replace {
      max-elements 3;
    }
  }

  container system {
    must "daytime or time";
    ...
  }

  deviation /base:system {
    deviate delete {
      must "daytime or time";
    }
  }

9.2.4. The "range" Statement

The "range" statement, which is an optional substatement to the "type" statement, takes as an argument a range expression string. It is used to restrict integer and decimal built-in types, or types derived from them.¶

A range consists of an explicit value, or a lower-inclusive bound, two consecutive dots "..", and an upper-inclusive bound. Multiple values or ranges can be given, separated by "|". If multiple values or ranges are given, they all MUST be disjoint and MUST be in ascending order. If a range restriction is applied to a type that is already range-restricted, the new restriction MUST be equally limiting or more limiting, i.e., raising the lower bounds, reducing the upper bounds, removing explicit values or ranges, or splitting ranges into multiple ranges with intermediate gaps. Each explicit value and range boundary value given in the range expression MUST match the type being restricted or be one of the special values "min" or "max". "min" and "max" mean the minimum and maximum values accepted for the type being restricted, respectively.¶

The range expression syntax is formally defined by the rule "range‑arg" in Section 14.¶

9.3.4. The "fraction-digits" Statement

The "fraction‑digits" statement, which is a substatement to the "type" statement, MUST be present if the type is "decimal64". It takes as an argument an integer between 1 and 18, inclusively. It controls the size of the minimum difference between values of a decimal64 type by restricting the value space to numbers that are expressible as "i x 10^-n" where n is the fraction-digits argument.¶

The following table lists the minimum and maximum values for each fraction-digit value:¶

9.6.4. The "enum" Statement

The "enum" statement, which is a substatement to the "type" statement, MUST be present if the type is "enumeration". It is repeatedly used to specify each assigned name of an enumeration type. It takes as an argument a string that is the assigned name. The string MUST NOT be zero-length and MUST NOT have any leading or trailing whitespace characters (any Unicode character with the "White_Space" property). The use of Unicode control codes SHOULD be avoided.¶

The statement is optionally followed by a block of substatements that holds detailed enum information.¶

All assigned names in an enumeration MUST be unique.¶

When an existing enumeration type is restricted, the set of assigned 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.¶

9.7.4. The "bit" Statement

The "bit" statement, which is a substatement to the "type" statement, MUST be present if the type is "bits". It is repeatedly used to 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 Section 6.2).¶

All assigned names in a bits type MUST be unique.¶

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