tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 6020

 
 
 

YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)

Part 4 of 7, p. 62 to 91
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 62 
7.7.  The leaf-list Statement

   Where the "leaf" statement is used to define a simple scalar variable
   of a particular type, the "leaf-list" statement is used to define an
   array of a particular type.  The "leaf-list" statement takes one
   argument, which is an identifier, followed by a block of
   substatements that holds detailed leaf-list information.

   The values in a leaf-list MUST be unique.

   Conceptually, the values in the data tree are always in the canonical
   form (see Section 9.1).

   If the type referenced by the leaf-list has a default value, it has
   no effect in the leaf-list.

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 device is
   free to sort the list entries in any reasonable order.  The
   "description" string for the list may suggest an order to the device
   implementor.  YANG calls this style of list "system ordered" and they
   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 device maintains that
   order.  YANG calls this style of list "user ordered" and they are
   indicated with the statement "ordered-by user".

   For example, the order in which firewall filters 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.

Top      Up      ToC       Page 63 
   The "ordered-by" statement is covered in Section 7.7.5.

7.7.2.  The leaf-list's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | config       | 7.19.1  | 0..1        |
                 | description  | 7.19.3  | 0..1        |
                 | if-feature   | 7.18.2  | 0..n        |
                 | max-elements | 7.7.4   | 0..1        |
                 | min-elements | 7.7.3   | 0..1        |
                 | must         | 7.5.3   | 0..n        |
                 | ordered-by   | 7.7.5   | 0..1        |
                 | reference    | 7.19.4  | 0..1        |
                 | status       | 7.19.2  | 0..1        |
                 | type         | 7.4     | 1           |
                 | units        | 7.3.3   | 0..1        |
                 | when         | 7.19.5  | 0..1        |
                 +--------------+---------+-------------+

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

   o  If this ancestor is a case node, the constraint is enforced if any
      other node from the case exists.

   o  Otherwise, it is enforced if the ancestor node exists.

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

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

Top      Up      ToC       Page 64 
   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.5.  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, order
   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.5.1.  ordered-by system

   The entries in the list are sorted according to an unspecified order.
   Thus, an implementation is free to sort the entries in the most
   appropriate order.  An implementation SHOULD use the same order for
   the same data, regardless of how the data were created.  Using a
   deterministic order will make comparisons possible using simple tools
   like "diff".

   This is the default order.

7.7.5.2.  ordered-by user

   The entries in the list are sorted according to an order defined by
   the user.  This order is controlled by using special XML attributes
   in the <edit-config> request.  See Section 7.7.7 for details.

7.7.6.  XML Mapping Rules

   A leaf-list node is encoded as a series of XML elements.  Each
   element's local name is the leaf-list's identifier, and its namespace
   is the module's XML namespace (see Section 7.1.3).

   The value of each leaf-list entry is encoded to XML according to the
   type, and sent as character data in the element.

   The XML elements representing leaf-list entries MUST appear in the
   order specified by the user if the leaf-list is "ordered-by user";
   otherwise, the order is implementation-dependent.  The XML elements

Top      Up      ToC       Page 65 
   representing leaf-list entries MAY be interleaved with other sibling
   elements, unless the leaf-list defines RPC input or output
   parameters.

   See Section 7.7.8 for an example.

7.7.7.  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 the
   time, in the order of the XML elements in the request.

   In a <copy-config>, or 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:

      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.

Top      Up      ToC       Page 66 
7.7.8.  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="http://example.com/schema/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":

Top      Up      ToC       Page 67 
     <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"
          xmlns:yang="urn:ietf:params:xml:ns:yang:1">
       <edit-config>
         <target>
           <running/>
         </target>
         <config>
           <system xmlns="http://example.com/schema/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.  The list Statement

   The "list" statement is used to define an interior data node in the
   schema tree.  A list node may exist in multiple instances in the data
   tree.  Each such instance is known as a list entry.  The "list"
   statement takes one argument, which is an identifier, followed by a
   block of substatements that holds detailed list information.

   A list entry is uniquely identified by the values of the list's keys,
   if defined.

Top      Up      ToC       Page 68 
7.8.1.  The list's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | anyxml       | 7.10    | 0..n        |
                 | choice       | 7.9     | 0..n        |
                 | config       | 7.19.1  | 0..1        |
                 | container    | 7.5     | 0..n        |
                 | description  | 7.19.3  | 0..1        |
                 | grouping     | 7.11    | 0..n        |
                 | if-feature   | 7.18.2  | 0..n        |
                 | key          | 7.8.2   | 0..1        |
                 | leaf         | 7.6     | 0..n        |
                 | leaf-list    | 7.7     | 0..n        |
                 | list         | 7.8     | 0..n        |
                 | max-elements | 7.7.4   | 0..1        |
                 | min-elements | 7.7.3   | 0..1        |
                 | must         | 7.5.3   | 0..n        |
                 | ordered-by   | 7.7.5   | 0..1        |
                 | reference    | 7.19.4  | 0..1        |
                 | status       | 7.19.2  | 0..1        |
                 | typedef      | 7.3     | 0..n        |
                 | unique       | 7.8.3   | 0..n        |
                 | uses         | 7.12    | 0..n        |
                 | when         | 7.19.5  | 0..1        |
                 +--------------+---------+-------------+

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 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.  It also implies that any mandatory
   statement in the key leafs are ignored.

   A leaf that is part of the key can be of any built-in or derived
   type, except it MUST NOT be the built-in type "empty".

Top      Up      ToC       Page 69 
   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 12.

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

7.8.3.1.  Usage Example

   With the following list:

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

Top      Up      ToC       Page 70 
   The following configuration is not valid:

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

   The following configuration is valid, since the "http" and "ftp" list
   entries do not have a value for all referenced leafs, and are thus
   not taken into account when the "unique" constraint is enforced:

     <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.8.4.  The list's Child Node Statements

   Within a list, the "container", "leaf", "list", "leaf-list", "uses",
   "choice", and "anyxml" statements can be used to define child nodes
   to the list.

7.8.5.  XML Mapping Rules

   A list is encoded as a series of XML elements, one for each entry in
   the list.  Each element's local name is the list's identifier, and
   its namespace is the module's XML namespace (see Section 7.1.3).

Top      Up      ToC       Page 71 
   The list's key nodes are encoded as subelements to the list's
   identifier element, in the same order as they are defined within the
   "key" statement.

   The rest of the list's child nodes are encoded as subelements to the
   list element, after the keys.  If the list defines RPC input or
   output parameters, the subelements are encoded in the same order as
   they are defined within the "list" statement.  Otherwise, the
   subelements are encoded in any order.

   The XML elements representing list entries MUST appear in the order
   specified by the user if the list is "ordered-by user", otherwise the
   order is implementation-dependent.  The XML elements representing
   list entries MAY be interleaved with other sibling elements, unless
   the list defines RPC input or output parameters.

7.8.6.  NETCONF <edit-config> Operations

   List entries can be created, deleted, replaced, and modified through
   <edit-config>, by using the "operation" attribute in the list's XML
   element.  In each case, the values of all keys are used to uniquely
   identify a list entry.  If all keys are not specified for a list
   entry, a "missing-element" error is returned.

   In an "ordered-by user" list, the attributes "insert" and "key" in
   the YANG XML namespace (Section 5.3.1) can be used to control where
   in the list the entry is inserted.  These can be used during "create"
   operations to insert a new list entry, or during "merge" or "replace"
   operations to insert a new list entry or move an existing one.

   The "insert" attribute can take the values "first", "last", "before",
   and "after".  If the value is "before" or "after", the "key"
   attribute MUST also be used, to specify an existing element in the
   list.  The value of the "key" attribute is the key predicates of the
   full instance identifier (see Section 9.13) for the list entry.

   If no "insert" attribute is present in the "create" operation, it
   defaults to "last".

   If several entries in an "ordered-by user" list are modified in the
   same <edit-config> request, the entries are modified one at the time,
   in the order of the XML elements in the request.

   In a <copy-config>, or an <edit-config> with a "replace" operation
   that covers the entire list, the list entry order is the same as the
   order of the XML elements in the request.

Top      Up      ToC       Page 72 
   When a NETCONF server processes an <edit-config> request, the
   elements of procedure for a list node are:

      If the operation is "merge" or "replace", the list entry is
      created if it does not exist.  If the list entry already exists
      and the "insert" and "key" attributes are present, the list entry
      is moved according to the values of the "insert" and "key"
      attributes.  If the list entry exists and the "insert" and "key"
      attributes are not present, the list entry is not moved.

      If the operation is "create", the list entry is created if it does
      not exist.  If the list entry already exists, a "data-exists"
      error is returned.

      If the operation is "delete", the entry is deleted from the list
      if it exists.  If the list entry does not exist, a "data-missing"
      error is returned.

7.8.7.  Usage Example

   Given the following list:

     list user {
         key "name";
         config true;
         description "This is a list of users in the system.";

         leaf name {
             type string;
         }
         leaf type {
             type string;
         }
         leaf full-name {
             type string;
         }
     }

   A corresponding XML instance example:

     <user>
       <name>fred</name>
       <type>admin</type>
       <full-name>Fred Flintstone</full-name>
     </user>

Top      Up      ToC       Page 73 
   To create a new user "barney":

     <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="http://example.com/schema/config">
             <user nc:operation="create">
               <name>barney</name>
               <type>admin</type>
               <full-name>Barney Rubble</full-name>
             </user>
           </system>
         </config>
       </edit-config>
     </rpc>

   To change the type of "fred" to "superuser":

     <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="http://example.com/schema/config">
             <user>
               <name>fred</name>
               <type>superuser</type>
             </user>
           </system>
         </config>
       </edit-config>
     </rpc>

Top      Up      ToC       Page 74 
   Given the following ordered-by user list:

     list user {
         description "This is a list of users in the system.";
         ordered-by user;
         config true;

         key "name";

         leaf name {
             type string;
         }
         leaf type {
             type string;
         }
         leaf full-name {
             type string;
         }
     }

   The following would be used to insert a new user "barney" after the
   user "fred":

     <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"
          xmlns:yang="urn:ietf:params:xml:ns:yang:1">
       <edit-config>
         <target>
           <running/>
         </target>
         <config>
           <system xmlns="http://example.com/schema/config"
                xmlns:ex="http://example.com/schema/config">
             <user nc:operation="create"
                   yang:insert="after"
                   yang:key="[ex:name='fred']">
               <name>barney</name>
               <type>admin</type>
               <full-name>Barney Rubble</full-name>
             </user>
           </system>
         </config>
       </edit-config>
     </rpc>

Top      Up      ToC       Page 75 
   The following would be used to move the user "barney" before the user
   "fred":

     <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"
          xmlns:yang="urn:ietf:params:xml:ns:yang:1">
       <edit-config>
         <target>
           <running/>
         </target>
         <config>
           <system xmlns="http://example.com/schema/config"
                xmlns:ex="http://example.com/schema/config">
             <user nc:operation="merge"
                   yang:insert="before"
                   yang:key="[ex:name='fred']">
               <name>barney</name>
             </user>
           </system>
         </config>
       </edit-config>
     </rpc>

7.9.  The choice Statement

   The "choice" statement defines a set of alternatives, only one of
   which may exist at any one time.  The argument is an identifier,
   followed by a block of substatements that holds detailed choice
   information.  The identifier is used to identify the choice node in
   the schema tree.  A choice node does not exist in the data tree.

   A choice consists of a number of branches, defined with the "case"
   substatement.  Each branch contains a number of child nodes.  The
   nodes from at most one of the choice's branches exist at the same
   time.

   See Section 8.3.2 for additional information.

Top      Up      ToC       Page 76 
7.9.1.  The choice's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | anyxml       | 7.10    | 0..n        |
                 | case         | 7.9.2   | 0..n        |
                 | config       | 7.19.1  | 0..1        |
                 | container    | 7.5     | 0..n        |
                 | default      | 7.9.3   | 0..1        |
                 | description  | 7.19.3  | 0..1        |
                 | if-feature   | 7.18.2  | 0..n        |
                 | leaf         | 7.6     | 0..n        |
                 | leaf-list    | 7.7     | 0..n        |
                 | list         | 7.8     | 0..n        |
                 | mandatory    | 7.9.4   | 0..1        |
                 | reference    | 7.19.4  | 0..1        |
                 | status       | 7.19.2  | 0..1        |
                 | when         | 7.19.5  | 0..1        |
                 +--------------+---------+-------------+

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

Top      Up      ToC       Page 77 
   As a shorthand, the "case" statement can be omitted if the branch
   contains a single "anyxml", "container", "leaf", "list", or
   "leaf-list" statement.  In this case, the identifier of the case node
   is the same as the identifier in the branch statement.  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.2.1.  The case's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | anyxml       | 7.10    | 0..n        |
                 | choice       | 7.9     | 0..n        |
                 | container    | 7.5     | 0..n        |
                 | description  | 7.19.3  | 0..1        |
                 | if-feature   | 7.18.2  | 0..n        |
                 | leaf         | 7.6     | 0..n        |
                 | leaf-list    | 7.7     | 0..n        |
                 | list         | 7.8     | 0..n        |
                 | reference    | 7.19.4  | 0..1        |
                 | status       | 7.19.2  | 0..1        |
                 | uses         | 7.12    | 0..n        |
                 | when         | 7.19.5  | 0..1        |
                 +--------------+---------+-------------+

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

Top      Up      ToC       Page 78 
   The default case is only important when considering the default
   values of nodes under the cases.  The default values for nodes 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.1) 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;
                     default 30;
                     units minutes;
                 }
             }
             case daily {
                 leaf daily {
                     type empty;
                 }
                 leaf time-of-day {
                     type string;
                     units 24-hour-clock;
                     default 1am;
                 }
             }
             case manual {
                 leaf manual {
                     type empty;
                 }
             }
         }
     }

Top      Up      ToC       Page 79 
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 which is not a non-presence
   container (see Section 7.5.1):

   o  If this ancestor is a case node, the constraint is enforced if any
      other node from the case exists.

   o  Otherwise, it is enforced if the ancestor node exists.

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

7.9.5.  XML Mapping Rules

   The choice and case nodes are not visible in XML.

   The child nodes of the selected "case" statement MUST be encoded in
   the same order as they are defined in the "case" statement if they
   are part of an RPC input or output parameter definition.  Otherwise,
   the subelements are encoded in any order.

7.9.6.  NETCONF <edit-config> Operations

   Since only one of the choice's cases can be valid at any time, the
   creation of a node from one case implicitly deletes all nodes from
   all other cases.  If an <edit-config> operation creates a node from a
   case, the NETCONF server will delete any existing nodes that are
   defined in other cases inside the choice.

7.9.7.  Usage Example

   Given the following choice:

Top      Up      ToC       Page 80 
     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="http://example.com/schema/config">
             <protocol>
               <udp nc:operation="create"/>
             </protocol>
           </system>
         </config>
       </edit-config>
     </rpc>

7.10.  The anyxml Statement

   The "anyxml" statement defines an interior node in the schema tree.
   It takes one argument, which is an identifier, followed by a block of
   substatements that holds detailed anyxml information.

Top      Up      ToC       Page 81 
   The "anyxml" statement is used to represent an unknown chunk of XML.
   No restrictions are placed on the XML.  This can be useful, for
   example, in RPC replies.  An example is the <filter> parameter in the
   <get-config> operation.

   An anyxml node cannot be augmented (see Section 7.15).

   Since the use of anyxml limits the manipulation of the content, it is
   RECOMMENDED that the "anyxml" statement not be used to represent
   configuration data.

   An anyxml node exists in zero or one instances in the data tree.

7.10.1.  The anyxml's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | config       | 7.19.1  | 0..1        |
                 | description  | 7.19.3  | 0..1        |
                 | if-feature   | 7.18.2  | 0..n        |
                 | mandatory    | 7.6.5   | 0..1        |
                 | must         | 7.5.3   | 0..n        |
                 | reference    | 7.19.4  | 0..1        |
                 | status       | 7.19.2  | 0..1        |
                 | when         | 7.19.5  | 0..1        |
                 +--------------+---------+-------------+

7.10.2.  XML Mapping Rules

   An anyxml node is encoded as an XML element.  The element's local
   name is the anyxml's identifier, and its namespace is the module's
   XML namespace (see Section 7.1.3).  The value of the anyxml node is
   encoded as XML content of this element.

   Note that any prefixes used in the encoding are local to each
   instance encoding.  This means that the same XML may be encoded
   differently by different implementations.

7.10.3.  NETCONF <edit-config> Operations

   An anyxml node is treated as an opaque chunk of data.  This data can
   be modified in its entirety only.

   Any "operation" attributes present on subelements of an anyxml node
   are ignored by the NETCONF server.

Top      Up      ToC       Page 82 
   When a NETCONF server processes an <edit-config> request, the
   elements of procedure for the anyxml node are:

      If the operation is "merge" or "replace", the node is created if
      it does not exist, and its value is set to the XML content of the
      anyxml node found in the XML RPC data.

      If the operation is "create", the node is created if it does not
      exist, and its value is set to the XML content of the anyxml node
      found in the XML RPC data.  If the node already exists, a
      "data-exists" error is returned.

      If the operation is "delete", the node is deleted if it exists.
      If the node does not exist, a "data-missing" error is returned.

7.10.4.  Usage Example

   Given the following "anyxml" statement:

     anyxml data;

   The following are two valid encodings of the same anyxml value:

     <data xmlns:if="http://example.com/ns/interface">
       <if:interface>
         <if:ifIndex>1</if:ifIndex>
       </if:interface>
     </data>

     <data>
       <interface xmlns="http://example.com/ns/interface">
         <ifIndex>1</ifIndex>
       </interface>
     </data>

7.11.  The grouping Statement

   The "grouping" statement is used to define a reusable block of nodes,
   which may be used locally in the module, in modules that include it,
   and by other modules that import from it, according to the rules in
   Section 5.5.  It takes one argument, which is an identifier, followed
   by a block of substatements that holds detailed grouping information.

   The "grouping" statement is not a data definition statement and, as
   such, does not define any nodes in the schema tree.

   A grouping is like a "structure" or a "record" in conventional
   programming languages.

Top      Up      ToC       Page 83 
   Once a grouping is defined, it can be referenced in a "uses"
   statement (see Section 7.12).  A grouping MUST NOT reference itself,
   neither directly nor indirectly through a chain of other groupings.

   If the grouping is defined at the top level of a YANG module or
   submodule, the grouping's identifier MUST be unique within the
   module.

   A grouping is more than just a mechanism for textual substitution,
   but defines a collection of nodes.  Identifiers appearing inside the
   grouping are resolved relative to the scope in which the grouping is
   defined, not where it is used.  Prefix mappings, type names, grouping
   names, and extension usage are evaluated in the hierarchy where the
   "grouping" statement appears.  For extensions, this means that
   extensions are applied to the grouping node, not the uses node.

7.11.1.  The grouping's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | anyxml       | 7.10    | 0..n        |
                 | choice       | 7.9     | 0..n        |
                 | container    | 7.5     | 0..n        |
                 | description  | 7.19.3  | 0..1        |
                 | grouping     | 7.11    | 0..n        |
                 | leaf         | 7.6     | 0..n        |
                 | leaf-list    | 7.7     | 0..n        |
                 | list         | 7.8     | 0..n        |
                 | reference    | 7.19.4  | 0..1        |
                 | status       | 7.19.2  | 0..1        |
                 | typedef      | 7.3     | 0..n        |
                 | uses         | 7.12    | 0..n        |
                 +--------------+---------+-------------+

Top      Up      ToC       Page 84 
7.11.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.12.  The uses Statement

   The "uses" statement is used to reference a "grouping" definition.
   It takes one argument, which is the name of the grouping.

   The effect of a "uses" reference to a grouping is that the nodes
   defined by the grouping are copied into the current schema tree, and
   then updated according to the "refine" and "augment" statements.

   The identifiers defined in the grouping are not bound to a namespace
   until the contents of the grouping are added to the schema tree via a
   "uses" statement that does not appear inside a "grouping" statement,
   at which point they are bound to the namespace of the current module.

Top      Up      ToC       Page 85 
7.12.1.  The uses's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | augment      | 7.15    | 0..1        |
                 | description  | 7.19.3  | 0..1        |
                 | if-feature   | 7.18.2  | 0..n        |
                 | refine       | 7.12.2  | 0..1        |
                 | reference    | 7.19.4  | 0..1        |
                 | status       | 7.19.2  | 0..1        |
                 | when         | 7.19.5  | 0..1        |
                 +--------------+---------+-------------+

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

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

   o  Any node may get a specialized "description" string.

   o  Any node may get a specialized "reference" string.

   o  Any node may get a different "config" statement.

   o  A leaf, anyxml, or choice node may get a different "mandatory"
      statement.

   o  A container node may get a "presence" statement.

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

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

Top      Up      ToC       Page 86 
7.12.3.  XML Mapping Rules

   Each node in the grouping is encoded as if it was defined inline,
   even if it is imported from another module with another XML
   namespace.

7.12.4.  Usage Example

   To use the "endpoint" grouping defined in Section 7.11.2 in a
   definition of an HTTP server in some other module, we can do:

     import acme-system {
         prefix "acme";
     }

     container http-server {
         leaf name {
             type string;
         }
         uses acme:endpoint;
     }

   A corresponding XML instance example:

     <http-server>
       <name>extern-web</name>
       <ip>192.0.2.1</ip>
       <port>80</port>
     </http-server>

   If port 80 should be the default for the HTTP server, default can be
   added:

     container http-server {
         leaf name {
             type string;
         }
         uses acme:endpoint {
             refine port {
                 default 80;
             }
         }
     }

   If we want to define a list of servers, and each server has the ip
   and port as keys, we can do:

Top      Up      ToC       Page 87 
     list server {
         key "ip port";
         leaf name {
             type string;
         }
         uses acme:endpoint;
     }

   The following is an error:

     container http-server {
         uses acme:endpoint;
         leaf ip {          // illegal - same identifier "ip" used twice
             type string;
         }
     }

7.13.  The rpc Statement

   The "rpc" statement is used to define a NETCONF 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, and is used as the element name directly under
   the <rpc> element, as designated by the substitution group
   "rpcOperation" in [RFC4741].

   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.

Top      Up      ToC       Page 88 
7.13.1.  The rpc's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | description  | 7.19.3  | 0..1        |
                 | grouping     | 7.11    | 0..n        |
                 | if-feature   | 7.18.2  | 0..n        |
                 | input        | 7.13.2  | 0..1        |
                 | output       | 7.13.3  | 0..1        |
                 | reference    | 7.19.4  | 0..1        |
                 | status       | 7.19.2  | 0..1        |
                 | typedef      | 7.3     | 0..n        |
                 +--------------+---------+-------------+

7.13.2.  The input Statement

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

   If a leaf in the input tree has a "mandatory" statement with the
   value "true", the leaf MUST be present in a NETCONF RPC invocation.
   Otherwise, the server MUST return a "missing-element" error.

   If a leaf in the input tree has a default value, the NETCONF server
   MUST use this value in the same cases as described in Section 7.6.1.
   In these cases, the server MUST operationally behave as if the leaf
   was present in the NETCONF RPC invocation with the default value as
   its value.

   If a "config" statement is present for any node in the input tree,
   the "config" statement is 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      Up      ToC       Page 89 
7.13.2.1.  The input's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | anyxml       | 7.10    | 0..n        |
                 | choice       | 7.9     | 0..n        |
                 | container    | 7.5     | 0..n        |
                 | grouping     | 7.11    | 0..n        |
                 | leaf         | 7.6     | 0..n        |
                 | leaf-list    | 7.7     | 0..n        |
                 | list         | 7.8     | 0..n        |
                 | typedef      | 7.3     | 0..n        |
                 | uses         | 7.12    | 0..n        |
                 +--------------+---------+-------------+

7.13.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 RPC's output node.

   If a leaf in the output tree has a "mandatory" statement with the
   value "true", the leaf MUST be present in a NETCONF RPC reply.

   If a leaf in the output tree has a default value, the NETCONF client
   MUST use this value in the same cases as described in Section 7.6.1.
   In these cases, the client MUST operationally behave as if the leaf
   was present in the NETCONF RPC reply with the default value as its
   value.

   If a "config" statement is present for any node in the output tree,
   the "config" statement is 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      Up      ToC       Page 90 
7.13.3.1.  The output's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | anyxml       | 7.10    | 0..n        |
                 | choice       | 7.9     | 0..n        |
                 | container    | 7.5     | 0..n        |
                 | grouping     | 7.11    | 0..n        |
                 | leaf         | 7.6     | 0..n        |
                 | leaf-list    | 7.7     | 0..n        |
                 | list         | 7.8     | 0..n        |
                 | typedef      | 7.3     | 0..n        |
                 | uses         | 7.12    | 0..n        |
                 +--------------+---------+-------------+

7.13.4.  XML Mapping Rules

   An rpc node is encoded as a child XML element to the <rpc> element
   defined in [RFC4741].  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 [RFC4741].  If output parameters are returned, they are encoded as
   child elements to the <rpc-reply> element defined in [RFC4741], in
   the same order as they are defined within the "output" statement.

Top      Up      ToC       Page 91 
7.13.5.  Usage Example

   The following example defines an RPC operation:

     module rock {
         namespace "http://example.net/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="http://example.net/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>



(page 91 continued on part 5)

Next RFC Part