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 6 of 9 – Pages 108 to 137
First   Prev   Next

Top   ToC   RFC7950 - Page 108   prevText

7.14. The "rpc" Statement

The "rpc" statement is used to define an RPC operation. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed rpc information. This argument is the name of the RPC.
Top   ToC   RFC7950 - Page 109
   The "rpc" statement defines an rpc node in the schema tree.  Under
   the 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.

7.14.1. The rpc's Substatements

+--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | description | 7.21.3 | 0..1 | | grouping | 7.12 | 0..n | | if-feature | 7.20.2 | 0..n | | input | 7.14.2 | 0..1 | | output | 7.14.3 | 0..1 | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | +--------------+---------+-------------+

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.
Top   ToC   RFC7950 - Page 110
7.14.2.1. The input's Substatements
+--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anydata | 7.10 | 0..n | | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | | grouping | 7.12 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | must | 7.5.3 | 0..n | | typedef | 7.3 | 0..n | | uses | 7.13 | 0..n | +--------------+---------+-------------+

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.
Top   ToC   RFC7950 - Page 111
7.14.3.1. The output's Substatements
+--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anydata | 7.10 | 0..n | | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | | grouping | 7.12 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | must | 7.5.3 | 0..n | | typedef | 7.3 | 0..n | | uses | 7.13 | 0..n | +--------------+---------+-------------+

7.14.4. 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 [RFC6241]. The element's local name is the rpc's identifier, and its namespace is the module's XML namespace (see Section 7.1.3). 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 [RFC6241]. If output parameters are returned, they are encoded as child elements to the <rpc-reply> element defined in [RFC6241], in the same order as they are defined within the "output" statement.
Top   ToC   RFC7950 - Page 112

7.14.5. Usage Example

The following example defines an RPC operation: module example-rock { yang-version 1.1; namespace "urn:example:rock"; prefix "rock"; rpc rock-the-house { input { leaf zip-code { type string; } } } } A corresponding XML instance example of the complete rpc and rpc-reply: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <rock-the-house xmlns="urn:example:rock"> <zip-code>27606-0100</zip-code> </rock-the-house> </rpc> <rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <ok/> </rpc-reply>
Top   ToC   RFC7950 - Page 113

7.15. The "action" Statement

The "action" statement is used to define an operation connected to a specific container or list data node. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed action information. The argument is the name of the action. The "action" statement defines an action node in the schema tree. Under the action 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. An action MUST NOT be defined within an rpc, another action, or a notification, i.e., an action node MUST NOT have an rpc, action, or a notification node as one of its ancestors in the schema tree. For example, this means that it is an error if a grouping that contains an action somewhere in its node hierarchy is used in a notification definition. An action MUST NOT have any ancestor node that is a list node without a "key" statement. Since an action cannot be defined at the top level of a module or in a "case" statement, it is an error if a grouping that contains an action at the top of its node hierarchy is used at the top level of a module or in a case definition. The difference between an action and an rpc is that an action is tied 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.
Top   ToC   RFC7950 - Page 114

7.15.1. The action's Substatements

+--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | description | 7.21.3 | 0..1 | | grouping | 7.12 | 0..n | | if-feature | 7.20.2 | 0..n | | input | 7.14.2 | 0..1 | | output | 7.14.3 | 0..1 | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | +--------------+---------+-------------+

7.15.2. 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 Section 5.3.1) is encoded as a child XML element to the <rpc> element defined in [RFC6241], as designated by the substitution group "rpcOperation" in [RFC6241]. 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 [RFC6241]. If output parameters are returned, they are encoded as child elements to the <rpc-reply> element defined in [RFC6241], in the same order as they are defined within the "output" statement.
Top   ToC   RFC7950 - Page 115

7.15.3. Usage Example

The following example defines an action to reset one server at a server farm: module example-server-farm { yang-version 1.1; namespace "urn:example:server-farm"; prefix "sfarm"; import ietf-yang-types { prefix "yang"; } list server { key name; leaf name { type string; } action reset { input { leaf reset-at { type yang:date-and-time; mandatory true; } } output { leaf reset-finished-at { type yang:date-and-time; mandatory true; } } } } }
Top   ToC   RFC7950 - Page 116
   A corresponding XML instance example of the complete rpc and
   rpc-reply:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <action xmlns="urn:ietf:params:xml:ns:yang:1">
         <server xmlns="urn:example:server-farm">
           <name>apache-1</name>
           <reset>
             <reset-at>2014-07-29T13:42:00Z</reset-at>
           </reset>
         </server>
       </action>
     </rpc>

     <rpc-reply message-id="101"
                xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <reset-finished-at xmlns="urn:example:server-farm">
         2014-07-29T13:42:12Z
       </reset-finished-at>
     </rpc-reply>

7.16. The "notification" Statement

The "notification" statement is used to define a notification. It takes one argument, which is an identifier, followed by a block of substatements that holds detailed notification information. The "notification" statement defines a notification node in the schema tree. A notification can be defined at the top level of a module, or connected to a specific container or list data node in the schema tree. A notification MUST NOT be defined within an rpc, action, or another notification, i.e., a notification node MUST NOT have an rpc, action, or a notification node as one of its ancestors in the schema tree. For example, this means that it is an error if a grouping that contains a notification somewhere in its node hierarchy is used in an rpc definition. A notification MUST NOT have any ancestor node that is a list node without a "key" statement. Since a notification cannot be defined in a "case" statement, it is an error if a grouping that contains a notification at the top of its node hierarchy is used in a case definition.
Top   ToC   RFC7950 - Page 117
   If a leaf in the notification tree has a "mandatory" statement with
   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
   Section 7.6.1.  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 Section 7.7.2.  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.

   Since the notification tree is not part of any datastore, all
   "config" statements for nodes in the notification tree are ignored.

7.16.1. The notification's Substatements

+--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | anydata | 7.10 | 0..n | | anyxml | 7.11 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | | description | 7.21.3 | 0..1 | | grouping | 7.12 | 0..n | | if-feature | 7.20.2 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | must | 7.5.3 | 0..n | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | | typedef | 7.3 | 0..n | | uses | 7.13 | 0..n | +--------------+---------+-------------+

7.16.2. 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" [RFC5277]. The element's local name is the notification's identifier, and its namespace is the module's XML namespace (see Section 7.1.3).
Top   ToC   RFC7950 - Page 118
   When a notification node is defined as a child to a data node, the
   <notification> element defined in [RFC5277] 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.

7.16.3. Usage Example

The following example defines a notification at the top level of a module: module example-event { yang-version 1.1; namespace "urn:example:event"; prefix "ev"; notification event { leaf event-class { type string; } leaf reporting-entity { type instance-identifier; } leaf severity { type string; } } } A corresponding XML instance example of the complete notification: <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2008-07-08T00:01:00Z</eventTime> <event xmlns="urn:example:event"> <event-class>fault</event-class> <reporting-entity> /ex:interface[ex:name='Ethernet0'] </reporting-entity> <severity>major</severity> </event> </notification>
Top   ToC   RFC7950 - Page 119
   The following example defines a notification in a data node:

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

       container interfaces {
         list interface {
           key "name";
           leaf name {
             type string;
           }
           notification interface-enabled {
             leaf by-user {
               type string;
             }
           }
         }
       }
     }

   A corresponding XML instance example of the complete notification:

     <notification
       xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
       <eventTime>2008-07-08T00:01:00Z</eventTime>
       <interfaces xmlns="urn:example:interface-module">
         <interface>
           <name>eth1</name>
           <interface-enabled>
             <by-user>fred</by-user>
           </interface-enabled>
         </interface>
       </interfaces>
     </notification>

7.17. The "augment" Statement

The "augment" statement allows a module or submodule to add to a schema tree defined in an external module, or in the current module and its submodules, and to add to the nodes from a grouping in a "uses" statement. The argument is a string that identifies a node in the schema tree. This node is called the augment's target node. The target node MUST be either a container, list, choice, case, input, output, or notification node. It is augmented with the nodes defined in the substatements that follow the "augment" statement.
Top   ToC   RFC7950 - Page 120
   The argument string is a schema node identifier (see Section 6.5).
   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 Section 14) 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 Section 14) MUST be used.

   If the target node is a container, list, case, input, output, or
   notification node, the "container", "leaf", "list", "leaf-list",
   "uses", and "choice" statements can be used within the "augment"
   statement.

   If the target node is a container or list node, the "action" and
   "notification" statements can be used within the "augment" statement.

   If the target node is a choice node, the "case" statement or a
   shorthand "case" statement (see Section 7.9.2) can be used within the
   "augment" statement.

   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 Section 3) 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 not know about the augmenting module do not break.

   In the following example, it is OK to augment the "interface" entry
   with "mandatory-leaf" because the augmentation depends on support for
   "some-new-iftype".  The old client does not know about this type, so
   it would never select this type and would therefore not be adding a
   mandatory data node.

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

       import ietf-interfaces {
         prefix if;
       }

       identity some-new-iftype {
          base if:interface-type;
       }
Top   ToC   RFC7950 - Page 121
       augment "/if:interfaces/if:interface" {
          when 'derived-from-or-self(if:type, "mymod:some-new-iftype")';

          leaf mandatory-leaf {
             mandatory true;
             type string;
          }
       }
     }

7.17.1. The augment's Substatements

+--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | action | 7.15 | 0..n | | anydata | 7.10 | 0..n | | anyxml | 7.11 | 0..n | | case | 7.9.2 | 0..n | | choice | 7.9 | 0..n | | container | 7.5 | 0..n | | description | 7.21.3 | 0..1 | | if-feature | 7.20.2 | 0..n | | leaf | 7.6 | 0..n | | leaf-list | 7.7 | 0..n | | list | 7.8 | 0..n | | notification | 7.16 | 0..n | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | | uses | 7.13 | 0..n | | when | 7.21.5 | 0..1 | +--------------+---------+-------------+

7.17.2. 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 specified. When a node is augmented, the augmenting child nodes are encoded as subelements to the augmented node, in any order.
Top   ToC   RFC7950 - Page 122

7.17.3. Usage Example

In namespace urn:example:interface-module, we have: container interfaces { list ifEntry { key "ifIndex"; leaf ifIndex { type uint32; } leaf ifDescr { type string; } leaf ifType { type iana:IfType; } leaf ifMtu { type int32; } } } Then, in namespace urn:example:ds0, we have: import example-interface-module { prefix "if"; } augment "/if:interfaces/if:ifEntry" { when "if:ifType='ds0'"; leaf ds0ChannelNumber { type ChannelNumber; } }
Top   ToC   RFC7950 - Page 123
   A corresponding XML instance example:

     <interfaces xmlns="urn:example:interface-module"
                 xmlns:ds0="urn:example:ds0">
       <ifEntry>
         <ifIndex>1</ifIndex>
         <ifDescr>Flintstone Inc Ethernet A562</ifDescr>
         <ifType>ethernetCsmacd</ifType>
         <ifMtu>1500</ifMtu>
       </ifEntry>
       <ifEntry>
         <ifIndex>2</ifIndex>
         <ifDescr>Flintstone Inc DS0</ifDescr>
         <ifType>ds0</ifType>
         <ds0:ds0ChannelNumber>1</ds0:ds0ChannelNumber>
       </ifEntry>
     </interfaces>

   As another example, suppose we have the choice defined in
   Section 7.9.6.  The following construct can be used to extend the
   protocol definition:

     augment /ex:system/ex:protocol/ex:name {
       case c {
         leaf smtp {
           type empty;
         }
       }
     }

   A corresponding XML instance example:

     <ex:system>
       <ex:protocol>
         <ex:tcp/>
       </ex:protocol>
     </ex:system>

   or

     <ex:system>
       <ex:protocol>
         <other:smtp/>
       </ex:protocol>
     </ex:system>
Top   ToC   RFC7950 - Page 124

7.18. The "identity" Statement

The "identity" statement is used to define a new globally unique, abstract, and untyped identity. The identity's only purpose is to denote its name, semantics, and existence. An identity can be either defined from scratch or derived from one or more base identities. The identity's argument is an identifier that is the name of the identity. It is followed by a block of substatements that holds detailed identity information. The built-in datatype "identityref" (see Section 9.10) can be used to reference identities within a data model.

7.18.1. The identity's Substatements

+--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | base | 7.18.2 | 0..n | | description | 7.21.3 | 0..1 | | if-feature | 7.20.2 | 0..n | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | +--------------+---------+-------------+

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.
Top   ToC   RFC7950 - Page 125
   The derivation of identities has the following properties:

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

   o  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."; }
Top   ToC   RFC7950 - Page 126
       identity des3 {
         base "crypto:crypto-alg";
         base "crypto:symmetric-key";
         description "Triple DES crypto algorithm.";
       }
     }

7.19. The "extension" Statement

The "extension" statement allows the definition of new statements within the YANG language. This new statement definition can be imported and used by other modules. The "extension" statement's argument is an identifier that is the new keyword for the extension and must be followed by a block of substatements that holds detailed extension information. The purpose of the "extension" statement is to define a keyword so that it can be imported and used by other modules. The extension can be used like a normal YANG statement, with the statement name followed by an argument if one is defined by the "extension" statement, and an optional block of substatements. The statement's name is created by combining the prefix of the module in which the extension was defined, a colon (":"), and the extension's keyword, with no interleaving whitespace. The substatements of an 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 Section 14. An extension can allow refinement (see Section 7.13.2) and deviations (Section 7.20.3.2), but the mechanism for how this is defined is outside the scope of this specification.

7.19.1. The extension's Substatements

+--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | argument | 7.19.2 | 0..1 | | description | 7.21.3 | 0..1 | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | +--------------+---------+-------------+
Top   ToC   RFC7950 - Page 127

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.2.1. The argument's Substatement
+--------------+----------+-------------+ | substatement | section | cardinality | +--------------+----------+-------------+ | yin-element | 7.19.2.2 | 0..1 | +--------------+----------+-------------+
7.19.2.2. 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 Section 13). If no "yin-element" statement is present, it defaults to "false".

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"; } }
Top   ToC   RFC7950 - Page 128
   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. Conformance-Related Statements

This section defines statements related to conformance, as described in Section 5.6.

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.
Top   ToC   RFC7950 - Page 129
   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.
Top   ToC   RFC7950 - Page 130
7.20.1.1. The feature's Substatements
+--------------+---------+-------------+ | substatement | section | cardinality | +--------------+---------+-------------+ | description | 7.21.3 | 0..1 | | if-feature | 7.20.2 | 0..n | | reference | 7.21.4 | 0..1 | | status | 7.21.2 | 0..1 | +--------------+---------+-------------+

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.
Top   ToC   RFC7950 - Page 131
7.20.2.1. Usage Example
In this example, the container "target" is implemented if either the "outbound-tls" or "outbound-ssh" feature is supported by the server. container target { if-feature "outbound-tls or outbound-ssh"; ... } The following examples are equivalent: 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.
Top   ToC   RFC7950 - Page 132
   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.

7.20.3.1. The deviation's Substatements
+--------------+----------+-------------+ | substatement | section | cardinality | +--------------+----------+-------------+ | description | 7.21.3 | 0..1 | | deviate | 7.20.3.2 | 1..n | | reference | 7.21.4 | 0..1 | +--------------+----------+-------------+
7.20.3.2. The "deviate" Statement
The "deviate" statement defines how the server's implementation of the target node deviates from its original definition. The argument is one of the strings "not-supported", "add", "replace", or "delete". The argument "not-supported" indicates that the target node is not implemented by this server. The argument "add" adds properties to the target node. The properties to add are identified by substatements to the "deviate" statement. If a property can only appear once, the property MUST NOT exist in the target node. The argument "replace" replaces properties of the target node. The properties to replace are identified by substatements to the "deviate" statement. The properties to replace MUST exist in the target node. The argument "delete" deletes properties from the target node. The properties to delete are identified by substatements to the "delete" 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.
Top   ToC   RFC7950 - Page 133
               +--------------+--------------+-------------+
               | substatement | section      | cardinality |
               +--------------+--------------+-------------+
               | config       | 7.21.1       | 0..1        |
               | default      | 7.6.4, 7.7.4 | 0..n        |
               | mandatory    | 7.6.5        | 0..1        |
               | max-elements | 7.7.6        | 0..1        |
               | min-elements | 7.7.5        | 0..1        |
               | must         | 7.5.3        | 0..n        |
               | type         | 7.4          | 0..1        |
               | unique       | 7.8.3        | 0..n        |
               | units        | 7.3.3        | 0..1        |
               +--------------+--------------+-------------+

                        The deviate's Substatements

   If the target node has a property defined by an extension, this
   property can be deviated if the extension allows deviations.  See
   Section 7.19 for details.

7.20.3.3. 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. 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; } ... } A server would advertise both modules "example-base" and "example-deviations".
Top   ToC   RFC7950 - Page 134
   The following example sets a server-specific default value to a leaf
   that does not have a default value defined:

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

   In this example, the server limits the number of name servers to 3:

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

   If the original definition is:

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

   a server might remove this "must" constraint by doing:

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

7.21. Common Statements

This section defines substatements common to several other statements.

7.21.1. The "config" Statement

The "config" statement takes as an argument the string "true" or "false". If "config" is "true", the definition represents configuration. Data nodes representing configuration are part of configuration datastores. If "config" is "false", the definition represents state data. Data nodes representing state data are not part of configuration datastores.
Top   ToC   RFC7950 - Page 135
   If "config" is not specified, the default is the same as the parent
   schema node's "config" value.  If the parent node is a case node, the
   value is the same as the case node's parent choice node.

   If the top node does not specify a "config" statement, the default is
   "true".

   If a node has "config" set to "false", no node underneath it can have
   "config" set to "true".

7.21.2. The "status" Statement

The "status" statement takes as an argument one of the strings "current", "deprecated", or "obsolete". o "current" means that the definition is current and valid. o "deprecated" indicates an obsolete definition, but it permits new/continued implementation in order to foster interoperability with older/existing implementations. o "obsolete" means that the definition is obsolete and SHOULD NOT be implemented and/or can be removed from implementations. If no status is specified, the default is "current". If a definition is "current", it MUST NOT reference a "deprecated" or "obsolete" definition within the same module. If a definition is "deprecated", it MUST NOT reference an "obsolete" definition within the same module. For example, the following is illegal: typedef my-type { status deprecated; type int32; } leaf my-leaf { status current; type my-type; // illegal, since my-type is deprecated }
Top   ToC   RFC7950 - Page 136

7.21.3. The "description" Statement

The "description" statement takes as an argument a string that contains a human-readable textual description of this definition. The text is provided in a language (or languages) chosen by the module developer; for the sake of interoperability, it is RECOMMENDED to choose a language that is widely understood among the community of network administrators who will use the module.

7.21.4. The "reference" Statement

The "reference" statement takes as an argument a string that is a human-readable cross-reference to an external document -- either another module that defines related management information or a document that provides additional information relevant to this definition. For example, a typedef for a "uri" data type could look like: typedef uri { type string; reference "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"; ... }

7.21.5. 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 Section 6.4), 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. A leaf that is a list key MUST NOT have a "when" statement. 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 Section 8.3.2 for additional information.
Top   ToC   RFC7950 - Page 137
   The XPath expression is conceptually evaluated in the following
   context, in addition to the definition in Section 6.4.1:

   o  If the "when" statement is a child of an "augment" statement, then
      the context node is the augment's target node in the data tree, if
      the target node is a data node.  Otherwise, the context node is
      the closest ancestor node to the target node that is also a data
      node.  If no such node exists, the context node is the root node.
      The accessible tree is tentatively altered during the processing
      of the XPath expression by removing all instances (if any) of the
      nodes added by the "augment" statement.

   o  If the "when" statement is a child of a "uses", "choice", or
      "case" statement, then the context node is the closest ancestor
      node to the node with the "when" statement that is also a data
      node.  If no such node exists, the context node is the root node.
      The accessible tree is tentatively altered during the processing
      of the XPath expression by removing all instances (if any) of the
      nodes added by the "uses", "choice", or "case" statement.

   o  If the "when" statement is a child of any other data definition
      statement, the accessible tree is tentatively altered during the
      processing of the XPath expression by replacing all instances of
      the data node for which the "when" statement is defined with a
      single dummy node with the same name, but with no value and no
      children.  If no such instance exists, the dummy node is
      tentatively created.  The context node is this dummy node.

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

   If the XPath expression references any node that also has associated
   "when" statements, those "when" expressions MUST be evaluated first.
   There MUST NOT be any circular dependencies among "when" expressions.

   Note that the XPath expression is conceptually evaluated.  This means
   that an implementation does not have to use an XPath evaluator in the
   server.  The "when" statement can very well be implemented with
   specially written code.


(next page on part 7)

Next Section