9.  Built-In Types

   YANG has a set of built-in types, similar to those of many
   programming languages, but with some differences due to special
   requirements from the management information model.

   Additional types may be defined, derived from those built-in types or
   from other derived types.  Derived types may use subtyping to
   formally restrict the set of possible values.

   The different built-in types and their derived types allow different
   kinds of subtyping, namely length and regular expression restrictions
   of strings (Sections 9.4.4 and 9.4.6) and range restrictions of
   numeric types (Section 9.2.4).

   The lexical representation of a value of a certain type is used in
   the NETCONF messages and when specifying default values and numerical
   ranges in YANG modules.

9.1.  Canonical Representation

   For most types, there is a single canonical representation of the
   type's values.  Some types allow multiple lexical representations of
   the same value, for example, the positive integer "17" can be
   represented as "+17" or "17".  Implementations MUST support all
   lexical representations specified in this document.

   When a NETCONF server sends data, it MUST be in the canonical form.

   Some types have a lexical representation that depends on the XML
   context in which they occur.  These types do not have a canonical
   form.

9.2.  The Integer Built-In Types

   The integer built-in types are int8, int16, int32, int64, uint8,
   uint16, uint32, and uint64.  They represent signed and unsigned
   integers of different sizes:

   int8  represents integer values between -128 and 127, inclusively.

   int16  represents integer values between -32768 and 32767,
      inclusively.

   int32  represents integer values between -2147483648 and 2147483647,
      inclusively.

   int64  represents integer values between -9223372036854775808 and
      9223372036854775807, inclusively.

   uint8  represents integer values between 0 and 255, inclusively.

   uint16  represents integer values between 0 and 65535, inclusively.

   uint32  represents integer values between 0 and 4294967295,
      inclusively.

   uint64  represents integer values between 0 and 18446744073709551615,
      inclusively.

9.2.1.  Lexical Representation

   An integer value is lexically represented as an optional sign ("+" or
   "-"), followed by a sequence of decimal digits.  If no sign is
   specified, "+" is assumed.

   For convenience, when specifying a default value for an integer in a
   YANG module, an alternative lexical representation can be used, which
   represents the value in a hexadecimal or octal notation.  The
   hexadecimal notation consists of an optional sign ("+" or "-"), the
   characters "0x" followed a number of hexadecimal digits, where
   letters may be uppercase or lowercase.  The octal notation consists
   of an optional sign ("+" or "-"), the character "0" followed a number
   of octal digits.

   Note that if a default value in a YANG module has a leading zero
   ("0"), it is interpreted as an octal number.  In the XML instance
   documents, an integer is always interpreted as a decimal number, and
   leading zeros are allowed.

   Examples:

     // legal values
     +4711                       // legal positive value
     4711                        // legal positive value
     -123                        // legal negative value
     0xf00f                      // legal positive hexadecimal value
     -0xf                        // legal negative hexadecimal value
     052                         // legal positive octal value

     // illegal values
     - 1                         // illegal intermediate space

9.2.2.  Canonical Form

   The canonical form of a positive integer does not include the sign
   "+".  Leading zeros are prohibited.  The value zero is represented as
   "0".

9.2.3.  Restrictions

   All integer types can be restricted with the "range" statement
   (Section 9.2.4).

9.2.4.  The range Statement

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

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

   The range expression syntax is formally defined by the rule
   "range-arg" in Section 12.

9.2.4.1.  The range's Substatements

                 +---------------+---------+-------------+
                 | substatement  | section | cardinality |
                 +---------------+---------+-------------+
                 | description   | 7.19.3  | 0..1        |
                 | error-app-tag | 7.5.4.2 | 0..1        |
                 | error-message | 7.5.4.1 | 0..1        |
                 | reference     | 7.19.4  | 0..1        |
                 +---------------+---------+-------------+

9.2.5.  Usage Example

     typedef my-base-int32-type {
         type int32 {
             range "1..4 | 10..20";
         }
     }

     typedef my-type1 {
         type my-base-int32-type {
             // legal range restriction
             range "11..max"; // 11..20
         }
     }

     typedef my-type2 {
         type my-base-int32-type {
             // illegal range restriction
             range "11..100";
         }
     }

9.3.  The decimal64 Built-In Type

   The decimal64 type represents a subset of the real numbers, which can
   be represented by decimal numerals.  The value space of decimal64 is
   the set of numbers that can be obtained by multiplying a 64-bit
   signed integer by a negative power of ten, i.e., expressible as
   "i x 10^-n" where i is an integer64 and n is an integer between 1 and
   18, inclusively.

9.3.1.  Lexical Representation

   A decimal64 value is lexically represented as an optional sign ("+"
   or "-"), followed by a sequence of decimal digits, optionally
   followed by a period ('.') as a decimal indicator and a sequence of
   decimal digits.  If no sign is specified, "+" is assumed.

9.3.2.  Canonical Form

   The canonical form of a positive decimal64 does not include the sign
   "+".  The decimal point is required.  Leading and trailing zeros are
   prohibited, subject to the rule that there MUST be at least one digit
   before and after the decimal point.  The value zero is represented as
   "0.0".

9.3.3.  Restrictions

   A decimal64 type can be restricted with the "range" statement
   (Section 9.2.4).

9.3.4.  The fraction-digits Statement

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

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

     +----------------+-----------------------+----------------------+
     | fraction-digit | min                   | max                  |
     +----------------+-----------------------+----------------------+
     | 1              | -922337203685477580.8 | 922337203685477580.7 |
     | 2              | -92233720368547758.08 | 92233720368547758.07 |
     | 3              | -9223372036854775.808 | 9223372036854775.807 |
     | 4              | -922337203685477.5808 | 922337203685477.5807 |
     | 5              | -92233720368547.75808 | 92233720368547.75807 |
     | 6              | -9223372036854.775808 | 9223372036854.775807 |
     | 7              | -922337203685.4775808 | 922337203685.4775807 |
     | 8              | -92233720368.54775808 | 92233720368.54775807 |
     | 9              | -9223372036.854775808 | 9223372036.854775807 |
     | 10             | -922337203.6854775808 | 922337203.6854775807 |
     | 11             | -92233720.36854775808 | 92233720.36854775807 |
     | 12             | -9223372.036854775808 | 9223372.036854775807 |
     | 13             | -922337.2036854775808 | 922337.2036854775807 |
     | 14             | -92233.72036854775808 | 92233.72036854775807 |
     | 15             | -9223.372036854775808 | 9223.372036854775807 |
     | 16             | -922.3372036854775808 | 922.3372036854775807 |
     | 17             | -92.23372036854775808 | 92.23372036854775807 |
     | 18             | -9.223372036854775808 | 9.223372036854775807 |
     +----------------+-----------------------+----------------------+

9.3.5.  Usage Example

     typedef my-decimal {
         type decimal64 {
             fraction-digits 2;
             range "1 .. 3.14 | 10 | 20..max";
         }
     }

9.4.  The string Built-In Type

   The string built-in type represents human-readable strings in YANG.
   Legal characters are tab, carriage return, line feed, and the legal
   characters of Unicode and ISO/IEC 10646 [ISO.10646]:

     ;; any Unicode character, excluding the surrogate blocks,
     ;; FFFE, and FFFF.
     string = *char
     char = %x9 / %xA / %xD / %x20-D7FF / %xE000-FFFD /
            %x10000-10FFFF

9.4.1.  Lexical Representation

   A string value is lexically represented as character data in the XML
   instance documents.

9.4.2.  Canonical Form

   The canonical form is the same as the lexical representation.  No
   Unicode normalization is performed of string values.

9.4.3.  Restrictions

   A string can be restricted with the "length" (Section 9.4.4) and
   "pattern" (Section 9.4.6) statements.

9.4.4.  The length Statement

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

   A "length" statement restricts the number of Unicode characters in
   the string.

   A length range consists of an explicit value, or a lower bound, two
   consecutive dots "..", and an upper bound.  Multiple values or ranges
   can be given, separated by "|".  Length-restricting values MUST NOT
   be negative.  If multiple values or ranges are given, they all MUST
   be disjoint and MUST be in ascending order.  If a length restriction
   is applied to an already length-restricted type, the new restriction
   MUST be equal or more limiting, that is, raising the lower bounds,
   reducing the upper bounds, removing explicit length values or ranges,
   or splitting ranges into multiple ranges with intermediate gaps.  A
   length value is a non-negative integer, or one of the special values
   "min" or "max". "min" and "max" mean the minimum and maximum length
   accepted for the type being restricted, respectively.  An
   implementation is not required to support a length value larger than
   18446744073709551615.

   The length expression syntax is formally defined by the rule
   "length-arg" in Section 12.

9.4.4.1.  The length's Substatements

                 +---------------+---------+-------------+
                 | substatement  | section | cardinality |
                 +---------------+---------+-------------+
                 | description   | 7.19.3  | 0..1        |
                 | error-app-tag | 7.5.4.2 | 0..1        |
                 | error-message | 7.5.4.1 | 0..1        |
                 | reference     | 7.19.4  | 0..1        |
                 +---------------+---------+-------------+

9.4.5.  Usage Example

     typedef my-base-str-type {
         type string {
             length "1..255";
         }
     }

     type my-base-str-type {
         // legal length refinement
         length "11 | 42..max"; // 11 | 42..255
     }

     type my-base-str-type {
         // illegal length refinement
         length "1..999";
     }

9.4.6.  The pattern Statement

   The "pattern" statement, which is an optional substatement to the
   "type" statement, takes as an argument a regular expression string,
   as defined in [XSD-TYPES].  It is used to restrict the built-in type
   "string", or types derived from "string", to values that match the
   pattern.

   If the type has multiple "pattern" statements, the expressions are
   ANDed together, i.e., all such expressions have to match.

   If a pattern restriction is applied to an already pattern-restricted
   type, values must match all patterns in the base type, in addition to
   the new patterns.

9.4.6.1.  The pattern's Substatements

                 +---------------+---------+-------------+
                 | substatement  | section | cardinality |
                 +---------------+---------+-------------+
                 | description   | 7.19.3  | 0..1        |
                 | error-app-tag | 7.5.4.2 | 0..1        |
                 | error-message | 7.5.4.1 | 0..1        |
                 | reference     | 7.19.4  | 0..1        |
                 +---------------+---------+-------------+

9.4.7.  Usage Example

   With the following type:

     type string {
         length "0..4";
         pattern "[0-9a-fA-F]*";
     }

   the following strings match:

     AB          // legal
     9A00        // legal

   and the following strings do not match:

     00ABAB      // illegal, too long
     xx00        // illegal, bad characters

9.5.  The boolean Built-In Type

   The boolean built-in type represents a boolean value.

9.5.1.  Lexical Representation

   The lexical representation of a boolean value is a string with a
   value of "true" or "false".  These values MUST be in lowercase.

9.5.2.  Canonical Form

   The canonical form is the same as the lexical representation.

9.5.3.  Restrictions

   A boolean cannot be restricted.

9.6.  The enumeration Built-In Type

   The enumeration built-in type represents values from a set of
   assigned names.

9.6.1.  Lexical Representation

   The lexical representation of an enumeration value is the assigned
   name string.

9.6.2.  Canonical Form

   The canonical form is the assigned name string.

9.6.3.  Restrictions

   An enumeration cannot be restricted.

9.6.4.  The enum Statement

   The "enum" statement, which is a substatement to the "type"
   statement, MUST be present if the type is "enumeration".  It is
   repeatedly used to specify each assigned name of an enumeration type.
   It takes as an argument a string which is the assigned name.  The
   string MUST NOT be empty and MUST NOT have any leading or trailing
   whitespace characters.  The use of Unicode control codes SHOULD be
   avoided.

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

   All assigned names in an enumeration MUST be unique.

9.6.4.1.  The enum's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | description  | 7.19.3  | 0..1        |
                 | reference    | 7.19.4  | 0..1        |
                 | status       | 7.19.2  | 0..1        |
                 | value        | 9.6.4.2 | 0..1        |
                 +--------------+---------+-------------+

9.6.4.2.  The value Statement

   The "value" statement, which is optional, is used to associate an
   integer value with the assigned name for the enum.  This integer
   value MUST be in the range -2147483648 to 2147483647, and it MUST be
   unique within the enumeration type.  The value is unused by YANG and
   the XML encoding, but is carried as a convenience to implementors.

   If a value is not specified, then one will be automatically assigned.
   If the "enum" substatement is the first one defined, the assigned
   value is zero (0); otherwise, the assigned value is one greater than
   the current highest enum value.

   If the current highest value is equal to 2147483647, then an enum
   value MUST be specified for "enum" substatements following the one
   with the current highest value.

9.6.5.  Usage Example

     leaf myenum {
         type enumeration {
             enum zero;
             enum one;
             enum seven {
                 value 7;
             }
         }
     }

   The lexical representation of the leaf "myenum" with value "seven"
   is:

     <myenum>seven</myenum>

9.7.  The bits Built-In Type

   The bits built-in type represents a bit set.  That is, a bits value
   is a set of flags identified by small integer position numbers
   starting at 0.  Each bit number has an assigned name.

9.7.1.  Restrictions

   A bits type cannot be restricted.

9.7.2.  Lexical Representation

   The lexical representation of the bits type is a space-separated list
   of the individual bit values that are set.  An empty string thus
   represents a value where no bits are set.

9.7.3.  Canonical Form

   In the canonical form, the bit values are separated by a single space
   character and they appear ordered by their position (see
   Section 9.7.4.2).

9.7.4.  The bit Statement

   The "bit" statement, which is a substatement to the "type" statement,
   MUST be present if the type is "bits".  It is repeatedly used to
   specify each assigned named bit of a bits type.  It takes as an
   argument a string that is the assigned name of the bit.  It is
   followed by a block of substatements that holds detailed bit
   information.  The assigned name follows the same syntax rules as an
   identifier (see Section 6.2).

   All assigned names in a bits type MUST be unique.

9.7.4.1.  The bit's Substatements

                 +--------------+---------+-------------+
                 | substatement | section | cardinality |
                 +--------------+---------+-------------+
                 | description  | 7.19.3  | 0..1        |
                 | reference    | 7.19.4  | 0..1        |
                 | status       | 7.19.2  | 0..1        |
                 | position     | 9.7.4.2 | 0..1        |
                 +--------------+---------+-------------+

9.7.4.2.  The position Statement

   The "position" statement, which is optional, takes as an argument a
   non-negative integer value that specifies the bit's position within a
   hypothetical bit field.  The position value MUST be in the range 0 to
   4294967295, and it MUST be unique within the bits type.  The value is
   unused by YANG and the NETCONF messages, but is carried as a
   convenience to implementors.

   If a bit position is not specified, then one will be automatically
   assigned.  If the "bit" substatement is the first one defined, the
   assigned value is zero (0); otherwise, the assigned value is one
   greater than the current highest bit position.

   If the current highest bit position value is equal to 4294967295,
   then a position value MUST be specified for "bit" substatements
   following the one with the current highest position value.

9.7.5.  Usage Example

   Given the following leaf:

     leaf mybits {
         type bits {
             bit disable-nagle {
                 position 0;
             }
             bit auto-sense-speed {
                 position 1;
             }
             bit 10-Mb-only {
                 position 2;
             }
         }
         default "auto-sense-speed";
     }

   The lexical representation of this leaf with bit values disable-nagle
   and 10-Mb-only set would be:

     <mybits>disable-nagle 10-Mb-only</mybits>

9.8.  The binary Built-In Type

   The binary built-in type represents any binary data, i.e., a sequence
   of octets.

9.8.1.  Restrictions

   A binary can be restricted with the "length" (Section 9.4.4)
   statement.  The length of a binary value is the number of octets it
   contains.

9.8.2.  Lexical Representation

   Binary values are encoded with the base64 encoding scheme (see
   [RFC4648], Section 4).

9.8.3.  Canonical Form

   The canonical form of a binary value follows the rules in [RFC4648].

9.9.  The leafref Built-In Type

   The leafref type is used to reference a particular leaf instance in
   the data tree.  The "path" substatement (Section 9.9.2) selects a set
   of leaf instances, and the leafref value space is the set of values
   of these leaf instances.

   If the leaf with the leafref type represents configuration data, the
   leaf it refers to MUST also represent configuration.  Such a leaf
   puts a constraint on valid data.  All leafref nodes MUST reference
   existing leaf instances or leafs with default values in use (see
   Section 7.6.1) for the data to be valid.  This constraint is enforced
   according to the rules in Section 8.

   There MUST NOT be any circular chains of leafrefs.

   If the leaf that the leafref refers to is conditional based on one or
   more features (see Section 7.18.2), then the leaf with the leafref
   type MUST also be conditional based on at least the same set of
   features.

9.9.1.  Restrictions

   A leafref cannot be restricted.

9.9.2.  The path Statement

   The "path" statement, which is a substatement to the "type"
   statement, MUST be present if the type is "leafref".  It takes as an
   argument a string that MUST refer to a leaf or leaf-list node.

   The syntax for a path argument is a subset of the XPath abbreviated
   syntax.  Predicates are used only for constraining the values for the
   key nodes for list entries.  Each predicate consists of exactly one
   equality test per key, and multiple adjacent predicates MAY be
   present if a list has multiple keys.  The syntax is formally defined
   by the rule "path-arg" in Section 12.

   The predicates are only used when more than one key reference is
   needed to uniquely identify a leaf instance.  This occurs if a list
   has multiple keys, or a reference to a leaf other than the key in a
   list is needed.  In these cases, multiple leafrefs are typically
   specified, and predicates are used to tie them together.

   The "path" expression evaluates to a node set consisting of zero,
   one, or more nodes.  If the leaf with the leafref type represents
   configuration data, this node set MUST be non-empty.

   The "path" XPath expression is conceptually evaluated in the
   following context, in addition to the definition in Section 6.4.1:

   o  The context node is the node in the data tree for which the "path"
      statement is defined.

   The accessible tree depends on the context node:

   o  If the context node represents configuration data, the tree is the
      data in the NETCONF datastore where the context node exists.  The
      XPath root node has all top-level configuration data nodes in all
      modules as children.

   o  Otherwise, the tree is all state data on the device, and the
      <running/> datastore.  The XPath root node has all top-level data
      nodes in all modules as children.

9.9.3.  Lexical Representation

   A leafref value is encoded the same way as the leaf it references.

9.9.4.  Canonical Form

   The canonical form of a leafref is the same as the canonical form of
   the leaf it references.

9.9.5.  Usage Example

   With the following list:

     list interface {
         key "name";
         leaf name {
             type string;
         }
         leaf admin-status {
             type admin-status;
         }
         list address {
             key "ip";
             leaf ip {
                 type yang:ip-address;
             }
         }
     }

   The following leafref refers to an existing interface:

     leaf mgmt-interface {
         type leafref {
             path "../interface/name";
         }
     }

   An example of a corresponding XML snippet:

     <interface>
       <name>eth0</name>
     </interface>
     <interface>
       <name>lo</name>
     </interface>

     <mgmt-interface>eth0</mgmt-interface>

   The following leafrefs refer to an existing address of an interface:

     container default-address {
         leaf ifname {
             type leafref {
                 path "../../interface/name";
             }
         }
         leaf address {
             type leafref {
                 path "../../interface[name = current()/../ifname]"
                    + "/address/ip";
             }
         }
     }

   An example of a corresponding XML snippet:

     <interface>
       <name>eth0</name>
       <admin-status>up</admin-status>
       <address>
         <ip>192.0.2.1</ip>
       </address>
       <address>
         <ip>192.0.2.2</ip>
       </address>
     </interface>
     <interface>
       <name>lo</name>
       <admin-status>up</admin-status>
       <address>
         <ip>127.0.0.1</ip>
       </address>
     </interface>

     <default-address>
       <ifname>eth0</ifname>
       <address>192.0.2.2</address>
     </default-address>

   The following list uses a leafref for one of its keys.  This is
   similar to a foreign key in a relational database.

     list packet-filter {
         key "if-name filter-id";
         leaf if-name {
             type leafref {
                 path "/interface/name";
             }
         }
         leaf filter-id {
             type uint32;
         }
         ...
     }

   An example of a corresponding XML snippet:

     <interface>
       <name>eth0</name>
       <admin-status>up</admin-status>
       <address>
         <ip>192.0.2.1</ip>
       </address>
       <address>
         <ip>192.0.2.2</ip>
       </address>
     </interface>

     <packet-filter>
       <if-name>eth0</if-name>
       <filter-id>1</filter-id>
       ...
     </packet-filter>
     <packet-filter>
       <if-name>eth0</if-name>
       <filter-id>2</filter-id>
       ...
     </packet-filter>

   The following notification defines two leafrefs to refer to an
   existing admin-status:

     notification link-failure {
         leaf if-name {
             type leafref {
                 path "/interface/name";
             }
         }
         leaf admin-status {
             type leafref {
                 path
                   "/interface[name = current()/../if-name]"
                 + "/admin-status";
             }
         }
     }

   An example of a corresponding XML notification:

     <notification
       xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
       <eventTime>2008-04-01T00:01:00Z</eventTime>
       <link-failure xmlns="http://acme.example.com/system">
         <if-name>eth0</if-name>
         <admin-status>up</admin-status>
       </link-failure>
     </notification>

9.10.  The identityref Built-In Type

   The identityref type is used to reference an existing identity (see
   Section 7.16).

9.10.1.  Restrictions

   An identityref cannot be restricted.

9.10.2.  The identityref's base Statement

   The "base" statement, which is a substatement to the "type"
   statement, MUST be present if the type is "identityref".  The
   argument is the name of an identity, as defined by an "identity"
   statement.  If a prefix is present on the identity name, it refers to
   an identity defined in the module that was imported with that prefix.
   Otherwise, an identity with the matching name MUST be defined in the
   current module or an included submodule.

   Valid values for an identityref are any identities derived from the
   identityref's base identity.  On a particular server, the valid
   values are further restricted to the set of identities defined in the
   modules supported by the server.

9.10.3.  Lexical Representation

   An identityref is encoded as the referred identity's qualified name
   as defined in [XML-NAMES].  If the prefix is not present, the
   namespace of the identityref is the default namespace in effect on
   the element that contains the identityref value.

   When an identityref is given a default value using the "default"
   statement, the identity name in the default value MAY have a prefix.
   If a prefix is present on the identity name, it refers to an identity
   defined in the module that was imported with that prefix.  Otherwise,
   an identity with the matching name MUST be defined in the current
   module or an included submodule.

9.10.4.  Canonical Form

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

9.10.5.  Usage Example

   With the identity definitions in Section 7.16.3 and the following
   module:

     module my-crypto {

         namespace "http://example.com/my-crypto";
         prefix mc;

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

         identity aes {
             base "crypto:crypto-alg";
         }

         leaf crypto {
             type identityref {
                 base "crypto:crypto-alg";
             }
         }
     }

   the leaf "crypto" will be encoded as follows, if the value is the
   "des3" identity defined in the "des" module:

     <crypto xmlns:des="http://example.com/des">des:des3</crypto>

   Any prefixes used in the encoding are local to each instance
   encoding.  This means that the same identityref may be encoded
   differently by different implementations.  For example, the following
   example encodes the same leaf as above:

     <crypto xmlns:x="http://example.com/des">x:des3</crypto>

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

     <crypto xmlns:mc="http://example.com/my-crypto">mc:aes</crypto>

   or, using the default namespace:

     <crypto>aes</crypto>

9.11.  The empty Built-In Type

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

   An empty type cannot have a default value.

9.11.1.  Restrictions

   An empty type cannot be restricted.

9.11.2.  Lexical Representation

   Not applicable.

9.11.3.  Canonical Form

   Not applicable.

9.11.4.  Usage Example

   The following leaf

     leaf enable-qos {
         type empty;
     }

   will be encoded as

     <enable-qos/>

   if it exists.

9.12.  The union Built-In Type

   The union built-in type represents a value that corresponds to one of
   its member types.

   When the type is "union", the "type" statement (Section 7.4) MUST be
   present.  It is used to repeatedly specify each member type of the
   union.  It takes as an argument a string that is the name of a member
   type.

   A member type can be of any built-in or derived type, except it MUST
   NOT be one of the built-in types "empty" or "leafref".

   When a string representing a union data type is validated, the string
   is validated against each member type, in the order they are
   specified in the "type" statement, until a match is found.

   Any default value or "units" property defined in the member types is
   not inherited by the union type.

   Example:

     type union {
         type int32;
         type enumeration {
             enum "unbounded";
         }
     }

9.12.1.  Restrictions

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

9.12.2.  Lexical Representation

   The lexical representation of a union is a value that corresponds to
   the representation of any one of the member types.

9.12.3.  Canonical Form

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

9.13.  The instance-identifier Built-In Type

   The instance-identifier built-in type is used to uniquely identify a
   particular instance node in the data tree.

   The syntax for an instance-identifier is a subset of the XPath
   abbreviated syntax, formally defined by the rule
   "instance-identifier" in Section 12.  It is used to uniquely identify
   a node in the data tree.  Predicates are used only for specifying the
   values for the key nodes for list entries, a value of a leaf-list
   entry, or a positional index for a list without keys.  For
   identifying list entries with keys, each predicate consists of one
   equality test per key, and each key MUST have a corresponding
   predicate.

   If the leaf with the instance-identifier type represents
   configuration data, and the "require-instance" property
   (Section 9.13.2) is "true", the node it refers to MUST also represent
   configuration.  Such a leaf puts a constraint on valid data.  All
   such leaf nodes MUST reference existing nodes or leaf nodes with
   their default value in use (see Section 7.6.1) for the data to be
   valid.  This constraint is enforced according to the rules in
   Section 8.

   The "instance-identifier" XPath expression is conceptually evaluated
   in the following context, in addition to the definition in
   Section 6.4.1:

   o  The context node is the root node in the accessible tree.

   The accessible tree depends on the leaf with the instance-identifier
   type:

   o  If this leaf represents configuration data, the tree is the data
      in the NETCONF datastore where the leaf exists.  The XPath root
      node has all top-level configuration data nodes in all modules as
      children.

   o  Otherwise, the tree is all state data on the device, and the
      <running/> datastore.  The XPath root node has all top-level data
      nodes in all modules as children.

9.13.1.  Restrictions

   An instance-identifier can be restricted with the "require-instance"
   statement (Section 9.13.2).

9.13.2.  The require-instance Statement

   The "require-instance" statement, which is a substatement to the
   "type" statement, MAY be present if the type is
   "instance-identifier".  It takes as an argument the string "true" or
   "false".  If this statement is not present, it defaults to "true".

   If "require-instance" is "true", it means that the instance being
   referred MUST exist for the data to be valid.  This constraint is
   enforced according to the rules in Section 8.

   If "require-instance" is "false", it means that the instance being
   referred MAY exist in valid data.

9.13.3.  Lexical Representation

   An instance-identifier value is lexically represented as a string.
   All node names in an instance-identifier value MUST be qualified with
   explicit namespace prefixes, and these prefixes MUST be declared in
   the XML namespace scope in the instance-identifier's XML element.

   Any prefixes used in the encoding are local to each instance
   encoding.  This means that the same instance-identifier may be
   encoded differently by different implementations.

9.13.4.  Canonical Form

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

9.13.5.  Usage Example

   The following are examples of instance identifiers:

     /* instance-identifier for a container */
     /ex:system/ex:services/ex:ssh

     /* instance-identifier for a leaf */
     /ex:system/ex:services/ex:ssh/ex:port

     /* instance-identifier for a list entry */
     /ex:system/ex:user[ex:name='fred']

     /* instance-identifier for a leaf in a list entry */
     /ex:system/ex:user[ex:name='fred']/ex:type

     /* instance-identifier for a list entry with two keys */
     /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80']

     /* instance-identifier for a leaf-list entry */
     /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc']

     /* instance-identifier for a list entry without keys */
     /ex:stats/ex:port[3]

10.  Updating a Module

   As experience is gained with a module, it may be desirable to revise
   that module.  However, changes are not allowed if they have any
   potential to cause interoperability problems between a client using
   an original specification and a server using an updated
   specification.

   For any published change, a new "revision" statement (Section 7.1.9)
   MUST be included in front of the existing "revision" statements.  If
   there are no existing "revision" statements, then one MUST be added
   to identify the new revision.  Furthermore, any necessary changes
   MUST be applied to any meta-data statements, including the
   "organization" and "contact" statements (Sections 7.1.7, 7.1.8).

   Note that definitions contained in a module are available to be
   imported by any other module, and are referenced in "import"
   statements via the module name.  Thus, a module name MUST NOT be
   changed.  Furthermore, the "namespace" statement MUST NOT be changed,
   since all XML elements are qualified by the namespace.

   Obsolete definitions MUST NOT be removed from modules since their
   identifiers may still be referenced by other modules.

   A definition may be revised in any of the following ways:

   o  An "enumeration" type may have new enums added, provided the old
      enums's values do not change.

   o  A "bits" type may have new bits added, provided the old bit
      positions do not change.

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

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

   o  A "units" statement may be added.

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

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

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

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

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

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

   o  New typedefs, groupings, rpcs, notifications, extensions,
      features, and identities may be added.

   o  New data definition statements may be added if they do not add
      mandatory nodes (Section 3.1) to existing nodes or at the top
      level in a module or submodule, or if they are conditionally
      dependent on a new feature (i.e., have an "if-feature" statement
      that refers to a new feature).

   o  A new "case" statement may be added.

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

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

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

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

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

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

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

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

   In statements that have any data definition statements as
   substatements, those data definition substatements MUST NOT be
   reordered.

11.  YIN

   A YANG module can be translated into an alternative XML-based syntax
   called YIN.  The translated module is called a YIN module.  This
   section describes symmetric mapping rules between the two formats.

   The YANG and YIN formats contain equivalent information using
   different notations.  The YIN notation enables developers to
   represent YANG data models in XML and therefore use the rich set of
   XML-based tools for data filtering and validation, automated
   generation of code and documentation, and other tasks.  Tools like
   XSLT or XML validators can be utilized.

   The mapping between YANG and YIN does not modify the information
   content of the model.  Comments and whitespace are not preserved.

11.1.  Formal YIN Definition

   There is a one-to-one correspondence between YANG keywords and YIN
   elements.  The local name of a YIN element is identical to the
   corresponding YANG keyword.  This means, in particular, that the
   document element (root) of a YIN document is always <module> or
   <submodule>.

   YIN elements corresponding to the YANG keywords belong to the
   namespace whose associated URI is
   "urn:ietf:params:xml:ns:yang:yin:1".

   YIN elements corresponding to extension keywords belong to the
   namespace of the YANG module where the extension keyword is declared
   via the "extension" statement.

   The names of all YIN elements MUST be properly qualified with their
   namespaces specified above using the standard mechanisms of
   [XML-NAMES], i.e., "xmlns" and "xmlns:xxx" attributes.

   The argument of a YANG statement is represented in YIN either as an
   XML attribute or a subelement of the keyword element.  Table 1
   defines the mapping for the set of YANG keywords.  For extensions,
   the argument mapping is specified within the "extension" statement
   (see Section 7.17).  The following rules hold for arguments:

   o  If the argument is represented as an attribute, this attribute has
      no namespace.

   o  If the argument is represented as an element, it is qualified by
      the same namespace as its parent keyword element.

   o  If the argument is represented as an element, it MUST be the first
      child of the keyword element.

   Substatements of a YANG statement are represented as (additional)
   children of the keyword element and their relative order MUST be the
   same as the order of substatements in YANG.

   Comments in YANG MAY be mapped to XML comments.

               Mapping of arguments of the YANG statements.

            +------------------+---------------+-------------+
            | keyword          | argument name | yin-element |
            +------------------+---------------+-------------+
            | anyxml           | name          | false       |
            | argument         | name          | false       |
            | augment          | target-node   | false       |
            | base             | name          | false       |
            | belongs-to       | module        | false       |
            | bit              | name          | false       |
            | case             | name          | false       |
            | choice           | name          | false       |
            | config           | value         | false       |
            | contact          | text          | true        |
            | container        | name          | false       |
            | default          | value         | false       |
            | description      | text          | true        |
            | deviate          | value         | false       |
            | deviation        | target-node   | false       |
            | enum             | name          | false       |
            | error-app-tag    | value         | false       |
            | error-message    | value         | true        |
            | extension        | name          | false       |
            | feature          | name          | false       |
            | fraction-digits  | value         | false       |
            | grouping         | name          | false       |
            | identity         | name          | false       |
            | if-feature       | name          | false       |
            | import           | module        | false       |
            | include          | module        | false       |
            | input            | <no argument> | n/a         |
            | key              | value         | false       |
            | leaf             | name          | false       |
            | leaf-list        | name          | false       |
            | length           | value         | false       |
            | list             | name          | false       |
            | mandatory        | value         | false       |
            | max-elements     | value         | false       |
            | min-elements     | value         | false       |
            | module           | name          | false       |
            | must             | condition     | false       |
            | namespace        | uri           | false       |
            | notification     | name          | false       |
            | ordered-by       | value         | false       |
            | organization     | text          | true        |
            | output           | <no argument> | n/a         |
            | path             | value         | false       |

            | pattern          | value         | false       |
            | position         | value         | false       |
            | prefix           | value         | false       |
            | presence         | value         | false       |
            | range            | value         | false       |
            | reference        | text          | true        |
            | refine           | target-node   | false       |
            | require-instance | value         | false       |
            | revision         | date          | false       |
            | revision-date    | date          | false       |
            | rpc              | name          | false       |
            | status           | value         | false       |
            | submodule        | name          | false       |
            | type             | name          | false       |
            | typedef          | name          | false       |
            | unique           | tag           | false       |
            | units            | name          | false       |
            | uses             | name          | false       |
            | value            | value         | false       |
            | when             | condition     | false       |
            | yang-version     | value         | false       |
            | yin-element      | value         | false       |
            +------------------+---------------+-------------+

                                  Table 1

11.1.1.  Usage Example

   The following YANG module:

     module acme-foo {
         namespace "http://acme.example.com/foo";
         prefix "acfoo";

         import my-extensions {
             prefix "myext";
         }

         list interface {
             key "name";
             leaf name {
                 type string;
             }

             leaf mtu {
                 type uint32;
                 description "The MTU of the interface.";
                 myext:c-define "MY_MTU";
             }
         }
     }

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

     <module name="acme-foo"
             xmlns="urn:ietf:params:xml:ns:yang:yin:1"
             xmlns:acfoo="http://acme.example.com/foo"
             xmlns:myext="http://example.com/my-extensions">

       <namespace uri="http://acme.example.com/foo"/>
       <prefix value="acfoo"/>

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

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