]> Watsen Networks

kent+ietf@watsen.net

Operations NETMOD Working Group data modeling This document defines encoding rules for representing YANG modeled configuration data, state data, parameters of Remote Procedure Call (RPC) operations or actions, and notifications defined using XML. This document is developed on GitHub (). If you wish to contribute, please consider opening a pull request (PR). Please see the README file for details.

This document defines encoding rules for representing YANG modeled configuration data, state data, parameters of Remote Procedure Call (RPC) operations or actions, and notifications defined using the Extensible Markup Language (XML) .

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The following terms are defined in :

• action
• anydata
• anyxml
• augment
• container
• data node
• data tree
• identity
• instance identifier
• leaf
• leaf-list
• list
• module
• RPC operation
• submodule

The following terms are defined in [RFC6241]:

• configuration data
• notification
• state data

This document defines XML encoding for YANG data trees and their subtrees. It is always assumed that there may be one or more top-level elements in XML-encoded configuration data and state data. RPC operations and notifications contain a single top-level element. Instances of YANG data nodes (leafs, containers, leaf-lists, lists, anydata nodes, and anyxml nodes) are encoded as XML elements having the name of the YANG data node. ) defines how the name is qualified with a namespace, and the following sections deal with the value part. The encoding rules are identical for all types of data trees, i.e., configuration data, state data, parameters of RPC operations, actions, and notifications. With the exception of "anydata" encoding (), all rules in this document are also applicable to YANG 1.0 . With the exception of anyxml and schema-less anydata nodes, it is possible to map an XML-encoded data tree to other encodings, such as the JSON encoding as defined in , and vice versa. However, such conversions require the YANG data model to be available.

An XML element name is always identical to the identifier of the corresponding YANG data node. All XML elements encoding YANG data are namespace qualified. The XML default namespace is never used in YANG encoded data. The namespace of an XML element is either inherited from its ancestor or set using the "xmlns" attribute in the element. The "xmlns" attribute may either set the XML default namespace or define and use a prefix for the namespace. Note that the same XML may be encoded differently by different implementations. For instance, the following two XML documents are the same. Document 1:

]]>

Document 2:

]]>

The "namespace" statement of a module determines the namespace of all data node names defined in that module. If a data node is defined in a submodule, then the namespace of the main module is used. A namespace MUST be set for all top-level XML elements and then also whenever the namespaces of the data node and its parent node are different. For example, consider the following YANG module:

If the data model consists only of this module, then the following is valid XML-encoded configuration data:

54 ]]>

Note that the top-level element sets the default namespace which "foo" leaf inherits its parent container "top". Now, assume that the container "top" is augmented from another module, "example-barmod":

Valid XML-encoded configuration data containing both leafs may then look like this:

54 true ]]>

The "bar" leaf's element sets a new default namespace because its parent is defined in a different module. Prefixed namespace identifiers are sometimes needed when encoding values of the "identityref" and "instance-identifier" types. See and for details.

A leaf node is encoded as an XML element. The element's local name is the leaf's identifier, and its namespace is the module's XML namespace (see ). The value of the leaf node is encoded to XML according to the type (see for type encoding rules) and is sent as character data in the element. Example: For the leaf node definition

the following is a valid XML-encoded instance:

123 ]]>

A container node is encoded as an XML element. The element's local name is the container's identifier, and its namespace is the module's XML namespace (see ). The container's child nodes are encoded as subelements to the container element. If the container defines RPC or action input or output parameters, these subelements are encoded in the same order as they are defined within the "container" statement. Otherwise, the subelements are encoded in any order. Any whitespace between the subelements to the container is insignificant, i.e., an implementation MAY insert whitespace characters between subelements. If a non-presence container does not have any child nodes, the container may or may not be present in the XML encoding. Example: For the container definition

the following is valid XML-encoded instance data:

123 ]]>

Note that, the example above sets presence container "baz", which is encoded as an empty XML element, since it has no descendants.

A leaf-list node is encoded as a series of XML elements. Each element's local name is the leaf-list's identifier, and its namespace is the module's XML namespace (see ). There is no XML element surrounding the leaf-list as a whole. The value of each leaf-list entry is encoded to XML according to the type and is sent as character data in the element (see for type encoding rules). The XML elements representing leaf-list entries MUST appear in the order specified by the user if the leaf-list is "ordered-by user"; otherwise, the order is implementation dependent. The XML elements representing leaf-list entries MAY be interleaved with elements for siblings of the leaf-list, unless the leaf-list defines RPC or action input or output parameters. Example: For the leaf-list definition

the following is a valid XML-encoded instance:

123 0 ]]>

A list is encoded as a series of XML elements, one for each entry in the list. Each element's local name is the list's identifier, and its namespace is the module's XML namespace (see ). There is no XML element surrounding the list as a whole. The list's key nodes are encoded as subelements to the list's identifier element, in the same order as they are defined within the "key" statement. The rest of the list's child nodes are encoded as subelements to the list element, after the keys. If the list defines RPC or action input or output parameters, the subelements are encoded in the same order as they are defined within the "list" statement. Otherwise, the subelements are encoded in any order. Any whitespace between the subelements to the list entry is insignificant, i.e., an implementation MAY insert whitespace characters between subelements. The XML elements representing list entries MUST appear in the order specified by the user if the list is "ordered-by user"; otherwise, the order is implementation dependent. The XML elements representing list entries MAY be interleaved with elements for siblings of the list, unless the list defines RPC or action input or output parameters. Example: For the list definition

the following is a valid XML-encoded instance:

123 zig 456 zag ]]>

An anydata node is encoded as an XML element. The element's local name is the anydata's identifier, and its namespace is the module's XML namespace (see ). The value of the anydata node is a set of nodes, which are encoded as XML subelements to the anydata element. The anydata data node serves as a container for an arbitrary set of nodes that otherwise appear as normal YANG-modeled data. A data model for anydata content may or may not be known at runtime. In the latter case, converting XML-encoded instances to other encodings, such as JSON may be impossible. Example: For the anydata definition

the following is a valid XML-encoded instance:

2014-07-29T13:43:01Z fault Ethernet0 major ]]>

An anyxml node is encoded the same as an anydata node. Please see for how the anydata node is encoded.

Apart from instances of YANG data nodes, XML elements MAY contain XML attributes for special purposes, such as encoding metadata . The exact syntax and semantics of such members are outside the scope of this document.

The type of the XML value in an instance of the leaf or leaf-list data node depends on the type of that data node, as specified in the following subsections.

All numeric types (int8, int16, int32, uint8, uint16, uint32, int64, uint64, and decimal64) are represented as a text value conforming the to lexical representation for the type described in and . Example: For the "int16" type

the following is a valid XML-encoded instance:

4711 -123 0xf00f -0xf 052 -052 ]]>

A "string" value is represented as character data conforming the to lexical representation for the type described in . Example: For the "string" type

the following is a valid XML-encoded instance:

This string is all on one line. This string is: - on more than one line. - contains tab characters. ]]>

A "boolean" value is represented as the corresponding literal name "true" or "false". Example: For the "boolean" type

the following is a valid XML-encoded instance:

true false ]]>

An "enumeration" value is represented as character data conforming the to lexical representation for the type described in . Example: For the "enumeration" type

the following is a valid XML-encoded instance:

one two three ]]>

A "bits" value is represented as character data conforming the to lexical representation for the type described in . Example: For the "bits" type

the following is a valid XML-encoded instance:

zero zero one zero one two ]]>

A "binary" value is represented as character data conforming the to lexical representation for the type described in . Example: For the "binary" type

the following is a valid XML-encoded instance:

SGVsbG8gQm9iCg== SGVsbG8gQWxpY2UK ]]>

A "leafref" value is represented as character data conforming the to lexical representation for the type described in . Example: For the "leafref" type

the following is valid XML-encoded instance data:

up eth0 eth1 eth2 red green blue ]]>

A "identityref" value is represented as character data conforming the to lexical representation for the type described in . Example: For the "identityref" type

the following is a valid XML-encoded instance:

aes blowfish ]]>

Note that, the example above uses the default namespace, and hence the identities are not prefixed.

An "empty" value is represented as an empty XML element. Example: For the "empty" type

the following is a valid XML-encoded instance:

]]>

A "union" value is represented as character data conforming the to lexical representation for the type described in . Example: For the "union" type

the following is a valid XML-encoded instance:

16 32 64 unbounded ]]>

A "instance-identifier" value is represented as character data conforming the to lexical representation for the type described in . Example: For the "instance-identifier" type

the following is a valid XML-encoded instance:

/ex:system/ex:services/ex:ssh /ex:system/ex:services/ex:ssh/ex:port /ex:system/ex:user[ex:name='fred'] /ex:system/ex:user[ex:name='fred']/ex:type /ex:system/ex:server[ex:ip='192.0.2.1'][ex:port='80'] /ex:system/ex:service[ex:name='foo'][ex:enabled=''] /ex:system/ex:services/ex:ssh/ex:cipher[.='blowfish-cbc'] /ex:stats/ex:port[3] ]]>

None.

This document defines an encoding for data modeled in the YANG data modeling language. As such, it doesn't contribute any new security issues beyond those discussed in . This document defines no mechanisms for signing and encrypting data modeled with YANG. Under normal circumstances, data security and integrity are guaranteed by the management protocol in use, such as NETCONF or RESTCONF . If this is not the case, external mechanisms, such as Public-Key Cryptography Standards (PKCS) #7 , need to be considered. XML processing is rather different from JSON, and XML parsers may thus suffer from different types of vulnerabilities than their JSON counterparts. To minimize these new security risks, software on the receiving side SHOULD reject all messages that do not comply with the rules of this document and reply with an appropriate error message to the sender.

Substantial amounts of text in this document was copied from and . The authors wish to thank Martin Björklund and Ladislav Lhotka for authoring RFC 7950 and RFC 7951, respectively.