wdiff draft-ietf-netmod-yang-json-00.txt draft-ietf-netmod-yang-json-01.txt

NETMOD Working Group L. Lhotka
Internet-Draft CZ.NIC
Intended status: Standards Track April 21, 2014
Expires: October 23, 13, 2014
Expires: April 16, 2015

JSON Encoding of Data Modeled with YANG
draft-ietf-netmod-yang-json-00
draft-ietf-netmod-yang-json-01

Abstract

This document defines encoding rules for representing configuration and configuration,
state
data data, RPC input and output parameters, and notifications
defined using YANG as JSON JavaScript Object Notation (JSON) text. It does so by specifying a
procedure for translating the subset of YANG-compatible XML documents
to JSON text, and vice versa. A JSON encoding of XML attributes is
also defined so as to allow for including metadata in JSON documents.

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 http://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 October 23, 2014. April 16, 2015.

This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://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 extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.

Table of Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology and Notation . . . . . . . . . . . . . . . . . . 4 3
3. Specification Validation of the Translation Procedure JSON-encoded
Instance Data . . . . . . . . . . . . . . . . . . . 5
3.1. . . . . . 3
4. Names and Namespaces . . . . . . . . . . . . . . . . . . 6
3.2. Mapping XML Elements to JSON Objects . . 4
5. Encoding of YANG Data Node Instances . . . . . . . . . . 8
3.2.1. . . 6
5.1. The "leaf" Data Node . . . . . . . . . . . . . . . . 8
3.2.2. . . 6
5.2. The "container" Data Node . . . . . . . . . . . . . . 8
3.2.3. . . 7
5.3. The "leaf-list" Data Node . . . . . . . . . . . . . . 9
3.2.4. . . 7
5.4. The "list" Data Node . . . . . . . . . . . . . . . . 9
3.2.5. . . 7
5.5. The "anyxml" Data Node . . . . . . . . . . . . . . . 10
3.3. . . 8
6. The Mapping of YANG Datatypes to JSON Values . . . . . . . . . . 11
3.3.1. 8
6.1. Numeric Datatypes . . . . . . . . . . . . . . . . . . 11
3.3.2. . . 9
6.2. The "string" Type . . . . . . . . . . . . . . . . . . 11
3.3.3. . . 9
6.3. The "boolean" Type . . . . . . . . . . . . . . . . . 11
3.3.4. . . 9
6.4. The "enumeration" Type . . . . . . . . . . . . . . . 11
3.3.5. . . 9
6.5. The "bits" Type . . . . . . . . . . . . . . . . . . . 12
3.3.6. . . 9
6.6. The "binary" Type . . . . . . . . . . . . . . . . . . 12
3.3.7. . . 9
6.7. The "leafref" Type . . . . . . . . . . . . . . . . . 12
3.3.8. . . 10
6.8. The "identityref" Type . . . . . . . . . . . . . . . 12
3.3.9. . . 10
6.9. The "empty" Type . . . . . . . . . . . . . . . . . . 12
3.3.10. . . 10
6.10. The "union" Type . . . . . . . . . . . . . . . . . . 13
3.3.11. . . 11
6.11. The "instance-identifier" Type . . . . . . . . . . . 13
4. Encoding Metadata in JSON . . 11
7. I-JSON Compliance . . . . . . . . . . . . . . . . . . 14
5. IANA . . . . 12
8. Security Considerations . . . . . . . . . . . . . . . . . . . 13
9. Acknowledgments . . 16
6. Security Considerations . . . . . . . . . . . . . . . . . . . 16
7. Acknowledgments . . 13
10. References . . . . . . . . . . . . . . . . . . . . . 17
8. . . . . 13
10.1. Normative References . . . . . . . . . . . . . . . . . . 13
10.2. Informative References . . . . . . . . 17
8.1. Normative References . . . . . . . . . 14
Appendix A. A Complete Example . . . . . . . . . . 17
8.2. Informative References . . . . . . . 14
Appendix B. Change Log . . . . . . . . . . 17
Appendix A. A Complete Example . . . . . . . . . . . 16
B.1. Changes Between Revisions -00 and -01 . . . . . . . . 18 . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20 17

1. Introduction

The aim of this document is define rules NETCONF protocol [RFC6241] uses XML [W3C.REC-xml-20081126] for representing
configuration and state
encoding data defined in its Content Layer. Other management protocols might
want to use other encodings while still benefiting from using the YANG data modeling
language
[RFC6020] as JavaScript Object Notation (JSON)
text [RFC7159]. The result can be potentially applied in two
different ways:

1. JSON may be used instead of the standard XML [XML] encoding in
the context of the NETCONF protocol [RFC6241] and/or with
existing data models expressed in YANG. An example application
is modeling language.

For example, the RESTCONF Protocol [RESTCONF].

2. Other documents that choose JSON to represent structured data can
use YANG for defining the data model, i.e., both syntactic and
semantic constraints that the data have to satisfy.

JSON mapping rules could be specified in a similar way as the XML
mapping rules in [RFC6020]. This would however require solving
several problems. To begin with, YANG uses XPath [XPath] quite
extensively, but XPath is not defined for JSON and such a definition
would be far from straightforward.

In order to avoid these technical difficulties, this document employs
an alternative approach: it defines a relatively simple procedure
which allows for translating the subset of protocol [I-D.ietf-netconf-restconf]
supports two encodings: XML that can be modeled
using YANG to JSON, (media type "application/yang.data+xml")
and vice versa. Consequently, validation of a
JSON text against a data model can done by translating the JSON text
to XML, which is then validated according to the rules stated in
[RFC6020].

The translation procedure is adapted to YANG specifics and
requirements, namely:

1. (media type "application/yang.data+json).

The translation is driven by a concrete specification of the YANG data model and uses
information about modelling language [RFC6020]
defines only XML encoding for data types to achieve better results than
generic XML-JSON translation procedures.

2. Various document types are supported, namely configuration data, instances, i.e. contents of
configuration + datastores, state data, RPC RFC input and output
parameters, and event notifications.

3. XML namespaces specified in the data model are mapped to
namespaces of JSON objects. However, explicit namespace
identifiers are rarely needed in JSON text.

4. Section 4 defines JSON encoding The aim of XML attributes. Although XML
attributes cannot be modeled with YANG, they are often used for
attaching metadata this document is to elements, and a standard JSON
define rules for encoding is
therefore needed.

5. Translation of XML mixed content, comments and processing
instructions is outside the scope of this document.

Item 1 above also means that, depending on the data model, the same
XML element can be translated data as JavaScript Object Notation
(JSON) text [RFC7159].

In order to different JSON objects. For
example,

is translated achieve maximum interoperability while allowing
implementations to
"foo": 123

if the "foo" node is defined as use a leaf with the "uint8" datatype, or
to

"foo": ["123"]

if variety of available JSON parsers, the "foo" node is defined JSON
encoding rules follow, as a leaf-list with the "string"
datatype, and much as possible, the <foo> element has no siblings constraints of the same name.
I-JSON restricted profile [I-D.ietf-json-i-json]. Section Section 7
discusses I-JSON conformance in more detail.

2. Terminology and Notation

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 [RFC2119].

The following terms are defined in [RFC6020]:

o anyxml

o augment

o container

o data node

o data tree

o datatype

o feature

o identity

o instance identifier

o leaf

o leaf-list

o list

o module

o submodule

The following terms are defined in [XMLNS]:

o local name

o prefixed name

o qualified name

3. Specification of the Translation Procedure

The translation procedure defines a 1-1 correspondence between the
subset of YANG-compatible XML documents and JSON text. This means
that the translation can be applied in both directions and it is
always invertible.

The translation procedure is applicable only to data hierarchies that
are modelled by a YANG data model. An input XML document MAY contain
enclosing elements representing NETCONF "Operations" and "Messages"
layers. However, these enclosing elements do not appear in the
resulting JSON document.

Any YANG-compatible XML document can be translated, except documents
with mixed content. This is only a minor limitation since mixed
content is marginal in YANG - it is allowed only in anyxml data
nodes.

The following sections specify rules mainly for translating XML
documents to JSON text. Rules for the inverse translation are stated
only where necessary, otherwise they can in this
document are to be easily inferred.

REQUIRED parameters of the translation procedure are: interpreted as described in [RFC2119].

The following terms are defined in [RFC6020]:

o anyxml

o augment

o container

o YANG data model consisting of a set of YANG modules, node

o type of the input document, identity

o optional features (defined via the "feature" statement) that are
considered active.

The permissible types instance identifier

o leaf

o leaf-list

o list

o module

o submodule

3. Validation of input documents JSON-encoded Instance Data

Instance data validation as defined in [RFC6020] is only applicable
to XML-encoded data. For one, semantic constraints in "must"
statements are listed expressed using XPath 1.0 [W3C.REC-xpath-19991116],
which can be properly interpreted only in Table 1
together the XML context.

This document along with the corresponding part "XML Mapping Rules"
sections from [RFC6020] also define an implicit schema-driven mapping
of the data model that is used
for the translation.

Table 1: YANG Document Types

When translating XML JSON-encoded instances to JSON, the type of the input XML-encoded instances (and vice versa).
This mapping is mostly straightforward. In cases where doubts could
arise, this document can
often be determined form the encapsulating elements belonging gives explicit instructions for mapping JSON-
encoded instances to the
"Operations" or "Messages" layer as defined by the NETCONF protocol
(see Sec. 1.2 in [RFC6241]).

A particular application MAY decide XML.

In order to support only validate a subset of
document types from Table 1.

XML documents can JSON instance document, it MUST first be translated
mapped, at least conceptually, to JSON text only if they are valid
instances of the YANG data model and selected document type, also
taking into account corresponding XML instance
document. By definition, the active features, if there are any.

The resulting JSON document is always a single object ([RFC7159],
Sec. 4) whose members are translated from then valid if and only
if the original XML document
using is valid according to the rules specified stated in the following sections.

3.1.
[RFC6020].

4. Names and Namespaces

The local part

Instances of YANG data nodes (leafs, containers, leaf-lists, lists
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.

Except in the cases specified below, the member name is always identical to
the local name identifier of the corresponding XML element.

Each JSON YANG data node. Every such name lives in
belongs to a namespace which is uniquely identified by
the name of associated with the YANG module where
the corresponding data node is defined. If the data node is defined
in a submodule, then the namespace identifier is the name of determined by the main module
to which the submodule belongs. The translation procedure MUST correctly map YANG

If the namespace URIs of a member name has to YANG be explicitly specified, the
module names and vice versa.

The namespace name SHALL be expressed in JSON text by prefixing used as a prefix to the local (local) member name.
Both parts of the member name in SHALL be separated with a colon
character (":"). In other words, the namespace-qualified name will
have the following way: form:

Figure 1: Encoding a namespace identifier with a local name.

The

Names with namespace identifier identifiers in the form shown in Figure 1 MUST
be used for local names that are
ambiguous, i.e., whenever the data model permits a sibling all top-level YANG data nodes, and also for all nodes
whose parent node
with the same local name. belongs to a different namespace. Otherwise, the names
with namespace identifier is
OPTIONAL. identifiers MUST NOT be used.

For example, consider the following YANG module:

module foomod {

namespace "http://example.com/foomod";

prefix "fm"; "foo";

container foo top {
leaf bar foo {
type boolean; uint8;
}
}
}

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

{
"foo":
"foomod:top": {
"bar": true
"foo": 54
}
}

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.

Now, assume the container "foo" "top" is augmented from another module: module,
"barmod":

module barmod {

namespace "http://example.com/barmod";

prefix "bm"; "bar";

import foomod {
prefix fm; "foo";
}

augment "/fm:foo" "/foo:top" {
leaf bar {
type uint8; boolean;
}
}
}

In the data model combining "foomod" and "barmod", we have two
sibling data nodes with the same local name, namely "bar". In this
case, a

A valid JSON document has to specify an explicit namespace
identifier (module name) for JSON-encoded configuration containing both leaves: leafs may then
look like this:

{
"foo":
"foomod:top": {
"foomod:bar": true,
"foo": 54,
"barmod:bar": 123 true
}
}

3.2. Mapping XML Elements

The name of the "bar" leaf must be prefixed with the namespace
identifier because its parent is defined in a different module, hence
it belongs to JSON Objects

An XML element that another namespace.

Explicit namespace identifiers are sometimes needed when encoding
values of the "identityref" and "instances-identifier" types. The
same form as shown in Figure 1 is modelled then used as well. See Sections
6.8 and 6.11 for details.

5. Encoding of YANG Data Node Instances

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.

Character encoding MUST be UTF-8.

Any data node instance is translated to encoded as a name/value pair where the name
is formed from the name of the XML
element data node identifier using the rules in of Section 3.1. 4.
The value depends on the
type category of the data node as specified explained in
the following sections.

3.2.1. subsections.

5.1. The "leaf" Data Node

An XML element that is modeled as YANG

A leaf instance is translated to encoded as a name/
value name/value pair and the type of where the value is derived from can
be a string, number, literal 'true' or 'false' or the YANG
datatype special array
'[null]', depending on the type of the leaf (see Section 3.3 6 for the datatype mapping
type encoding rules).

Example: For the leaf node definition

leaf foo {
type uint8;
}

the XML element

corresponds to the JSON name/value pair following is a valid JSON-encoded instance:

"foo": 123

3.2.2.

5.2. The "container" Data Node

An XML element that is modeled as YANG container instance is translated to encoded as a name/object pair. The
container's child data nodes are encoded as members of the object.

Example: For the container definition

container bar {
leaf foo {
type uint8;
}
}

the XML element

corresponds to the JSON name/value pair following is a valid instance:

"bar": {
"foo": 123
}

3.2.3.

5.3. The "leaf-list" Data Node

A sequence of one or more sibling XML elements with the same
qualified name that is modeled as YANG leaf-list is translated to encoded as a name/array pair, and the array elements
are primitive values whose type depends on the datatype of the leaf-list (see
Section 3.3). 6).

Example: For the leaf-list definition

leaf-list foo {
type uint8;
}

the XML elements

<foo>123</foo>
<foo>0</foo

correspond to the JSON name/value pair following is a valid instance:

"foo": [123, 0]

3.2.4.

5.4. The "list" Data Node

A sequence of one or more sibling XML elements with the same
qualified name that is modeled as YANG list instance is translated to encoded as a name/
array name/array pair, and the array
elements are JSON objects.

Unlike the XML encoding, where the list keys are required to come
before precede any
other siblings, and to appear in the order specified by the data
model, the order of members within a JSON JSON-encoded list entry is arbitrary,
arbitrary because JSON objects are fundamentally unordered
collections of members.

Example: For the list definition
list bar {
key foo;
leaf foo {
type uint8;
}
leaf baz {
type string;
}
}

the XML elements

correspond to the JSON name/value pair following is a valid instance:

"bar": [
{
"foo": 123,
"baz": "zig"
},
{
"foo": 0,
"baz": "zag" "zag",
"foo": 0
}
]

3.2.5.

5.5. The "anyxml" Data Node

An XML element that is modeled as a YANG anyxml data node instance is translated to a name/object name/value pair. The content of such an element is
not modelled by YANG, and there may not value can
be a straightforward mapping
to of any valid JSON text (e.g., if it is a mixed XML content). Therefore,
translation type, i.e. an object, array, number, string or
any of anyxml contents is necessarily application-specific the literals 'true', 'false' and outside 'null'.

This document defines no mapping between the scope contents of this document. JSON- and
XML-encoded anyxml instances. It is not necessary because anyxml
contents are not subject to YANG-based validation (see sec. 7.10 in
[RFC6020]).

Example: For the anyxml definition

anyxml bar;

the XML element

may be translated to the following JSON name/value pair:

{
"bar": {
"p": "This is *very* cool."
}
}

3.3. a valid instance:

"bar": [true, null, true]

6. The Mapping of YANG Datatypes to JSON Values

3.3.1.

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

6.1. Numeric Datatypes

A value of one of the YANG numeric datatypes ("int8", "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint16" is
represented as a JSON number.

A value of the "int64", "uint64" and
"decimal64") or "decimal64" type is mapped to encoded as a
JSON number using string whose contents is the same lexical
representation.

3.3.2. representation of that
numeric value as specified in sections 9.2.1 and 9.3.1 of [RFC6020].

For example, if the type of the leaf "foo" in Section 5.1 was
"unit64" instead of "uint8", the instance would have to be encoded as

"foo": "123"

The special handling of 64-bit numbers follows from I-JSON
recommendation to encode numbers exceeding the IEEE 754-2000 double
precision range as strings, see sec. 2.2 in [I-D.ietf-json-i-json].

6.2. The "string" Type

A "string" value is mapped to an identical encoded as a JSON string, subject to JSON encoding
rules.

3.3.3.

6.3. The "boolean" Type

A "boolean" value is mapped to the corresponding JSON value literal name
'true' or 'false'.

3.3.4.

6.4. The "enumeration" Type

An "enumeration" value is mapped in the same way as a string except
that the permitted values are defined by "enum" statements in YANG.

3.3.5.
See sec. 9.6 in [RFC6020].

6.5. The "bits" Type

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.

3.3.6. See sec. 9.7 in
[RFC6020].

6.6. The "binary" Type

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.

3.3.7. See sec. 9.8 in [RFC6020].

6.7. The "leafref" Type

A "leafref" value is mapped according to the same rules as the type
of the leaf being referred to.

3.3.8.

6.8. The "identityref" Type

An "identityref" value is mapped to a string representing the
qualified name of the
an identity. Its namespace MAY MUST be expressed as shown in Figure 1. If the namespace part 1 if
it is not present, different from the namespace of the name leaf node containing the
identityref value, and MAY be expressed otherwise.

For example, consider the following schematic module:

module exmod {
...
import ietf-interfaces {
prefix if;
}
import iana-if-type {
prefix ianaift;
}
...
leaf type {
type identityref {
base "if:interface-type";
}
}
}

A valid instance of the JSON object containing "type" leaf is then encoded as follows:

"type": "iana-if-type:ethernetCsmacd"

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 value is
assumed.

3.3.9. "type" leaf.

6.9. The "empty" Type

An "empty" value is mapped to '[null]', i.e., an array with the
'null' value literal being its only element.

This encoding 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'.

Example: For the leaf definition

leaf foo {
type empty;
}

the XML element

<foo/>

corresponds to the JSON name/value pair

"foo": [null]

3.3.10. The "union" Type

YANG "union" type represents a choice among multiple alternative
types. The actual type of the XML value MUST be determined using the
procedure specified in Sec. 9.12 of [RFC6020] and the mapping rules
for that type are used.

For example, consider the following YANG definition:

leaf-list bar {
type union {
type uint16;
type string;
}
}

The sequence of three XML elements

<bar>6378</bar>
<bar>14.5</bar>
<bar>infinity</bar>

will then be translated to this name/array pair:

"bar": [6378, "14.5", "infinity"]

3.3.11. The "instance-identifier" Type

An "instance-identifier" value is a string representing a simplified
XPath specification. It is mapped to an analogical JSON string in
which all occurrences of XML namespace prefixes are either removed or
replaced with the corresponding module name according to the rules of
Section 3.1.

When translating such a value from JSON to XML, all components of the
instance-identifier MUST be given appropriate XML namespace prefixes.
It is RECOMMENDED that these prefixes be those defined via the
"prefix" statement in the corresponding YANG modules.

For example, assume "ex" is the prefix defined for the "example"
module. Then the XML-encoded instance identifier

/ex:system/ex:user[ex:name='fred']

corresponds to the following JSON-encoded instance identifier:

/example:system/example:user[example:name='fred']

or simply

/system/user[name='fred']

if the local names of the data nodes "system", "user" and "name" are
unambiguous.

4. Encoding Metadata in JSON

By design, YANG does not allow for modeling XML attributes. However,
attributes are often used in XML instance documents for attaching
various types of metadata information to elements. It is therefore
desirable to have a standard way for representing attributes in JSON
documents as well.

The metadata encoding defined in the rest of this section satisfies boolean context, the following two important requirements:

1. There has '[null]' value, unlike 'null',
evaluates to be true.

Example: For the leaf definition

leaf foo {
type empty;
}

a way for adding metadata to instances of all
types of YANG data nodes, i.e., leafs, containers, list and leaf-
list entries, and anyxml nodes.

2. valid instance is

"foo": [null]

6.10. The encoding "union" Type

A value of YANG data node instances as defined in the
previous sections must not change.

Existing proposals for metadata encoding in JSON, such "union" type is encoded as
[JSON-META], are oriented on rather specific uses the value of any of metadata, and
fall short with respect to the first requirement.

All attributes assigned to an XML element are mapped in
member types.

Unlike XML, JSON to
members (name/value pairs) conveys part of a single object, henceforth denoted as the metadata object. The placement type information already in the
encoding. When validating a value of the "union" type, this object depends on
information MUST also be taken into account.

For example, consider the following YANG definition:

leaf bar {
type of union {
type uint16;
type string;
}
}

In RESTCONF [I-D.ietf-netconf-restconf], it is fully acceptable to
set the element from YANG viewpoint, as specified value of "bar" in the following paragraphs.

For way when using the
"application/yang.data+xml" media type:

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 XML element that error:

"bar": 13.5

In this case, the JSON encoding indicates the value is translated supposed to be
a JSON object (i.e., a
container, anyxml node and list entry), the metadata object number rather than string.

6.11. The "instance-identifier" Type

An "instance-identifier" value is added encoded as a new member of string that object with the name "@".

Examples:

o If "cask" is a container or anyxml node,
analogical to the lexical representation in XML instance with
attributes

<cask foo="a" bar="b">
...
</cask> encoding, see
sec. 9.13.3 in [RFC6020]. The only difference is mapped that XML namespace
prefixes used for qualifying node names in the instance-identifier
value are replaced by the corresponding module names according to the following JSON object:

"cask": {
"@": {
"foo": "a",
"bar": "b"
}
...
}

o If "seq" is
rules of Section 4.

Conversely, when translating such a list, then value from JSON to XML, the pair
namespace identifier (YANG module name) in each component of XML elements

is mapped to the following JSON array:

"seq": [
{
"@": {
"foo": "a"
},
"name": "one"
},
{
"@": {
"bar": "b"
},
"name": "two"
}
]

In order to assign attributes to a leaf instance, a sibling name/
value pair is added, where
instance-identifier MUST be replaced by the name XML namespace prefix that
is the symbol "@" concatenated associated with the identifier namespace URI reference of the leaf. module.

For example, assume "ex" is the prefix associated with the element

<flag foo="a" bar="b">true</foo> namespace
URI that is mapped defined in the "example" module. Then the XML-encoded
instance-identifier

/ex:system/ex:user[ex:name='fred']

corresponds to the following two name/value pairs:

"flag": true,
"@flag": {
"foo": "a",
"bar": "b"
}

Finally, for a leaf-list instance, which JSON-encoded instance-identifier:

/example:system/example:user[example:name='fred']

7. I-JSON Compliance

I-JSON [I-D.ietf-json-i-json] is represented as a restricted profile of JSON
array with primitive values, attributes may be assigned to one or
more entries by adding a sibling name/value pair, where 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 name is I-JSON requirements and recommendations as
closely as possible.

In particular, the symbol "@" concatenated with following properties are guaranteed:

o Character encoding is UTF-8.

o Member names within the identifier same JSON object are always unique.

o The order of the leaf-list, and
the value JSON object members is never relied upon.

o Numbers of any type supported by YANG can be exchanged reliably.
See Section 6.1 for details.

The only two cases where a JSON array whose i-th element is the metadata object
with attributes assigned instance document encoded according
to this document may deviate from I-JSON were dictated by the i-th entry of the leaf-list, or nil
if need to
be able to encode the i-th entry has no attributes.

Trailing nil values same instance data in both JSON and XML. These
two exceptions are:

o Leaf values encoded as strings may contain code points identifying
Noncharacters that belong to the array, i.e., those following XML character set (see sec. 2.2
in [W3C.REC-xml-20081126]).

o Values of the last non-
nil metadata object, MAY be omitted.

For example, a leaf-list instance "binary" type are encoded with four entries

is mapped to the following two name/value pairs:

"folio": [6, 3, 7, 8],
"@folio": [nil, {"foo": "a"}, {"bar": "b"}]

The base64 encoding
scheme (see sec. 9.8.2 in [RFC6020]) whereas I-JSON recommends
base64url instead. However, the use of attributes as specified above has base64 should not cause
any interoperability problems because these values never appear in
an URL.

8. Security Considerations

This document defines an alternative encoding for data modeled in the following two
limitations:

o Mapping
YANG data modeling language. As such, it doesn't contribute any new
security issues beyond those discussed in sec. 15 of namespaces [RFC6020].

JSON is rather different from XML, and JSON parsers may thus suffer
from other types of vulnerabilities than their XML attributes counterparts. To
minimize these security risks, it is undefined.

o Attribute values can only important that client and server
software supporting JSON encoding behaves as required in sec. 3 of
[I-D.ietf-json-i-json]. That is, any received JSON data that violate
any of I-JSON strict constraints MUST NOT be strings, other trusted nor acted upon.
Violations due to the presence of Unicode Noncharacters in the data types are not
supported.

5. IANA Considerations

TBD - register application/yang.data+json media type?

6. Security Considerations

TBD.

7.
exceptions (see Section 7) SHOULD be carefully examined.

9. Acknowledgments

The author wishes to thank Andy Bierman, Martin Bjorklund Bjorklund, Juergen
Schoenwaelder and Phil Shafer for their helpful comments and
suggestions.

10. References

8.1.

10.1. Normative References

[I-D.ietf-json-i-json]
Bray, T., "The I-JSON Message Format", draft-ietf-json-
i-json-03 (work in progress), August 2014.

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020,
September
October 2010.

[RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A.
Bierman, "NETCONF "Network Configuration Protocol", Protocol (NETCONF)", RFC
6241, June 2011.

[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014.

[XMLNS] Bray, T., Hollander, D., Layman, A., Tobin, R., and H.
Thompson, "Namespaces in XML 1.0 (Third Edition)", World
Wide Web Consortium Recommendation REC-xml-names-20091208,
December 2009,
<http://www.w3.org/TR/2009/REC-xml-names-20091208>.

[XML]

[W3C.REC-xml-20081126]
Bray, T., Paoli, J., Sperberg-McQueen, C., M., Maler, E., and
F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008,
<http://www.w3.org/TR/2006/REC-xml-20060816>.

8.2.
<http://www.w3.org/TR/2008/REC-xml-20081126>.

10.2. Informative References

[IF-CFG] Bjorklund, M., "A YANG Data Model for Interface
Management", draft-ietf-netmod-interfaces-cfg-16 (work in
progress), January 2014.

[JSON-META]
Sakimura, N., "JSON Metadata", draft-sakimura-json-
metadata-01 (work in progress), November 2013.

[RESTCONF]

[I-D.ietf-netconf-restconf]
Bierman, A., Bjorklund, M., Watsen, K., and R. Fernando, K. Watsen, "RESTCONF
Protocol", draft-ietf-netconf-restconf-00 draft-ietf-netconf-restconf-02 (work in
progress), March October 2014.

[RFC7223] Bjorklund, M., "A YANG Data Model for Interface
Management", RFC 7223, May 2014.

[XPath]

[W3C.REC-xpath-19991116]
Clark, J., J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium Recommendation
REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>.

Appendix A. A Complete Example

The JSON document shown below was translated from a represents the same data as the reply
to the NETCONF <get> request that can be found appearing in Appendix D of [IF-CFG]. [RFC7223].
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 [IF-CFG]). [RFC7223]). The "if-mib" feature defined in the "ietf-
interfaces" module is considered to be active.

{
"interfaces":
"ietf-interfaces:interfaces": {
"interface": [
{
"name": "eth0",
"type": "iana-if-type:ethernetCsmacd",
"enabled": false
},
{
"name": "eth1",
"type": "iana-if-type:ethernetCsmacd",
"enabled": true,
"vlan-tagging":
"ex-vlan:vlan-tagging": true
},
{
"name": "eth1.10",
"type": "iana-if-type:l2vlan",
"enabled": true,
"base-interface":
"ex-vlan:base-interface": "eth1",
"vlan-id":
"ex-vlan:vlan-id": 10
},
{
"name": "lo1",
"type": "iana-if-type:softwareLoopback",
"enabled": true
}
]
},
"interfaces-state":
"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"
}
}
]
}
}

Appendix B. Change Log

RFC Editor: Remove this section upon publication as an RFC.

B.1. Changes Between Revisions -00 and -01

o Metadata encoding was moved to a separate I-D, draft-lhotka-
netmod-yang-metadata.

o JSON encoding is now defined directly rather than via XML-JSON
mapping.

o The rules for namespace encoding has changed. This affect both
node instance names and instance-identifiers.

o I-JSON-related changes. The most significant is the string
encoding of 64-bit numbers.

o When validating union type, the partial type info present in JSON
encoding is taken into account.

o Added section about I-JSON compliance.

o Updated the example in appendix.

o Wrote Security Considerations.

o Removed IANA Considerations as there are none.

Author's Address

Ladislav Lhotka
CZ.NIC

Email: lhotka@nic.cz