draft-ietf-netmod-yang-json-03.txt   draft-ietf-netmod-yang-json-04.txt 
NETMOD Working Group L. Lhotka NETMOD Working Group L. Lhotka
Internet-Draft CZ.NIC Internet-Draft CZ.NIC
Intended status: Standards Track February 24, 2015 Intended status: Standards Track June 12, 2015
Expires: August 28, 2015 Expires: December 14, 2015
JSON Encoding of Data Modeled with YANG JSON Encoding of Data Modeled with YANG
draft-ietf-netmod-yang-json-03 draft-ietf-netmod-yang-json-04
Abstract Abstract
This document defines encoding rules for representing configuration, This document defines encoding rules for representing configuration,
state data, RPC input and output parameters, and notifications state data, RPC input and output parameters, and notifications
defined using YANG as JavaScript Object Notation (JSON) text. defined using YANG as JavaScript Object Notation (JSON) text.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 32 skipping to change at page 1, line 32
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 28, 2015. This Internet-Draft will expire on December 14, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 10 skipping to change at page 2, line 10
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3
3. Validation of JSON-encoded 3. Validation of JSON-encoded
Instance Data . . . . . . . . . . . . . . . . . . . . . . . . 3 Instance Data . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Names and Namespaces . . . . . . . . . . . . . . . . . . . . 4 4. Names and Namespaces . . . . . . . . . . . . . . . . . . . . 4
5. Encoding of YANG Data Node Instances . . . . . . . . . . . . 6 5. Encoding of YANG Data Node Instances . . . . . . . . . . . . 6
5.1. The "leaf" Data Node . . . . . . . . . . . . . . . . . . 6 5.1. The "leaf" Data Node . . . . . . . . . . . . . . . . . . 7
5.2. The "container" Data Node . . . . . . . . . . . . . . . . 7 5.2. The "container" Data Node . . . . . . . . . . . . . . . . 7
5.3. The "leaf-list" Data Node . . . . . . . . . . . . . . . . 7 5.3. The "leaf-list" Data Node . . . . . . . . . . . . . . . . 7
5.4. The "list" Data Node . . . . . . . . . . . . . . . . . . 7 5.4. The "list" Data Node . . . . . . . . . . . . . . . . . . 8
5.5. The "anyxml" Data Node . . . . . . . . . . . . . . . . . 8 5.5. The "anydata" Data Node . . . . . . . . . . . . . . . . . 9
6. The Mapping of YANG Data Types to JSON Values . . . . . . . . 9 5.6. The "anyxml" Data Node . . . . . . . . . . . . . . . . . 10
6.1. Numeric Types . . . . . . . . . . . . . . . . . . . . . . 9 6. The Mapping of YANG Data Types to JSON Values . . . . . . . . 10
6.2. The "string" Type . . . . . . . . . . . . . . . . . . . . 9 6.1. Numeric Types . . . . . . . . . . . . . . . . . . . . . . 10
6.3. The "boolean" Type . . . . . . . . . . . . . . . . . . . 9 6.2. The "string" Type . . . . . . . . . . . . . . . . . . . . 11
6.4. The "enumeration" Type . . . . . . . . . . . . . . . . . 10 6.3. The "boolean" Type . . . . . . . . . . . . . . . . . . . 11
6.5. The "bits" Type . . . . . . . . . . . . . . . . . . . . . 10 6.4. The "enumeration" Type . . . . . . . . . . . . . . . . . 11
6.6. The "binary" Type . . . . . . . . . . . . . . . . . . . . 10 6.5. The "bits" Type . . . . . . . . . . . . . . . . . . . . . 11
6.7. The "leafref" Type . . . . . . . . . . . . . . . . . . . 10 6.6. The "binary" Type . . . . . . . . . . . . . . . . . . . . 11
6.8. The "identityref" Type . . . . . . . . . . . . . . . . . 10 6.7. The "leafref" Type . . . . . . . . . . . . . . . . . . . 11
6.9. The "empty" Type . . . . . . . . . . . . . . . . . . . . 11 6.8. The "identityref" Type . . . . . . . . . . . . . . . . . 11
6.10. The "union" Type . . . . . . . . . . . . . . . . . . . . 11 6.9. The "empty" Type . . . . . . . . . . . . . . . . . . . . 12
6.11. The "instance-identifier" Type . . . . . . . . . . . . . 12 6.10. The "union" Type . . . . . . . . . . . . . . . . . . . . 13
7. I-JSON Compliance . . . . . . . . . . . . . . . . . . . . . . 13 6.11. The "instance-identifier" Type . . . . . . . . . . . . . 13
8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 7. I-JSON Compliance . . . . . . . . . . . . . . . . . . . . . . 14
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 8. Security Considerations . . . . . . . . . . . . . . . . . . . 15
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15
10.1. Normative References . . . . . . . . . . . . . . . . . . 14 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
10.2. Informative References . . . . . . . . . . . . . . . . . 14 10.1. Normative References . . . . . . . . . . . . . . . . . . 15
Appendix A. A Complete Example . . . . . . . . . . . . . . . . . 15 10.2. Informative References . . . . . . . . . . . . . . . . . 16
Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 17 Appendix A. A Complete Example . . . . . . . . . . . . . . . . . 16
B.1. Changes Between Revisions -02 and -03 . . . . . . . . . . 17 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 18
B.2. Changes Between Revisions -01 and -02 . . . . . . . . . . 17 B.1. Changes Between Revisions -03 and -04 . . . . . . . . . . 18
B.3. Changes Between Revisions -00 and -01 . . . . . . . . . . 17 B.2. Changes Between Revisions -02 and -03 . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18 B.3. Changes Between Revisions -01 and -02 . . . . . . . . . . 19
B.4. Changes Between Revisions -00 and -01 . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19
1. Introduction 1. Introduction
The NETCONF protocol [RFC6241] uses XML [W3C.REC-xml-20081126] for The NETCONF protocol [RFC6241] uses XML [W3C.REC-xml-20081126] for
encoding data in its Content Layer. Other management protocols might encoding data in its Content Layer. Other management protocols might
want to use other encodings while still benefiting from using YANG want to use other encodings while still benefiting from using YANG
[RFC6020] as the data modeling language. [I-D.ietf-netmod-rfc6020bis] as the data modeling language.
For example, the RESTCONF protocol [I-D.ietf-netconf-restconf] For example, the RESTCONF protocol [I-D.ietf-netconf-restconf]
supports two encodings: XML (media type "application/yang.data+xml") supports two encodings: XML (media type "application/yang.data+xml")
and JSON (media type "application/yang.data+json). and JSON (media type "application/yang.data+json).
The specification of the YANG data modelling language [RFC6020] The specification of YANG 1.1 data modelling language
defines only XML encoding for data instances, i.e. contents of [I-D.ietf-netmod-rfc6020bis] defines only XML encoding for data
configuration datastores, state data, RFC input and output instances, i.e., contents of configuration datastores, state data,
parameters, and event notifications. The aim of this document is to RFC input and output parameters, and event notifications. The aim of
define rules for encoding the same data as JavaScript Object Notation this document is to define rules for encoding the same data as
(JSON) text [RFC7159]. JavaScript Object Notation (JSON) text [RFC7159].
In order to achieve maximum interoperability while allowing In order to achieve maximum interoperability while allowing
implementations to use a variety of available JSON parsers, the JSON implementations to use a variety of available JSON parsers, the JSON
encoding rules follow, as much as possible, the constraints of the encoding rules follow, as much as possible, the constraints of the
I-JSON restricted profile [I-D.ietf-json-i-json]. Section 7 I-JSON restricted profile [RFC7493]. Section 7 discusses I-JSON
discusses I-JSON conformance in more detail. conformance in more detail.
2. Terminology and Notation 2. Terminology and Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
The following terms are defined in [RFC6020]: The following terms are defined in [I-D.ietf-netmod-rfc6020bis]:
o anyxml o anydata,
o augment o anyxml,
o container o augment,
o data node o container,
o identity o data node,
o instance identifier o identity,
o leaf o instance identifier,
o leaf-list o leaf,
o list o leaf-list,
o module o list,
o submodule o module,
o submodule.
3. Validation of JSON-encoded Instance Data 3. Validation of JSON-encoded Instance Data
Instance data validation as defined in [RFC6020] is only applicable Instance data validation as defined in [I-D.ietf-netmod-rfc6020bis],
to XML-encoded data. For one, semantic constraints in "must" sec. 8.3.3, is only applicable to XML-encoded data. For one,
statements are expressed using XPath 1.0 [W3C.REC-xpath-19991116], semantic constraints in "must" statements are expressed using
which can be properly interpreted only in the XML context. XPath 1.0 [W3C.REC-xpath-19991116], which can be properly interpreted
only in the XML context.
This document and the corresponding "XML Mapping Rules" sections from This document and the corresponding "XML Mapping Rules" sections from
[RFC6020] also define an implicit schema-driven mapping of JSON- [I-D.ietf-netmod-rfc6020bis] also define an implicit schema-driven
encoded instances to XML-encoded instances (and vice versa). This mapping of JSON-encoded instances to XML-encoded instances (and vice
mapping is mostly straightforward. In cases where doubts could versa). This mapping is mostly straightforward. In cases where
arise, this document gives explicit instructions for mapping JSON- doubts could arise, this document gives explicit instructions for
encoded instances to XML. mapping JSON-encoded instances to XML.
In order to validate a JSON instance document, it MUST first be In order to validate a JSON instance document, it needs first to be
mapped, at least conceptually, to the corresponding XML instance mapped, at least conceptually, to the corresponding XML instance
document. By definition, the JSON document is then valid if and only document. By definition, the JSON document is then valid if and only
if the XML document is valid according to the rules stated in if the XML document is valid according to the rules stated in
[RFC6020]. [I-D.ietf-netmod-rfc6020bis].
4. Names and Namespaces 4. Names and Namespaces
Instances of YANG data nodes (leafs, containers, leaf-lists, lists Instances of YANG data nodes (leafs, containers, leaf-lists, lists,
and anyxml nodes) are always encoded as members of a JSON object, anydata and anyxml nodes) are always encoded as members of a JSON
i.e., as name/value pairs. This section defines how the name part is object, i.e., as name/value pairs. This section defines how the name
formed, and the following sections deal with the value part. part is formed, and the following sections deal with the value part.
Except in the cases specified below, the member name is identical to Except in the cases specified below, the member name is identical to
the identifier of the corresponding YANG data node. Every such name the identifier of the corresponding YANG data node. Every such name
belongs to a namespace which is associated with the YANG module where belongs to a namespace which is associated with the YANG module where
the corresponding data node is defined. If the data node is defined the corresponding data node is defined. If the data node is defined
in a submodule, then the namespace is determined by the main module in a submodule, then the namespace is determined by the main module
to which the submodule belongs. to which the submodule belongs.
If the namespace of a member name has to be explicitly specified, the If the namespace of a member name has to be explicitly specified, the
module name SHALL be used as a prefix to the (local) member name. module name SHALL be used as a prefix to the member's local name.
Both parts of the member name SHALL be separated with a colon Both parts of the member name SHALL be separated with a colon
character (":"). In other words, the namespace-qualified name will character (":"). Using ABNF [RFC5234], the namespace-qualified name
have the following form: can be expressed as shown in Figure 1, where the production for
"identifier" is defined in sec. 13 of [I-D.ietf-netmod-rfc6020bis].
<module name>:<local name> qualified-member-name = identifier ":" identifier
Figure 1: Encoding a namespace identifier with a local name. Figure 1: ABNF production for a qualified member name.
Names with namespace identifiers in the form shown in Figure 1 are Names with namespace identifiers in the form shown in Figure 1 are
used if and only if the parent data node belongs to a different used if and only if the parent data node belongs to a different
namespace, which also includes all top-level YANG data nodes. namespace, which also includes all top-level YANG data nodes that
have no parent node.
For example, consider the following YANG module: For example, consider the following YANG module:
module foomod { module foomod {
namespace "http://example.com/foomod"; namespace "http://example.com/foomod";
prefix "foo"; prefix "foo";
container top { container top {
skipping to change at page 7, line 7 skipping to change at page 7, line 24
leaf foo { leaf foo {
type uint8; type uint8;
} }
the following is a valid JSON-encoded instance: the following is a valid JSON-encoded instance:
"foo": 123 "foo": 123
5.2. The "container" Data Node 5.2. The "container" Data Node
An container instance is encoded as a name/object pair. The A container instance is encoded as a name/object pair. The
container's child data nodes are encoded as members of the object. container's child data nodes are encoded as members of the object.
Example: For the container definition Example: For the container definition
container bar { container bar {
leaf foo { leaf foo {
type uint8; type uint8;
} }
} }
the following is a valid instance: the following is a valid JSON-encoded instance:
"bar": { "bar": {
"foo": 123 "foo": 123
} }
5.3. The "leaf-list" Data Node 5.3. The "leaf-list" Data Node
A leaf-list is encoded as a name/array pair, and the array elements A leaf-list is encoded as a name/array pair, and the array elements
are values of the same type, which can be a string, number, literal are values of some scalar type, which can be a string, number,
"true" or "false", or the special array "[null]", depending on the literal "true" or "false", or the special array "[null]", depending
type of the leaf-list (see Section 6 for the type encoding rules). on the type of the leaf-list (see Section 6 for the type encoding
rules).
The ordering of array elements follows the same rules as the ordering The ordering of array elements follows the same rules as the ordering
of XML elements representing leaf-list entries in the XML encoding. of XML elements representing leaf-list entries in the XML encoding.
Specifically, the "ordered-by" properties (sec. 7.7.5 in [RFC6020]) Specifically, the "ordered-by" properties (sec. 7.7.7 in
MUST be observed. [I-D.ietf-netmod-rfc6020bis]) MUST be observed.
Example: For the leaf-list definition Example: For the leaf-list definition
leaf-list foo { leaf-list foo {
type uint8; type uint8;
} }
the following is a valid instance: the following is a valid JSON-encoded instance:
"foo": [123, 0] "foo": [123, 0]
5.4. The "list" Data Node 5.4. The "list" Data Node
A list instance is encoded as a name/array pair, and the array A list instance is encoded as a name/array pair, and the array
elements are JSON objects. elements are JSON objects.
The ordering of array elements follows the same rules as the ordering The ordering of array elements follows the same rules as the ordering
of XML elements representing list entries in the XML encoding. of XML elements representing list entries in the XML encoding.
Specifically, the "ordered-by" properties (sec. 7.7.7 in
Specifically, the "ordered-by" properties (sec. 7.7.5 in [RFC6020]) [I-D.ietf-netmod-rfc6020bis]) MUST be observed.
MUST be observed.
Unlike the XML encoding, where list keys are required to precede any Unlike the XML encoding, where list keys are required to precede any
other siblings within a list entry, and appear in the order specified other siblings within a list entry, and appear in the order specified
by the data model, the order of members in a JSON-encoded list entry by the data model, the order of members in a JSON-encoded list entry
is arbitrary because JSON objects are fundamentally unordered is arbitrary because JSON objects are fundamentally unordered
collections of members. collections of members.
Example: For the list definition Example: For the list definition
list bar { list bar {
key foo; key foo;
leaf foo { leaf foo {
type uint8; type uint8;
} }
leaf baz { leaf baz {
type string; type string;
} }
} }
the following is a valid instance: the following is a valid JSON-encoded instance:
"bar": [ "bar": [
{ {
"foo": 123, "foo": 123,
"baz": "zig" "baz": "zig"
}, },
{ {
"baz": "zag", "baz": "zag",
"foo": 0 "foo": 0
} }
] ]
5.5. The "anyxml" Data Node 5.5. The "anydata" Data Node
An anyxml instance is encoded as a name/value pair. The value can be Anydata data node is a new feature in YANG 1.1. It serves as a
of any valid JSON type, i.e. an object, array, number, string or one container for data that appear as normal YANG-modeled data, except
of the literals "true", "false" and "null". their data model is not a priori known.
This document imposes no other restrictions on the contents of JSON- An anydata instance is thus encoded in the same way as a container,
encoded anyxml instances. It also doesn't define any universal and its content is subject to the following rules:
mapping between the contents of JSON- and XML-encoded anyxml
instances - note that such a mapping is not needed for the purposes o It is a valid I-JSON message [RFC7493].
of validation (Section 3) because anyxml contents are not subject to
YANG-based validation (see sec. 7.10 in [RFC6020]). However, each o Any member name is either a YANG identifier as defined by the
definition of an anyxml node MAY specify, in its "description" "identifier" production in sec. 13 of
statement, appropriate syntactic, semantic and mapping rules for the [I-D.ietf-netmod-rfc6020bis], or two such identifiers separated by
values of that anyxml data node. the colon character (":"). See also Section 4.
o Any JSON array contains either only unique scalar values (as a
leaf-list, see Section 5.3), or only objects (as a list, see
Section 5.4).
o The "null" value is only allowed in the single-element array
"[null]" corresponding to the encoding of the "empty" type, see
Section 6.9.
If a data model for anydata content is not available, it may be
impossible to map a JSON-encoded anydata instance to XML, and vice
versa. Note, however, that such a mapping is not needed for
validation purposes (Section 3) because anydata contents are
generally not subject to YANG-based validation (see sec. 7.10 in
[I-D.ietf-netmod-rfc6020bis]).
Example: for the anydata definition
anydata data;
the following is a valid JSON-encoded instance:
"data": {
"ietf-notification:notification": {
"eventTime": "2014-07-29T13:43:01Z",
"example-event:event": {
"event-class: "fault",
"reporting-entity": {
"card": "Ethernet0"
},
"severity": "major"
}
}
}
5.6. The "anyxml" Data Node
An anyxml instance is encoded as a JSON name/value pair which MUST
satisfy I-JSON constraints. Otherwise it is unrestricted, i.e., the
value can be an object, array, number, string or one of the literals
"true", "false" and "null".
As in the case of anydata (Section 5.5), there is no universal
procedure for mapping JSON-encoded anyxml instances to XML, and vice
versa.
Example: For the anyxml definition Example: For the anyxml definition
anyxml bar; anyxml bar;
the following is a valid instance: the following is a valid JSON-encoded instance:
"bar": [true, null, true] "bar": [true, null, true]
6. The Mapping of YANG Data Types to JSON Values 6. The Mapping of YANG Data Types to JSON Values
The type of the JSON value in an instance of the leaf or leaf-list The type of the JSON value in an instance of the leaf or leaf-list
data node depends on the type of that data node as specified in the data node depends on the type of that data node as specified in the
following subsections. following subsections.
6.1. Numeric Types 6.1. Numeric Types
A value of the "int8", "int16", "int32", "uint8", "uint16" and A value of the "int8", "int16", "int32", "uint8", "uint16" and
"uint32" is represented as a JSON number. "uint32" is represented as a JSON number.
A value of the "int64", "uint64" or "decimal64" type is encoded as a A value of the "int64", "uint64" or "decimal64" type is encoded as a
JSON string whose contents is the lexical representation of that JSON string whose contents is the lexical representation of that
numeric value as specified in sections 9.2.1 and 9.3.1 of [RFC6020]. numeric value as specified in sections 9.2.1 and 9.3.1 of
[I-D.ietf-netmod-rfc6020bis].
For example, if the type of the leaf "foo" in Section 5.1 was For example, if the type of the leaf "foo" in Section 5.1 was
"uint64" instead of "uint8", the instance would have to be encoded as "uint64" instead of "uint8", the instance would have to be encoded as
"foo": "123" "foo": "123"
The special handling of 64-bit numbers follows from I-JSON The special handling of 64-bit numbers follows from I-JSON
recommendation to encode numbers exceeding the IEEE 754-2008 double recommendation to encode numbers exceeding the IEEE 754-2008 double
precision range as strings, see sec. 2.2 in [I-D.ietf-json-i-json]. precision range as strings, see sec. 2.2 in [RFC7493].
6.2. The "string" Type 6.2. The "string" Type
A "string" value encoded as a JSON string, subject to JSON string A "string" value encoded as a JSON string, subject to JSON string
encoding rules. encoding rules.
6.3. The "boolean" Type 6.3. The "boolean" Type
A "boolean" value is mapped to the corresponding JSON literal name A "boolean" value is mapped to the corresponding JSON literal name
"true" or "false". "true" or "false".
6.4. The "enumeration" Type 6.4. The "enumeration" Type
An "enumeration" value is mapped in the same way as a string except An "enumeration" value is mapped in the same way as a string except
that the permitted values are defined by "enum" statements in YANG. that the permitted values are defined by "enum" statements in YANG.
See sec. 9.6 in [RFC6020]. See sec. 9.6 in [I-D.ietf-netmod-rfc6020bis].
6.5. The "bits" Type 6.5. The "bits" Type
A "bits" value is mapped to a JSON string identical to the lexical A "bits" value is mapped to a JSON string identical to the lexical
representation of this value in XML, i.e., space-separated names representation of this value in XML, i.e., space-separated names
representing the individual bit values that are set. See sec. 9.7 in representing the individual bit values that are set. See sec. 9.7 in
[RFC6020]. [I-D.ietf-netmod-rfc6020bis].
6.6. The "binary" Type 6.6. The "binary" Type
A "binary" value is mapped to a JSON string identical to the lexical A "binary" value is mapped to a JSON string identical to the lexical
representation of this value in XML, i.e., base64-encoded binary representation of this value in XML, i.e., base64-encoded binary
data. See sec. 9.8 in [RFC6020]. data. See sec. 9.8 in [I-D.ietf-netmod-rfc6020bis].
6.7. The "leafref" Type 6.7. The "leafref" Type
A "leafref" value is mapped according to the same rules as the type A "leafref" value is mapped according to the same rules as the type
of the leaf being referred to. of the leaf being referred to.
6.8. The "identityref" Type 6.8. The "identityref" Type
An "identityref" value is mapped to a string representing the name of An "identityref" value is mapped to a string representing the name of
an identity. Its namespace MUST be expressed as shown in Figure 1 if an identity. Its namespace MUST be expressed as shown in Figure 1 if
skipping to change at page 11, line 15 skipping to change at page 12, line 36
"type": "iana-if-type:ethernetCsmacd" "type": "iana-if-type:ethernetCsmacd"
The namespace identifier "iana-if-type" must be present in this case The namespace identifier "iana-if-type" must be present in this case
because the "ethernetCsmacd" identity is not defined in the same because the "ethernetCsmacd" identity is not defined in the same
module as the "type" leaf. module as the "type" leaf.
6.9. The "empty" Type 6.9. The "empty" Type
An "empty" value is mapped to "[null]", i.e., an array with the An "empty" value is mapped to "[null]", i.e., an array with the
"null" literal being its only element. "null" literal being its only element. For the purposes of this
document, "[null]" is treated as an atomic scalar value.
This encoding was chosen instead of using simply "null" in order to This encoding of the "empty" type was chosen instead of using simply
facilitate the use of empty leafs in common programming languages. "null" in order to facilitate the use of empty leafs in common
When used in a boolean context, the "[null]" value, unlike "null", programming languages. When used in a boolean context, the "[null]"
evaluates to true. value, unlike "null", evaluates to true.
Example: For the leaf definition Example: For the leaf definition
leaf foo { leaf foo {
type empty; type empty;
} }
a valid instance is a valid instance is
"foo": [null] "foo": [null]
6.10. The "union" Type 6.10. The "union" Type
A value of the "union" type is encoded as the value of any of the A value of the "union" type is encoded as the value of any of the
member types. member types.
Unlike XML, JSON conveys part of the type information already in the Unlike XML, JSON conveys part of the type information already in the
encoding. When validating a value of the "union" type, this encoding. When validating a value of the "union" type, this
information MUST also be taken into account. information MUST also be taken into account.
skipping to change at page 12, line 23 skipping to change at page 13, line 43
"bar": 13.5 "bar": 13.5
In this case, the JSON encoding indicates the value is supposed to be In this case, the JSON encoding indicates the value is supposed to be
a number rather than a string. a number rather than a string.
6.11. The "instance-identifier" Type 6.11. The "instance-identifier" Type
An "instance-identifier" value is encoded as a string that is An "instance-identifier" value is encoded as a string that is
analogical to the lexical representation in XML encoding, see analogical to the lexical representation in XML encoding, see
sec. 9.13.3 in [RFC6020]. However, the encoding of namespaces in sec. 9.13.3 in [I-D.ietf-netmod-rfc6020bis]. However, the encoding
instance-identifier values follows the rules stated in Section 4, of namespaces in instance-identifier values follows the rules stated
namely: in Section 4, namely:
o The namespace identifier is the module name where each data node o The namespace identifier is the module name where each data node
is defined. is defined.
o The encoding of a node name with an explicit namespace is as shown o The encoding of a node name with an explicit namespace is as shown
in Figure 1. in Figure 1.
o The leftmost (top-level) node name is always prefixed with the o The leftmost (top-level) node name is always prefixed with the
namespace identifier. namespace identifier.
skipping to change at page 13, line 9 skipping to change at page 14, line 28
interfaces", whereas "ipv4" and "ip" are defined in "ietf-ip". interfaces", whereas "ipv4" and "ip" are defined in "ietf-ip".
When translating an instance-identifier value from JSON to XML, the When translating an instance-identifier value from JSON to XML, the
namespace identifier (YANG module name) in each component of the namespace identifier (YANG module name) in each component of the
instance-identifier MUST be replaced by an XML namespace prefix that instance-identifier MUST be replaced by an XML namespace prefix that
is associated with the namespace URI reference of the module in the is associated with the namespace URI reference of the module in the
scope of the element containing the instance-identifier value. scope of the element containing the instance-identifier value.
7. I-JSON Compliance 7. I-JSON Compliance
I-JSON [I-D.ietf-json-i-json] is a restricted profile of JSON that I-JSON [RFC7493] is a restricted profile of JSON that guarantees
guarantees maximum interoperability for protocols that use JSON in maximum interoperability for protocols that use JSON in their
their messages, no matter what JSON encoders/decoders are used in messages, no matter what JSON encoders/decoders are used in protocol
protocol implementations. The encoding defined in this document implementations. The encoding defined in this document therefore
therefore observes the I-JSON requirements and recommendations as observes the I-JSON requirements and recommendations as closely as
closely as possible. possible.
In particular, the following properties are guaranteed: In particular, the following properties are guaranteed:
o Character encoding is UTF-8. o Character encoding is UTF-8.
o Member names within the same JSON object are always unique. o Member names within the same JSON object are always unique.
o The order of JSON object members is never relied upon. o The order of JSON object members is never relied upon.
o Numbers of any type supported by YANG can be exchanged reliably. o Numbers of any type supported by YANG can be exchanged reliably.
See Section 6.1 for details. See Section 6.1 for details.
The only two cases where a JSON instance document encoded according This document deviates from I-JSON only in the encoding of values
to this document may deviate from I-JSON were dictated by the need to with the "binary" type. It uses the base64 encoding scheme
be able to encode the same instance data in both JSON and XML. These (Section 6.6), whereas I-JSON recommends base64url instead.
two exceptions are: Theoretically, values of the "binary" type might appear in URI
references, such as Request-URI in RESTCONF, although in practice the
o Leaf values encoded as strings may contain code points identifying cases where it is really needed should be extremely rare.
Noncharacters that belong to the XML character set (see sec. 2.2
in [W3C.REC-xml-20081126]). This issue is likely to be solved in
YANG 1.1 because noncharacters will not be allowed in string
values, see sec. 9.4 in [I-D.ietf-netmod-rfc6020bis].
o Values of the "binary" type are encoded with the base64 encoding
scheme (Section 6.6), whereas I-JSON recommends base64url instead.
Theoretically, values of the "binary" type might appear in URI
references, such as Request-URI in RESTCONF, although in practice
the cases where it is really needed should be extremely rare.
8. Security Considerations 8. Security Considerations
This document defines an alternative encoding for data modeled in the This document defines an alternative encoding for data modeled in the
YANG data modeling language. As such, it doesn't contribute any new YANG data modeling language. As such, it doesn't contribute any new
security issues beyond those discussed in sec. 15 of [RFC6020]. security issues beyond those discussed in sec. 16 of
[I-D.ietf-netmod-rfc6020bis].
JSON is rather different from XML, and JSON parsers may thus suffer JSON processing is rather different from XML, and JSON parsers may
from other types of vulnerabilities than their XML counterparts. To thus suffer from other types of vulnerabilities than their XML
minimize these security risks, it is important that client and server counterparts. To minimize these new security risks, software on the
software supporting JSON encoding behaves as required in sec. 3 of receiving side SHOULD reject all messages that do not comply to the
[I-D.ietf-json-i-json]. That is, received JSON data that violate any rules of this document and reply with an appropriate error message to
of I-JSON strict constraints MUST NOT be trusted nor acted upon. the sender.
Violations due to the presence of Unicode Noncharacters in the data
(see Section 7) SHOULD be carefully examined.
9. Acknowledgments 9. Acknowledgments
The author wishes to thank Andy Bierman, Martin Bjorklund, Dean The author wishes to thank Andy Bierman, Martin Bjorklund, Dean
Bogdanovic, Balazs Lengyel, Juergen Schoenwaelder and Phil Shafer for Bogdanovic, Balazs Lengyel, Juergen Schoenwaelder and Phil Shafer for
their helpful comments and suggestions. their helpful comments and suggestions.
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.ietf-json-i-json] [I-D.ietf-netmod-rfc6020bis]
Bray, T., "The I-JSON Message Format", draft-ietf-json- Bjorklund, M., "YANG - A Data Modeling Language for the
i-json-06 (work in progress), January 2015. Network Configuration Protocol (NETCONF)", draft-ietf-
netmod-rfc6020bis-05 (work in progress), May 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Network Configuration Protocol (NETCONF)", RFC 6020, Specifications: ABNF", STD 68, RFC 5234, January 2008.
October 2010.
[RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A.
Bierman, "Network Configuration Protocol (NETCONF)", RFC Bierman, "Network Configuration Protocol (NETCONF)", RFC
6241, June 2011. 6241, June 2011.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
[RFC7493] Bray, T., "The I-JSON Message Format", RFC 7493, March
2015.
[W3C.REC-xml-20081126] [W3C.REC-xml-20081126]
Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC- Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008, xml-20081126, November 2008,
<http://www.w3.org/TR/2008/REC-xml-20081126>. <http://www.w3.org/TR/2008/REC-xml-20081126>.
10.2. Informative References 10.2. Informative References
[I-D.ietf-netconf-restconf] [I-D.ietf-netconf-restconf]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", draft-ietf-netconf-restconf-04 (work in Protocol", draft-ietf-netconf-restconf-05 (work in
progress), January 2015. progress), June 2015.
[I-D.ietf-netmod-rfc6020bis]
Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", draft-ietf-
netmod-rfc6020bis-03 (work in progress), January 2015.
[RFC7223] Bjorklund, M., "A YANG Data Model for Interface [RFC7223] Bjorklund, M., "A YANG Data Model for Interface
Management", RFC 7223, May 2014. Management", RFC 7223, May 2014.
[W3C.REC-xpath-19991116] [W3C.REC-xpath-19991116]
Clark, J. and S. DeRose, "XML Path Language (XPath) Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Recommendation Version 1.0", World Wide Web Consortium Recommendation
REC-xpath-19991116, November 1999, REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>. <http://www.w3.org/TR/1999/REC-xpath-19991116>.
skipping to change at page 17, line 28 skipping to change at page 18, line 37
} }
} }
] ]
} }
} }
Appendix B. Change Log Appendix B. Change Log
RFC Editor: Remove this section upon publication as an RFC. RFC Editor: Remove this section upon publication as an RFC.
B.1. Changes Between Revisions -02 and -03 B.1. Changes Between Revisions -03 and -04
o I-D.ietf-netmod-rfc6020bis is used as a normative reference
instead of RFC 6020.
o Removed noncharacters as an I-JSON issue because it doesn't exist
in YANG 1.1.
o Section about anydata encoding was added.
o Require I-JSON for anyxml encoding.
o Use ABNF for defining qualified name.
B.2. Changes Between Revisions -02 and -03
o Namespace encoding is defined without using RFC 2119 keywords. o Namespace encoding is defined without using RFC 2119 keywords.
o Specification for anyxml nodes was extended and clarified. o Specification for anyxml nodes was extended and clarified.
o Text about ordering of list entries was corrected. o Text about ordering of list entries was corrected.
B.2. Changes Between Revisions -01 and -02 B.3. Changes Between Revisions -01 and -02
o Encoding of namespaces in instance-identifiers was changed. o Encoding of namespaces in instance-identifiers was changed.
o Text specifying the order of array elements in leaf-list and list o Text specifying the order of array elements in leaf-list and list
instances was added. instances was added.
B.3. Changes Between Revisions -00 and -01 B.4. Changes Between Revisions -00 and -01
o Metadata encoding was moved to a separate I-D, draft-lhotka- o Metadata encoding was moved to a separate I-D, draft-lhotka-
netmod-yang-metadata. netmod-yang-metadata.
o JSON encoding is now defined directly rather than via XML-JSON o JSON encoding is now defined directly rather than via XML-JSON
mapping. mapping.
o The rules for namespace encoding has changed. This affect both o The rules for namespace encoding has changed. This affect both
node instance names and instance-identifiers. node instance names and instance-identifiers.
 End of changes. 62 change blocks. 
161 lines changed or deleted 215 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/