NETMOD Working Group K. Watsen
Internet-Draft Watsen Networks
Intended status: Standards Track 8 July 2024
Expires: 9 January 2025
XML Encoding of Data Modeled with YANG
draft-yn-netmod-yang-xml-00
Abstract
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.
GitHub Information (to be removed by RFC Editor)
This document is developed on GitHub (https://github.com/netmod-wg/
rfc7950bis-and-friends). If you wish to contribute, please consider
opening a pull request (PR). Please see the README file for details.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 9 January 2025.
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
Watsen Expires 9 January 2025 [Page 1]
Internet-Draft XML Encoding of YANG Data July 2024
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3
3. Properties of the XML Encoding . . . . . . . . . . . . . . . 3
4. Names and Namespaces . . . . . . . . . . . . . . . . . . . . 4
5. Encoding of YANG Data Node Instances . . . . . . . . . . . . 6
5.1. The "leaf" Data Node . . . . . . . . . . . . . . . . . . 6
5.2. The "container" Data Node . . . . . . . . . . . . . . . . 7
5.3. The "leaf-list" Data Node . . . . . . . . . . . . . . . . 8
5.4. The "list" Data Node . . . . . . . . . . . . . . . . . . 8
5.5. The "anydata" Data Node . . . . . . . . . . . . . . . . . 10
5.6. The "anyxml" Data Node . . . . . . . . . . . . . . . . . 10
5.7. Metadata Objects . . . . . . . . . . . . . . . . . . . . 10
6. Representing YANG Data Types in XML Values . . . . . . . . . 11
6.1. Numeric Types . . . . . . . . . . . . . . . . . . . . . . 11
6.2. The "string" Type . . . . . . . . . . . . . . . . . . . . 11
6.3. The "boolean" Type . . . . . . . . . . . . . . . . . . . 12
6.4. The "enumeration" Type . . . . . . . . . . . . . . . . . 12
6.5. The "bits" Type . . . . . . . . . . . . . . . . . . . . . 13
6.6. The "binary" Type . . . . . . . . . . . . . . . . . . . . 13
6.7. The "leafref" Type . . . . . . . . . . . . . . . . . . . 13
6.8. The "identityref" Type . . . . . . . . . . . . . . . . . 14
6.9. The "empty" Type . . . . . . . . . . . . . . . . . . . . 15
6.10. The "union" Type . . . . . . . . . . . . . . . . . . . . 16
6.11. The "instance-identifier" Type . . . . . . . . . . . . . 16
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
8. Security Considerations . . . . . . . . . . . . . . . . . . . 17
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
9.1. Normative References . . . . . . . . . . . . . . . . . . 17
9.2. Informative References . . . . . . . . . . . . . . . . . 18
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 18
Watsen Expires 9 January 2025 [Page 2]
Internet-Draft XML Encoding of YANG Data July 2024
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction
This document defines encoding rules for representing YANG [RFC7950]
modeled configuration data, state data, parameters of Remote
Procedure Call (RPC) operations or actions, and notifications defined
using the Extensible Markup Language (XML) [XML].
2. Terminology and Notation
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 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
The following terms are defined in [RFC7950]:
* 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
3. Properties of the XML Encoding
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.
Watsen Expires 9 January 2025 [Page 3]
Internet-Draft XML Encoding of YANG Data July 2024
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. Section 4) 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 (Section 5.5), all rules in
this document are also applicable to YANG 1.0 [RFC6020].
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 [RFC7951], and vice versa. However,
such conversions require the YANG data model to be available.
4. Names and Namespaces
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.
Watsen Expires 9 January 2025 [Page 4]
Internet-Draft XML Encoding of YANG Data July 2024
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:
module example-foomod {
namespace "https://example.com/foomod";
prefix "foomod";
container top {
leaf foo {
type uint8;
}
}
}
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":
Watsen Expires 9 January 2025 [Page 5]
Internet-Draft XML Encoding of YANG Data July 2024
module example-barmod {
namespace "https://example.com/barmod";
prefix "barmod";
import example-foomod {
prefix "foomod";
}
augment "/foomod:top" {
leaf bar {
type boolean;
}
}
}
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
Section 6.8 and Section 6.11 for details.
5. Encoding of YANG Data Node Instances
5.1. The "leaf" Data Node
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 Section 4).
The value of the leaf node is encoded to XML according to the type
(see Section 6 for type encoding rules) and is sent as character data
in the element.
Example: For the leaf node definition
Watsen Expires 9 January 2025 [Page 6]
Internet-Draft XML Encoding of YANG Data July 2024
leaf foo {
type uint8;
}
the following is a valid XML-encoded instance:
123
5.2. The "container" Data Node
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 Section 4).
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
container bar {
leaf foo {
type uint8;
}
}
container baz {
presence "Indicates baz is configured";
}
the following is valid XML-encoded instance data:
Watsen Expires 9 January 2025 [Page 7]
Internet-Draft XML Encoding of YANG Data July 2024
123
Note that, the example above sets presence container "baz", which is
encoded as an empty XML element, since it has no descendants.
5.3. The "leaf-list" Data Node
A leaf-list node is encoded as a series of XML elements. Each
element's local name is the leaf-list's identifier, and its namespace
is the module's XML namespace (see Section 4). 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 Section 6 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
leaf-list foo {
type uint8;
}
the following is a valid XML-encoded instance:
123
0
5.4. The "list" Data Node
A list is encoded as a series of XML elements, one for each entry in
the list. Each element's local name is the list's identifier, and
its namespace is the module's XML namespace (see Section 4). There
is no XML element surrounding the list as a whole.
Watsen Expires 9 January 2025 [Page 8]
Internet-Draft XML Encoding of YANG Data July 2024
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
list bar {
key "foo baz";
leaf foo {
type uint8;
}
leaf baz {
type string;
}
}
the following is a valid XML-encoded instance:
123
zig
456
zag
Watsen Expires 9 January 2025 [Page 9]
Internet-Draft XML Encoding of YANG Data July 2024
5.5. The "anydata" Data Node
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 Section 4). 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 [RFC7951] may be impossible.
Example: For the anydata definition
anydata data;
the following is a valid XML-encoded instance:
2014-07-29T13:43:01Z
fault
Ethernet0
major
5.6. The "anyxml" Data Node
An anyxml node is encoded the same as an anydata node. Please see
Section 5.5 for how the anydata node is encoded.
5.7. Metadata Objects
Apart from instances of YANG data nodes, XML elements MAY contain XML
attributes for special purposes, such as encoding metadata [RFC7952].
The exact syntax and semantics of such members are outside the scope
of this document.
Watsen Expires 9 January 2025 [Page 10]
Internet-Draft XML Encoding of YANG Data July 2024
6. Representing YANG Data Types in XML Values
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.
6.1. Numeric Types
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 Section 9.2.1 of
[RFC7950] and Section 9.3.1 of [RFC7950] .
Example: For the "int16" type
leaf-list foo {
type int16;
}
the following is a valid XML-encoded instance:
4711
-123
0xf00f
-0xf
052
-052
6.2. The "string" Type
A "string" value is represented as character data conforming the to
lexical representation for the type described in Section 9.4.1 of
[RFC7950].
Example: For the "string" type
leaf-list foo {
type string;
}
the following is a valid XML-encoded instance:
Watsen Expires 9 January 2025 [Page 11]
Internet-Draft XML Encoding of YANG Data July 2024
This string is all on one line.
This string is:
- on more than one line.
- contains tab characters.
6.3. The "boolean" Type
A "boolean" value is represented as the corresponding literal name
"true" or "false".
Example: For the "boolean" type
leaf-list foo {
type boolean;
}
the following is a valid XML-encoded instance:
true
false
6.4. The "enumeration" Type
An "enumeration" value is represented as character data conforming
the to lexical representation for the type described in Section 9.6.1
of [RFC7950].
Example: For the "enumeration" type
leaf-list foo {
type enumeration {
enum one;
enum two;
enum three;
}
}
the following is a valid XML-encoded instance:
one
two
three
Watsen Expires 9 January 2025 [Page 12]
Internet-Draft XML Encoding of YANG Data July 2024
6.5. The "bits" Type
A "bits" value is represented as character data conforming the to
lexical representation for the type described in Section 9.7.2 of
[RFC7950].
Example: For the "bits" type
leaf-list foo {
type bits {
bit zero;
bit one;
bit two;
}
}
the following is a valid XML-encoded instance:
zero
zero one
zero one two
6.6. The "binary" Type
A "binary" value is represented as character data conforming the to
lexical representation for the type described in Section 9.8.2 of
[RFC7950].
Example: For the "binary" type
leaf-list foo {
type binary;
}
the following is a valid XML-encoded instance:
SGVsbG8gQm9iCg==
SGVsbG8gQWxpY2UK
6.7. The "leafref" Type
A "leafref" value is represented as character data conforming the to
lexical representation for the type described in Section 9.9.4 of
[RFC7950].
Watsen Expires 9 January 2025 [Page 13]
Internet-Draft XML Encoding of YANG Data July 2024
Example: For the "leafref" type
leaf-list status {
type leafref {
path "/my-leaf"; // assume current value is "up"
}
}
leaf-list ifname {
type leafref {
path "/my-list/key"; // assume current key values are
} // "eth0", "eth1", and "eth2"
}
leaf-list color {
type leafref {
path "/my-leaf-list"; // assume current list values are
} // "red", "green", and "blue"
}
the following is valid XML-encoded instance data:
up
eth0
eth1
eth2
red
green
blue
6.8. The "identityref" Type
A "identityref" value is represented as character data conforming the
to lexical representation for the type described in Section 9.10.3 of
[RFC7950].
Example: For the "identityref" type
Watsen Expires 9 January 2025 [Page 14]
Internet-Draft XML Encoding of YANG Data July 2024
identity symmetric-key-algs {
description
"Base identity used to identify symmetric-key crypto
algorithms.";
}
identity blowfish {
base symmetric-key;
description
"Identity used to identify the 'blowfish' algorithm.";
}
}
identity aes {
base symmetric-key;
description
"Identity used to identify the 'aes' algorithm.";
}
}
leaf-list foo {
type identityref {
base symmetric-key-algs;
}
}
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.
6.9. The "empty" Type
An "empty" value is represented as an empty XML element.
Example: For the "empty" type
leaf foo {
type empty;
}
the following is a valid XML-encoded instance:
Watsen Expires 9 January 2025 [Page 15]
Internet-Draft XML Encoding of YANG Data July 2024
6.10. The "union" Type
A "union" value is represented as character data conforming the to
lexical representation for the type described in Section 9.12.2 of
[RFC7950].
Example: For the "union" type
leaf-list foo {
type union {
type int32;
type enumeration {
enum "unbounded";
}
}
}
the following is a valid XML-encoded instance:
16
32
64
unbounded
6.11. The "instance-identifier" Type
A "instance-identifier" value is represented as character data
conforming the to lexical representation for the type described in
Section 9.13.2 of [RFC7950].
Example: For the "instance-identifier" type
leaf-list foo {
type instance-identifier;
}
the following is a valid XML-encoded instance:
Watsen Expires 9 January 2025 [Page 16]
Internet-Draft XML Encoding of YANG Data July 2024
/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]
7. IANA Considerations
None.
8. Security Considerations
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 Section 17 of [RFC7950].
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 [RFC6241] or RESTCONF [RFC8040]. If this is not the case,
external mechanisms, such as Public-Key Cryptography Standards
(PKCS) #7 [RFC2315], 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.
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
.
Watsen Expires 9 January 2025 [Page 17]
Internet-Draft XML Encoding of YANG Data July 2024
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, .
[XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and
F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", W3C Recommendation REC-xml-20081126, 26
November 2008,
.
9.2. Informative References
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
.
[RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax
Version 1.5", RFC 2315, DOI 10.17487/RFC2315, March 1998,
.
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
RFC 7951, DOI 10.17487/RFC7951, August 2016,
.
[RFC7952] Lhotka, L., "Defining and Using Metadata with YANG",
RFC 7952, DOI 10.17487/RFC7952, August 2016,
.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
.
Acknowledgements
Substantial amounts of text in this document was copied from
[RFC7950] and [RFC7951]. The authors wish to thank Martin Björklund
and Ladislav Lhotka for authoring RFC 7950 and RFC 7951,
respectively.
Author's Address
Watsen Expires 9 January 2025 [Page 18]
Internet-Draft XML Encoding of YANG Data July 2024
Kent Watsen
Watsen Networks
Email: kent+ietf@watsen.net
Watsen Expires 9 January 2025 [Page 19]