One document matched: draft-ietf-netmod-yang-json-04.xml
<?xml version="1.0"?>
<?rfc strict="yes"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc docName="draft-ietf-netmod-yang-json-04" ipr="trust200902" category="std" obsoletes="" updates="" submissionType="IETF" xml:lang="en">
<front>
<title abbrev="JSON Encoding of YANG Data">JSON Encoding of Data
Modeled with YANG</title>
<author initials="L." surname="Lhotka" fullname="Ladislav Lhotka">
<organization>CZ.NIC</organization>
<address>
<email>lhotka@nic.cz</email>
</address>
</author>
<date day="12" month="June" year="2015"/>
<area>Operations and Management</area>
<area>Operations and Management</area>
<workgroup>NETMOD Working Group</workgroup>
<abstract>
<t>This document defines encoding rules for representing
configuration, state data, RPC input and output parameters, and
notifications defined using YANG as JavaScript Object Notation
(JSON) text.</t>
</abstract>
</front>
<middle>
<section anchor="sec.introduction" title="Introduction" toc="default">
<t>The NETCONF protocol <xref target="RFC6241" pageno="false" format="default"/> uses XML <xref target="W3C.REC-xml-20081126" pageno="false" format="default"/> for encoding data in its Content
Layer. Other management protocols might want to use other
encodings while still benefiting from using YANG <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/> as the data modeling
language.</t>
<t>For example, the RESTCONF protocol <xref target="I-D.ietf-netconf-restconf" pageno="false" format="default"/> supports two encodings: XML
(media type "application/yang.data+xml") and JSON (media type
"application/yang.data+json).</t>
<t>The specification of YANG 1.1 data modelling language <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/> defines only XML encoding
for data instances, i.e., contents of configuration datastores,
state data, RFC input and output parameters, and event
notifications. The aim of this document is to define rules for
encoding the same data as JavaScript Object Notation (JSON)
text <xref target="RFC7159" pageno="false" format="default"/>.</t>
<t>In order to achieve maximum interoperability while allowing
implementations to use a variety of available JSON parsers, the
JSON encoding rules follow, as much as possible, the constraints
of the I-JSON restricted profile <xref target="RFC7493" pageno="false" format="default"/>. <xref target="sec.i-json" pageno="false" format="default"/> discusses I-JSON conformance in more
detail.</t>
</section>
<section anchor="sec.term-not" title="Terminology and Notation" toc="default">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
in this document are to be interpreted as described in <xref target="RFC2119" pageno="false" format="default"/>.</t>
<t>The following terms are defined in <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>:
<list style="symbols">
<t>anydata,</t>
<t>anyxml,</t>
<t>augment,</t>
<t>container,</t>
<t>data node,</t>
<t>identity,</t>
<t>instance identifier,</t>
<t>leaf,</t>
<t>leaf-list,</t>
<t>list,</t>
<t>module,</t>
<t>submodule.</t>
</list></t>
</section>
<section anchor="sec.valid" title="Validation of JSON-encoded Instance Data" toc="default">
<t>Instance data validation as defined in <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>, sec. 8.3.3, is only
applicable to XML-encoded data. For one, semantic constraints in
"must" statements are expressed using XPath 1.0 <xref target="W3C.REC-xpath-19991116" pageno="false" format="default"/>, which can be properly
interpreted only in the XML context.</t>
<t>This document and the corresponding "XML Mapping Rules"
sections from <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/> also
define an implicit schema-driven mapping of JSON-encoded
instances to XML-encoded instances (and vice versa). This
mapping is mostly straightforward. In cases where doubts could
arise, this document gives explicit instructions for mapping
JSON-encoded instances to XML.</t>
<t>In order to validate a JSON instance document, it needs first
to be mapped, at least conceptually, to the corresponding XML
instance document. By definition, the JSON document is then
valid if and only if the XML document is valid according to the
rules stated in <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>.</t>
</section>
<section anchor="sec.names-ns" title="Names and Namespaces" toc="default">
<t>Instances of YANG data nodes (leafs, containers, leaf-lists,
lists, anydata and anyxml nodes) are always encoded as members
of a JSON object, i.e., as name/value pairs. This section
defines how the name part is formed, and the following sections
deal with the value part.</t>
<t>Except in the cases specified below, the member name is
identical to the identifier of the corresponding YANG data
node. Every such name belongs to a namespace which is associated
with the YANG module where the corresponding data node is
defined. If the data node is defined in a submodule, then the
namespace is determined by the main module to which the
submodule belongs.</t>
<t>If the namespace of a member name has to be explicitly
specified, the 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 character (":"). Using ABNF <xref target="RFC5234" pageno="false" format="default"/>, the namespace-qualified name can be
expressed as shown in <xref target="fig.ns-enc" pageno="false" format="default"/>, where the
production for "identifier" is defined in sec. 13 of <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>.</t>
<figure anchor="fig.ns-enc" title="ABNF production for a qualified member name." suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
qualified-member-name = identifier ":" identifier
</artwork>
</figure>
<t>Names with namespace identifiers in the form shown in <xref target="fig.ns-enc" pageno="false" format="default"/> are used if and only if the parent data
node belongs to a different namespace, which also includes all
top-level YANG data nodes that have no parent node.</t>
<t>For example, consider the following YANG module:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
module foomod {
namespace "http://example.com/foomod";
prefix "foo";
container top {
leaf foo {
type uint8;
}
}
}
</artwork>
</figure></t>
<t>If the data model consists only of this module, then the
following is a valid JSON-encoded configuration:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
{
"foomod:top": {
"foo": 54
}
}
</artwork>
</figure>
</t>
<t>Note that the top-level container instance contains the
namespace identifier (module name) but the "foo" leaf doesn't
because it is defined in the same module as its parent container.</t>
<t>Now, assume the container "top" is augmented from another
module, "barmod":
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
module barmod {
namespace "http://example.com/barmod";
prefix "bar";
import foomod {
prefix "foo";
}
augment "/foo:top" {
leaf bar {
type boolean;
}
}
}
</artwork>
</figure>
</t>
<t>A valid JSON-encoded configuration containing both leafs may
then look like this:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
{
"foomod:top": {
"foo": 54,
"barmod:bar": true
}
}
</artwork>
</figure>
</t>
<t>The name of the "bar" leaf is prefixed with the namespace
identifier because its parent is defined in a different module,
hence it belongs to another namespace.</t>
<t>Explicit namespace identifiers are sometimes needed when
encoding values of the "identityref" and "instances-identifier"
types. The same form as shown in <xref target="fig.ns-enc" pageno="false" format="default"/> is
then used as well. See Sections <xref format="counter" target="sec.idref" pageno="false"/> and <xref format="counter" target="sec.i-i" pageno="false"/> for details.</t>
</section>
<section anchor="sec.datanodes" title="Encoding of YANG Data Node Instances" toc="default">
<t>Every complete JSON instance document, such as a
configuration datastore content, is an object. Its members are
instances of all top-level data nodes defined by the YANG data
model.</t>
<t>Character encoding MUST be UTF-8.</t>
<t>Any data node instance is encoded as a name/value pair where
the name is formed from the data node identifier using the rules
of <xref target="sec.names-ns" pageno="false" format="default"/>. The value depends on the
category of the data node as explained in the following
subsections.</t>
<section anchor="sec.leaf" title="The "leaf" Data Node" toc="default">
<t>A leaf instance is encoded as a name/value pair where the
value can be a string, number, literal "true" or "false", or
the special array "[null]", depending on the type of the leaf
(see <xref target="sec.datatypes" pageno="false" format="default"/> for the type encoding
rules).</t>
<t>Example: For the leaf node definition
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
leaf foo {
type uint8;
}
</artwork>
</figure>
the following is a valid JSON-encoded instance:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
"foo": 123
</artwork>
</figure>
</t>
</section>
<section anchor="sec.container" title="The "container" Data Node" toc="default">
<t>A container instance is encoded as a name/object pair. The
container's child data nodes are encoded as members of the
object.</t>
<t>Example: For the container definition
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
container bar {
leaf foo {
type uint8;
}
}
</artwork>
</figure>
the following is a valid JSON-encoded instance:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
"bar": {
"foo": 123
}
</artwork>
</figure>
</t>
</section>
<section anchor="sec.leaf-list" title="The "leaf-list" Data Node" toc="default">
<t>A leaf-list is encoded as a name/array pair, and the array
elements are values of some scalar type, which can be a
string, number, literal "true" or "false", or the special
array "[null]", depending on the type of the leaf-list (see
<xref target="sec.datatypes" pageno="false" format="default"/> for the type encoding
rules).</t>
<t>The ordering of array elements follows the same rules as
the ordering of XML elements representing leaf-list entries in
the XML encoding. Specifically, the "ordered-by" properties
(sec. 7.7.7 in <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>)
MUST be observed.</t>
<t>Example: For the leaf-list definition
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
leaf-list foo {
type uint8;
}
</artwork>
</figure>
the following is a valid JSON-encoded instance:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
"foo": [123, 0]
</artwork>
</figure>
</t>
</section>
<section anchor="sec.list" title="The "list" Data Node" toc="default">
<t>A list instance is encoded as a name/array pair, and the
array elements are JSON objects.</t>
<t>The ordering of array elements follows the same rules as
the ordering of XML elements representing list entries in the
XML encoding. Specifically, the "ordered-by" properties
(sec. 7.7.7 in <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>)
MUST be observed.</t>
<t>Unlike the XML encoding, where list keys are required to
precede any 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 is arbitrary because JSON objects
are fundamentally unordered collections of members.</t>
<t>Example: For the list definition
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
list bar {
key foo;
leaf foo {
type uint8;
}
leaf baz {
type string;
}
}
</artwork>
</figure>
the following is a valid JSON-encoded instance:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
"bar": [
{
"foo": 123,
"baz": "zig"
},
{
"baz": "zag",
"foo": 0
}
]
</artwork>
</figure>
</t>
</section>
<section anchor="sec.anydata" title="The "anydata" Data Node" toc="default">
<t>Anydata data node is a new feature in YANG 1.1. It serves
as a container for data that appear as normal YANG-modeled
data, except their data model is not a priori known.</t>
<t>An anydata instance is thus encoded in the same way as a
container, and its content is subject to the following rules:
<list style="symbols">
<t>It is a valid I-JSON message <xref target="RFC7493" pageno="false" format="default"/>.</t>
<t>Any member name is either a YANG identifier as defined by
the "identifier" production in sec. 13 of <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>, or two such
identifiers separated by the colon character (":"). See also
<xref target="sec.names-ns" pageno="false" format="default"/>.</t>
<t>Any JSON array contains either only unique scalar values
(as a leaf-list, see <xref target="sec.leaf-list" pageno="false" format="default"/>), or
only objects (as a list, see <xref target="sec.list" pageno="false" format="default"/>).</t>
<t>The "null" value is only allowed in the single-element
array "[null]" corresponding to the encoding of the "empty"
type, see <xref target="sec.empty" pageno="false" format="default"/>.</t>
</list></t>
<t>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 (<xref target="sec.valid" pageno="false" format="default"/>)
because anydata contents are generally not subject to
YANG-based validation (see sec. 7.10 in <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>).</t>
<t>Example: for the anydata definition
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
anydata data;
</artwork>
</figure>
the following is a valid JSON-encoded instance:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
"data": {
"ietf-notification:notification": {
"eventTime": "2014-07-29T13:43:01Z",
"example-event:event": {
"event-class: "fault",
"reporting-entity": {
"card": "Ethernet0"
},
"severity": "major"
}
}
}
</artwork>
</figure>
</t>
</section>
<section anchor="sec.anyxml" title="The "anyxml" Data Node" toc="default">
<t>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".</t>
<t>As in the case of anydata (<xref target="sec.anydata" pageno="false" format="default"/>),
there is no universal procedure for mapping JSON-encoded
anyxml instances to XML, and vice versa.</t>
<t>Example: For the anyxml definition
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
anyxml bar;
</artwork>
</figure>
the following is a valid JSON-encoded instance:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
"bar": [true, null, true]
</artwork>
</figure>
</t>
</section>
</section>
<section anchor="sec.datatypes" title="The Mapping of YANG Data Types to JSON Values" toc="default">
<t>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 following subsections.</t>
<section anchor="sec.numtypes" title="Numeric Types" toc="default">
<t>A value of the "int8", "int16", "int32", "uint8", "uint16"
and "uint32" is represented as a JSON number.</t>
<t>A value of the "int64", "uint64" or "decimal64" type is
encoded as a JSON string whose contents is the lexical
representation of that numeric value as specified in sections
9.2.1 and 9.3.1 of <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>.</t>
<t>For example, if the type of the leaf "foo" in <xref target="sec.leaf" pageno="false" format="default"/> was "uint64" instead of "uint8", the
instance would have to be encoded as</t>
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
"foo": "123"
</artwork>
</figure>
<t>The special handling of 64-bit numbers follows from I-JSON
recommendation to encode numbers exceeding the IEEE 754-2008
double precision range as strings, see sec. 2.2 in <xref target="RFC7493" pageno="false" format="default"/>.</t>
</section>
<section anchor="sec.string" title="The "string" Type" toc="default">
<t>A "string" value encoded as a JSON string, subject to JSON
string encoding rules.</t>
</section>
<section anchor="sec.boolean" title="The "boolean" Type" toc="default">
<t>A "boolean" value is mapped to the corresponding JSON
literal name "true" or "false".</t>
</section>
<section anchor="sec.enum" title="The "enumeration" Type" toc="default">
<t>An "enumeration" value is mapped in the same way as a
string except that the permitted values are defined by "enum"
statements in YANG. See sec. 9.6 in <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>.</t>
</section>
<section anchor="sec.bits" title="The "bits" Type" toc="default">
<t>A "bits" value is mapped to a JSON string identical to the
lexical representation of this value in XML, i.e.,
space-separated names representing the individual bit values
that are set. See sec. 9.7 in <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>.</t>
</section>
<section anchor="sec.binary" title="The "binary" Type" toc="default">
<t>A "binary" value is mapped to a JSON string identical to
the lexical representation of this value in XML, i.e.,
base64-encoded binary data. See sec. 9.8 in <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>.</t>
</section>
<section anchor="sec.leafref" title="The "leafref" Type" toc="default">
<t>A "leafref" value is mapped according to the same rules as
the type of the leaf being referred to.</t>
</section>
<section anchor="sec.idref" title="The "identityref" Type" toc="default">
<t>An "identityref" value is mapped to a string representing
the name of an identity. Its namespace MUST be expressed as
shown in <xref target="fig.ns-enc" pageno="false" format="default"/> if it is different from
the namespace of the leaf node containing the identityref
value, and MAY be expressed otherwise.</t>
<t>For example, consider the following schematic module:</t>
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
module exmod {
...
import ietf-interfaces {
prefix if;
}
import iana-if-type {
prefix ianaift;
}
...
leaf type {
type identityref {
base "if:interface-type";
}
}
}
</artwork>
</figure>
<t>A valid instance of the "type" leaf is then encoded as
follows:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
"type": "iana-if-type:ethernetCsmacd"
</artwork>
</figure>
</t>
<t>The namespace identifier "iana-if-type" must be present in
this case because the "ethernetCsmacd" identity is not defined
in the same module as the "type" leaf.</t>
</section>
<section anchor="sec.empty" title="The "empty" Type" toc="default">
<t>An "empty" value is mapped to "[null]", i.e., an array with
the "null" literal being its only element. For the purposes of
this document, "[null]" is treated as an atomic scalar
value.</t>
<t>This encoding of the "empty" type was chosen instead of
using simply "null" in order to facilitate the use of empty
leafs in common programming languages. When used in a boolean
context, the "[null]" value, unlike "null", evaluates to
true.</t>
<t>Example: For the leaf definition
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
leaf foo {
type empty;
}
</artwork>
</figure>
a valid instance is
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
"foo": [null]
</artwork>
</figure>
</t>
</section>
<section anchor="sec.union" title="The "union" Type" toc="default">
<t>A value of the "union" type is encoded as the value of any
of the member types.</t>
<t>Unlike XML, JSON conveys part of the type information
already in the encoding. When validating a value of the
"union" type, this information MUST also be taken into account.</t>
<t>For example, consider the following YANG definition:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
leaf bar {
type union {
type uint16;
type string;
}
}
</artwork>
</figure>
In RESTCONF <xref target="I-D.ietf-netconf-restconf" pageno="false" format="default"/>, it is
fully acceptable to set the value of "bar" in the following
way when using the "application/yang.data+xml" media type:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
<bar>13.5</bar>
</artwork>
</figure>
because the value may be interpreted as a string, i.e., the
second member type of the union. When using the
"application/yang.data+json" media type, however, this is an error:
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
"bar": 13.5
</artwork>
</figure>
In this case, the JSON encoding indicates the value is
supposed to be a number rather than a string.
</t>
</section>
<section anchor="sec.i-i" title="The "instance-identifier" Type" toc="default">
<t>An "instance-identifier" value is encoded as a string that
is analogical to the lexical representation in XML encoding,
see sec. 9.13.3 in <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>. However, the encoding
of namespaces in instance-identifier values follows the rules
stated in <xref target="sec.names-ns" pageno="false" format="default"/>, namely:
<list style="symbols">
<t>The namespace identifier is the module name where each
data node is defined.</t>
<t>The encoding of a node name with an explicit namespace is
as shown in <xref target="fig.ns-enc" pageno="false" format="default"/>.</t>
<t>The leftmost (top-level) node name is always prefixed
with the namespace identifier.</t>
<t>Any subsequent node name has the namespace identifier if
and only if its parent node has a different namespace. This
also holds for node names appearing in predicates.</t>
</list></t>
<t>For example,
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
/ietf-interfaces:interfaces/interface[name='eth0']/ietf-ip:ipv4/ip
</artwork>
</figure>
is a valid instance-identifer value because the data nodes
"interfaces", "interface" and "name" are defined in the module
"ietf-interfaces", whereas "ipv4" and "ip" are defined in
"ietf-ip".</t>
<t>When translating an instance-identifier value from JSON to
XML, the namespace identifier (YANG module name) in each
component of the instance-identifier MUST be replaced by an
XML namespace prefix that is associated with the namespace URI
reference of the module in the scope of the element containing
the instance-identifier value.</t>
</section>
</section>
<section anchor="sec.i-json" title="I-JSON Compliance" toc="default">
<t>I-JSON <xref target="RFC7493" pageno="false" format="default"/> is a restricted profile of
JSON that guarantees maximum interoperability for protocols that
use JSON in their messages, no matter what JSON
encoders/decoders are used in protocol implementations. The
encoding defined in this document therefore observes the I-JSON
requirements and recommendations as closely as possible.</t>
<t>In particular, the following properties are guaranteed:
<list style="symbols">
<t>Character encoding is UTF-8.</t>
<t>Member names within the same JSON object are always unique.</t>
<t>The order of JSON object members is never relied upon.</t>
<t>Numbers of any type supported by YANG can be exchanged
reliably. See <xref target="sec.numtypes" pageno="false" format="default"/> for details.</t>
</list>
</t>
<t>This document deviates from I-JSON only in the encoding of
values with the "binary" type. It uses the base64 encoding
scheme (<xref target="sec.binary" pageno="false" format="default"/>), 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.</t>
</section>
<section anchor="sec.cons" title="Security Considerations" toc="default">
<t>This document defines an alternative encoding for data
modeled in the YANG data modeling language. As such, it doesn't
contribute any new security issues beyond those discussed in
sec. 16 of <xref target="I-D.ietf-netmod-rfc6020bis" pageno="false" format="default"/>.</t>
<t>JSON processing is rather different from XML, and JSON
parsers may thus suffer from other types of vulnerabilities than
their XML counterparts. To minimize these new security risks,
software on the receiving side SHOULD reject all messages that
do not comply to the rules of this document and reply with an
appropriate error message to the sender.</t>
</section>
<section anchor="sec.ack" title="Acknowledgments" toc="default">
<t>The author wishes to thank Andy Bierman, Martin Bjorklund,
Dean Bogdanovic, Balazs Lengyel, Juergen Schoenwaelder and Phil
Shafer for their helpful comments and suggestions.</t>
</section>
</middle>
<back>
<references title="Normative References">
<reference anchor="RFC7159">
<front>
<title>The JavaScript Object Notation (JSON) Data Interchange Format</title>
<author initials="T." surname="Bray" fullname="T. Bray">
<organization/></author>
<date year="2014" month="March"/>
<abstract>
<t>JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data.</t><t> This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.</t></abstract></front>
<seriesInfo name="RFC" value="7159"/>
<format type="TXT" octets="27451" target="http://www.rfc-editor.org/rfc/rfc7159.txt"/>
</reference>
<reference anchor="RFC2119">
<front>
<title abbrev="RFC Key Words">Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials="S." surname="Bradner" fullname="Scott Bradner">
<organization>Harvard University</organization>
<address>
<postal>
<street>1350 Mass. Ave.</street>
<street>Cambridge</street>
<street>MA 02138</street></postal>
<phone>- +1 617 495 3864</phone>
<email>sob@harvard.edu</email></address></author>
<date year="1997" month="March"/>
<area>General</area>
<keyword>keyword</keyword>
<abstract>
<t>
In many standards track documents several words are used to signify
the requirements in the specification. These words are often
capitalized. This document defines these words as they should be
interpreted in IETF documents. Authors who follow these guidelines
should incorporate this phrase near the beginning of their document:
<list>
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
</t></list></t>
<t>
Note that the force of these words is modified by the requirement
level of the document in which they are used.
</t></abstract></front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="2119"/>
<format type="TXT" octets="4723" target="http://www.rfc-editor.org/rfc/rfc2119.txt"/>
<format type="HTML" octets="17970" target="http://xml.resource.org/public/rfc/html/rfc2119.html"/>
<format type="XML" octets="5777" target="http://xml.resource.org/public/rfc/xml/rfc2119.xml"/>
</reference>
<reference anchor="RFC5234">
<front>
<title>Augmented BNF for Syntax Specifications: ABNF</title>
<author initials="D." surname="Crocker" fullname="D. Crocker">
<organization/></author>
<author initials="P." surname="Overell" fullname="P. Overell">
<organization/></author>
<date year="2008" month="January"/>
<abstract>
<t>Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK]</t></abstract></front>
<seriesInfo name="STD" value="68"/>
<seriesInfo name="RFC" value="5234"/>
<format type="TXT" octets="26359" target="http://www.rfc-editor.org/rfc/rfc5234.txt"/>
</reference>
<reference anchor="I-D.ietf-netmod-rfc6020bis">
<front>
<title>YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)</title>
<author initials="M" surname="Bjorklund" fullname="Martin Bjorklund">
<organization/>
</author>
<date month="May" day="4" year="2015"/>
<abstract><t>YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. This document obsoletes RFC 6020.</t></abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-netmod-rfc6020bis-05"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-netmod-rfc6020bis-05.txt"/>
</reference>
<reference anchor="RFC6241">
<front>
<title>Network Configuration Protocol (NETCONF)</title>
<author initials="R." surname="Enns" fullname="R. Enns">
<organization/></author>
<author initials="M." surname="Bjorklund" fullname="M. Bjorklund">
<organization/></author>
<author initials="J." surname="Schoenwaelder" fullname="J. Schoenwaelder">
<organization/></author>
<author initials="A." surname="Bierman" fullname="A. Bierman">
<organization/></author>
<date year="2011" month="June"/>
<abstract>
<t>The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls (RPCs). This document obsoletes RFC 4741. [STANDARDS-TRACK]</t></abstract></front>
<seriesInfo name="RFC" value="6241"/>
<format type="TXT" octets="209465" target="http://www.rfc-editor.org/rfc/rfc6241.txt"/>
</reference>
<reference anchor="RFC7493">
<front>
<title>The I-JSON Message Format</title>
<author initials="T." surname="Bray" fullname="T. Bray">
<organization/></author>
<date year="2015" month="March"/>
<abstract>
<t>I-JSON (short for "Internet JSON") is a restricted profile of JSON designed to maximize interoperability and increase confidence that software can process it successfully with predictable results.</t></abstract></front>
<seriesInfo name="RFC" value="7493"/>
<format type="TXT" octets="12849" target="http://www.rfc-editor.org/rfc/rfc7493.txt"/>
</reference>
<reference anchor="W3C.REC-xml-20081126" target="http://www.w3.org/TR/2008/REC-xml-20081126">
<front>
<title>Extensible Markup Language (XML) 1.0 (Fifth Edition)</title>
<author initials="T." surname="Bray" fullname="Tim Bray">
<organization/>
</author>
<author initials="J." surname="Paoli" fullname="Jean Paoli">
<organization/>
</author>
<author initials="M." surname="Sperberg-McQueen" fullname="Michael Sperberg-McQueen">
<organization/>
</author>
<author initials="E." surname="Maler" fullname="Eve Maler">
<organization/>
</author>
<author initials="F." surname="Yergeau" fullname="François Yergeau">
<organization/>
</author>
<date month="November" day="26" year="2008"/>
</front>
<seriesInfo name="World Wide Web Consortium Recommendation" value="REC-xml-20081126"/>
<format type="HTML" target="http://www.w3.org/TR/2008/REC-xml-20081126"/>
</reference>
</references>
<references title="Informative References">
<reference anchor="RFC7223">
<front>
<title>A YANG Data Model for Interface Management</title>
<author initials="M." surname="Bjorklund" fullname="M. Bjorklund">
<organization/></author>
<date year="2014" month="May"/>
<abstract>
<t>This document defines a YANG data model for the management of network interfaces. It is expected that interface-type-specific data models augment the generic interfaces data model defined in this document. The data model includes configuration data and state data (status information and counters for the collection of statistics).</t></abstract></front>
<seriesInfo name="RFC" value="7223"/>
<format type="TXT" octets="70537" target="http://www.rfc-editor.org/rfc/rfc7223.txt"/>
</reference>
<reference anchor="W3C.REC-xpath-19991116" target="http://www.w3.org/TR/1999/REC-xpath-19991116">
<front>
<title>XML Path Language (XPath) Version 1.0</title>
<author initials="J." surname="Clark" fullname="James Clark">
<organization/>
</author>
<author initials="S." surname="DeRose" fullname="Steven DeRose">
<organization/>
</author>
<date month="November" day="16" year="1999"/>
</front>
<seriesInfo name="World Wide Web Consortium Recommendation" value="REC-xpath-19991116"/>
<format type="HTML" target="http://www.w3.org/TR/1999/REC-xpath-19991116"/>
</reference>
<reference anchor="I-D.ietf-netconf-restconf">
<front>
<title>RESTCONF Protocol</title>
<author initials="A" surname="Bierman" fullname="Andy Bierman">
<organization/>
</author>
<author initials="M" surname="Bjorklund" fullname="Martin Bjorklund">
<organization/>
</author>
<author initials="K" surname="Watsen" fullname="Kent Watsen">
<organization/>
</author>
<date month="June" day="4" year="2015"/>
<abstract><t>This document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastores defined in NETCONF.</t></abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-netconf-restconf-05"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-netconf-restconf-05.txt"/>
</reference>
</references>
<section anchor="app.ex-if" title="A Complete Example" toc="default">
<t>The JSON document shown below represents the same data as the
reply to the NETCONF <get> request appearing in Appendix D
of <xref target="RFC7223" pageno="false" format="default"/>. The data model is a combination of
two YANG modules: "ietf-interfaces" and "ex-vlan" (the latter is
an example module from Appendix C of <xref target="RFC7223" pageno="false" format="default"/>). The "if-mib" feature defined in the
"ietf-interfaces" module is considered to be active.</t>
<figure title="" suppress-title="false" align="left" alt="" width="" height="">
<artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height="">
{
"ietf-interfaces:interfaces": {
"interface": [
{
"name": "eth0",
"type": "iana-if-type:ethernetCsmacd",
"enabled": false
},
{
"name": "eth1",
"type": "iana-if-type:ethernetCsmacd",
"enabled": true,
"ex-vlan:vlan-tagging": true
},
{
"name": "eth1.10",
"type": "iana-if-type:l2vlan",
"enabled": true,
"ex-vlan:base-interface": "eth1",
"ex-vlan:vlan-id": 10
},
{
"name": "lo1",
"type": "iana-if-type:softwareLoopback",
"enabled": true
}
]
},
"ietf-interfaces:interfaces-state": {
"interface": [
{
"name": "eth0",
"type": "iana-if-type:ethernetCsmacd",
"admin-status": "down",
"oper-status": "down",
"if-index": 2,
"phys-address": "00:01:02:03:04:05",
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "eth1",
"type": "iana-if-type:ethernetCsmacd",
"admin-status": "up",
"oper-status": "up",
"if-index": 7,
"phys-address": "00:01:02:03:04:06",
"higher-layer-if": [
"eth1.10"
],
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "eth1.10",
"type": "iana-if-type:l2vlan",
"admin-status": "up",
"oper-status": "up",
"if-index": 9,
"lower-layer-if": [
"eth1"
],
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "eth2",
"type": "iana-if-type:ethernetCsmacd",
"admin-status": "down",
"oper-status": "down",
"if-index": 8,
"phys-address": "00:01:02:03:04:07",
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
},
{
"name": "lo1",
"type": "iana-if-type:softwareLoopback",
"admin-status": "up",
"oper-status": "up",
"if-index": 1,
"statistics": {
"discontinuity-time": "2013-04-01T03:00:00+00:00"
}
}
]
}
}
</artwork>
</figure>
</section>
<section title="Change Log" toc="default">
<t>RFC Editor: Remove this section upon publication as an RFC.</t>
<section title="Changes Between Revisions -03 and -04" toc="default">
<t>
<list style="symbols">
<t>I-D.ietf-netmod-rfc6020bis is used as a normative
reference instead of RFC 6020.</t>
<t>Removed noncharacters as an I-JSON issue because it
doesn't exist in YANG 1.1.</t>
<t>Section about anydata encoding was added.</t>
<t>Require I-JSON for anyxml encoding.</t>
<t>Use ABNF for defining qualified name.</t>
</list>
</t>
</section>
<section title="Changes Between Revisions -02 and -03" toc="default">
<t>
<list style="symbols">
<t>Namespace encoding is defined without using RFC 2119
keywords.</t>
<t>Specification for anyxml nodes was extended and
clarified.</t>
<t>Text about ordering of list entries was corrected.</t>
</list>
</t>
</section>
<section title="Changes Between Revisions -01 and -02" toc="default">
<t>
<list style="symbols">
<t>Encoding of namespaces in instance-identifiers was changed.</t>
<t>Text specifying the order of array elements in
leaf-list and list instances was added.</t>
</list>
</t>
</section>
<section title="Changes Between Revisions -00 and -01" toc="default">
<t>
<list style="symbols">
<t>Metadata encoding was moved to a separate I-D,
draft-lhotka-netmod-yang-metadata.</t>
<t>JSON encoding is now defined directly rather than via
XML-JSON mapping.</t>
<t>The rules for namespace encoding has changed. This
affect both node instance names and
instance-identifiers.</t>
<t>I-JSON-related changes. The most significant is the
string encoding of 64-bit numbers.</t>
<t>When validating union type, the partial type info
present in JSON encoding is taken into account.</t>
<t>Added section about I-JSON compliance.</t>
<t>Updated the example in appendix.</t>
<t>Wrote Security Considerations.</t>
<t>Removed IANA Considerations as there are none.</t>
</list>
</t>
</section>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 02:51:03 |