--- 1/draft-ietf-netmod-yang-json-05.txt 2015-10-07 07:15:06.674240357 -0700
+++ 2/draft-ietf-netmod-yang-json-06.txt 2015-10-07 07:15:06.710241230 -0700
@@ -1,18 +1,18 @@
NETMOD Working Group L. Lhotka
Internet-Draft CZ.NIC
-Intended status: Standards Track September 10, 2015
-Expires: March 13, 2016
+Intended status: Standards Track October 07, 2015
+Expires: April 9, 2016
JSON Encoding of Data Modeled with YANG
- draft-ietf-netmod-yang-json-05
+ draft-ietf-netmod-yang-json-06
Abstract
This document defines encoding rules for representing configuration,
state data, RPC operation or action input and output parameters, and
notifications defined using YANG as JavaScript Object Notation (JSON)
text.
Status of This Memo
@@ -22,21 +22,21 @@
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 March 13, 2016.
+ This Internet-Draft will expire on April 9, 2016.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
@@ -72,37 +72,38 @@
6.10. The "union" Type . . . . . . . . . . . . . . . . . . . . 13
6.11. The "instance-identifier" Type . . . . . . . . . . . . . 14
7. I-JSON Compliance . . . . . . . . . . . . . . . . . . . . . . 14
8. Security Considerations . . . . . . . . . . . . . . . . . . . 15
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
10.1. Normative References . . . . . . . . . . . . . . . . . . 15
10.2. Informative References . . . . . . . . . . . . . . . . . 16
Appendix A. A Complete Example . . . . . . . . . . . . . . . . . 16
Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 18
- B.1. Changes Between Revisions -04 and -05 . . . . . . . . . . 18
- B.2. Changes Between Revisions -03 and -04 . . . . . . . . . . 18
- B.3. Changes Between Revisions -02 and -03 . . . . . . . . . . 19
- B.4. Changes Between Revisions -01 and -02 . . . . . . . . . . 19
- B.5. Changes Between Revisions -00 and -01 . . . . . . . . . . 19
+ B.1. Changes Between Revisions -05 and -06 . . . . . . . . . . 18
+ B.2. Changes Between Revisions -04 and -05 . . . . . . . . . . 18
+ B.3. Changes Between Revisions -03 and -04 . . . . . . . . . . 19
+ B.4. Changes Between Revisions -02 and -03 . . . . . . . . . . 19
+ B.5. Changes Between Revisions -01 and -02 . . . . . . . . . . 19
+ B.6. Changes Between Revisions -00 and -01 . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20
1. Introduction
The NETCONF protocol [RFC6241] uses XML [W3C.REC-xml-20081126] for
encoding data in its Content Layer. Other management protocols might
want to use other encodings while still benefiting from using YANG
[I-D.ietf-netmod-rfc6020bis] as the data modeling language.
For example, the RESTCONF protocol [I-D.ietf-netconf-restconf]
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 YANG 1.1 data modelling language
[I-D.ietf-netmod-rfc6020bis] defines only XML encoding for data
instances, i.e., contents of configuration datastores, state data,
RPC operation or action 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 [RFC7159].
2. Terminology and Notation
@@ -170,22 +171,23 @@
conformance in more detail.
4. Names and Namespaces
An object member name MUST be in one of the following forms:
o simple - identical to the identifier of the corresponding YANG
data node;
o namespace-qualified - the data node identifier is prefixed with
- the name of the module in which the data node is defined, and
- separated by the colon character (":").
+ the name of the module in which the data node is defined,
+ separated from the data node identifier by the colon character
+ (":").
The name of a module determines the namespace of all data node names
defined in that module. If a data node is defined in a submodule,
then the namespace-qualified member name uses the name of the main
module to which the submodule belongs.
ABNF syntax [RFC5234] of a member name is shown in Figure 1, where
the production for "identifier" is defined in sec. 13 of
[I-D.ietf-netmod-rfc6020bis].
@@ -368,30 +370,30 @@
"baz": "zig"
},
{
"baz": "zag",
"foo": 0
}
]
5.5. The "anydata" Data Node
- Anydata data node is a new feature in YANG 1.1. It serves as a
- container for an unknown set of nodes that however appear as normal
- YANG-modeled data. A data model for anydata content may or may not
- exist at run time. In the latter case, no universal mapping between
- JSON- and XML-encoded instances is available.
+ Anydata data node serves as a container for an arbitrary set of nodes
+ that otherwise appear as normal YANG-modeled data. A data model for
+ anydata content may or may not be known at run time. In the latter
+ case, converting JSON-encoded instances to the XML encoding defined
+ in [I-D.ietf-netmod-rfc6020bis] may be impossible.
An anydata instance is encoded in the same way as a container, i.e.,
as a value/object pair. The requirement that anydata content can be
- modeled by YANG implies the following rules for JSON text inside the
- object:
+ modeled by YANG implies the following rules for the JSON text inside
+ the object:
o It is valid I-JSON [RFC7493].
o All object member names satisfy the ABNF production in Figure 1.
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
@@ -401,21 +403,21 @@
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",
+ "event-class": "fault",
"reporting-entity": {
"card": "Ethernet0"
},
"severity": "major"
}
}
}
5.6. The "anyxml" Data Node
@@ -455,22 +457,22 @@
"uint64" instead of "uint8", the instance would have to be encoded as
"foo": "123"
The special handling of 64-bit numbers follows from the I-JSON
recommendation to encode numbers exceeding the IEEE 754-2008 double
precision range as strings, see sec. 2.2 in [RFC7493].
6.2. The "string" Type
- A "string" value represented as a JSON string, subject to JSON string
- encoding rules.
+ A "string" value is represented as a JSON string, subject to JSON
+ string encoding rules.
6.3. The "boolean" Type
A "boolean" value is represented as the corresponding JSON literal
name "true" or "false".
6.4. The "enumeration" Type
An "enumeration" value is represented as a JSON string - one of the
names assigned by "enum" statements in YANG.
@@ -555,21 +557,23 @@
a valid instance is
"foo": [null]
6.10. The "union" Type
A value of the "union" type is encoded as the value of any of the
member types.
When validating a value of the "union" type, the type information
- conveyed by the JSON encoding MUST also be taken into account.
+ conveyed by the JSON encoding MUST also be taken into account. JSON
+ syntax thus provides additional means for resolving union member type
+ that are not available in XML encoding.
For example, consider the following YANG definition:
leaf bar {
type union {
type uint16;
type string;
}
}
@@ -579,21 +583,26 @@
13.5
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:
"bar": 13.5
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, and it is not a valid "uint16" value.
+
+ Conversely, the value of
+ "bar": "1"
+
+ is to be interpreted as a string.
6.11. The "instance-identifier" Type
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 [I-D.ietf-netmod-rfc6020bis]. However, the encoding
of namespaces in instance-identifier values follows the rules stated
in Section 4, namely:
o The leftmost (top-level) data node name is always in the
@@ -628,21 +637,21 @@
o Member names within the same JSON object are always unique.
o The order of 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 JSON encoding defined in this document deviates from I-JSON only
in the representation of the "binary" type. In order to remain
compatible with XML encoding, the base64 encoding scheme is used
- (Section 6.6), whereas I-JSON recommends base64url instead.
+ (Section 6.6), whilst I-JSON recommends base64url instead.
8. Security Considerations
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
[I-D.ietf-netmod-rfc6020bis].
JSON processing is rather different from XML, and JSON parsers may
thus suffer from other types of vulnerabilities than their XML
@@ -655,23 +664,23 @@
The author wishes to thank Andy Bierman, Martin Bjorklund, Dean
Bogdanovic, Balazs Lengyel, Juergen Schoenwaelder and Phil Shafer for
their helpful comments and suggestions.
10. References
10.1. Normative References
[I-D.ietf-netmod-rfc6020bis]
- Bjorklund, M., "YANG - A Data Modeling Language for the
- Network Configuration Protocol (NETCONF)", draft-ietf-
- netmod-rfc6020bis-06 (work in progress), July 2015.
+ Bjorklund, M., "The YANG 1.1 Data Modeling Language",
+ draft-ietf-netmod-rfc6020bis-07 (work in progress),
+ September 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
RFC2119, March 1997,
.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/
RFC5234, January 2008,
.
@@ -806,57 +816,61 @@
}
}
]
}
}
Appendix B. Change Log
RFC Editor: Remove this section upon publication as an RFC.
-B.1. Changes Between Revisions -04 and -05
+B.1. Changes Between Revisions -05 and -06
+
+ o More text and a new example about resolving union-type values.
+
+B.2. Changes Between Revisions -04 and -05
o Removed section "Validation of JSON-encoded Instance Data" and
other text about XML-JSON mapping.
o Added section "Properties of the JSON Encoding".
-B.2. Changes Between Revisions -03 and -04
+B.3. 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.3. Changes Between Revisions -02 and -03
+B.4. Changes Between Revisions -02 and -03
o Namespace encoding is defined without using RFC 2119 keywords.
o Specification for anyxml nodes was extended and clarified.
o Text about ordering of list entries was corrected.
-B.4. Changes Between Revisions -01 and -02
+B.5. Changes Between Revisions -01 and -02
o Encoding of namespaces in instance-identifiers was changed.
o Text specifying the order of array elements in leaf-list and list
instances was added.
-B.5. Changes Between Revisions -00 and -01
+B.6. 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.