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.

   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.

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.

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.

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>

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.

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.

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;
              }
            }
          }
        }
      }

   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.

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

   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>

   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.

   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;
       }

       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.

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;
       }
     }

   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>

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.

   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.";
       }

       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        |
                 +--------------+---------+-------------+

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";
       }
     }

   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.

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

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.

   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.

               +--------------+--------------+-------------+
               | 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".

   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.

   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
     }

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.

   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.