Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 6020

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

Pages: 173
Proposed Standard
Errata
Part 6 of 7 – Pages 111 to 142
First   Prev   Next

Top   ToC   RFC6020 - Page 111   prevText

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.
Top   ToC   RFC6020 - Page 112

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.
Top   ToC   RFC6020 - Page 113

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
Top   ToC   RFC6020 - Page 114

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 | +---------------+---------+-------------+
Top   ToC   RFC6020 - Page 115

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".
Top   ToC   RFC6020 - Page 116

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 | +----------------+-----------------------+----------------------+
Top   ToC   RFC6020 - Page 117

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.
Top   ToC   RFC6020 - Page 118
   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"; }
Top   ToC   RFC6020 - Page 119

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
Top   ToC   RFC6020 - Page 120

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.
Top   ToC   RFC6020 - Page 121
   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>
Top   ToC   RFC6020 - Page 122

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 | +--------------+---------+-------------+
Top   ToC   RFC6020 - Page 123
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.
Top   ToC   RFC6020 - Page 124

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.
Top   ToC   RFC6020 - Page 125
   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.
Top   ToC   RFC6020 - Page 126

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>
Top   ToC   RFC6020 - Page 127
   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>
Top   ToC   RFC6020 - Page 128
   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>
Top   ToC   RFC6020 - Page 129
   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.
Top   ToC   RFC6020 - Page 130
   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"; } } }
Top   ToC   RFC6020 - Page 131
   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; }
Top   ToC   RFC6020 - Page 132
   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.
Top   ToC   RFC6020 - Page 133

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.
Top   ToC   RFC6020 - Page 134

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']
Top   ToC   RFC6020 - Page 135
     /* 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.
Top   ToC   RFC6020 - Page 136
   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.
Top   ToC   RFC6020 - Page 137
   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".
Top   ToC   RFC6020 - Page 138
   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.
Top   ToC   RFC6020 - Page 139
               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       |
Top   ToC   RFC6020 - Page 140
            | 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
Top   ToC   RFC6020 - Page 141

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:
Top   ToC   RFC6020 - Page 142
     <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>


(next page on part 7)

Next Section