draft-ietf-netmod-yang-json-05.txt   draft-ietf-netmod-yang-json-06.txt 
NETMOD Working Group L. Lhotka NETMOD Working Group L. Lhotka
Internet-Draft CZ.NIC Internet-Draft CZ.NIC
Intended status: Standards Track September 10, 2015 Intended status: Standards Track October 07, 2015
Expires: March 13, 2016 Expires: April 9, 2016
JSON Encoding of Data Modeled with YANG JSON Encoding of Data Modeled with YANG
draft-ietf-netmod-yang-json-05 draft-ietf-netmod-yang-json-06
Abstract Abstract
This document defines encoding rules for representing configuration, This document defines encoding rules for representing configuration,
state data, RPC operation or action input and output parameters, and state data, RPC operation or action input and output parameters, and
notifications defined using YANG as JavaScript Object Notation (JSON) notifications defined using YANG as JavaScript Object Notation (JSON)
text. text.
Status of This Memo Status of This Memo
skipping to change at page 1, line 33 skipping to change at page 1, line 33
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 March 13, 2016. This Internet-Draft will expire on April 9, 2016.
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 38 skipping to change at page 2, line 38
6.10. The "union" Type . . . . . . . . . . . . . . . . . . . . 13 6.10. The "union" Type . . . . . . . . . . . . . . . . . . . . 13
6.11. The "instance-identifier" Type . . . . . . . . . . . . . 14 6.11. The "instance-identifier" Type . . . . . . . . . . . . . 14
7. I-JSON Compliance . . . . . . . . . . . . . . . . . . . . . . 14 7. I-JSON Compliance . . . . . . . . . . . . . . . . . . . . . . 14
8. Security Considerations . . . . . . . . . . . . . . . . . . . 15 8. Security Considerations . . . . . . . . . . . . . . . . . . . 15
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
10.1. Normative References . . . . . . . . . . . . . . . . . . 15 10.1. Normative References . . . . . . . . . . . . . . . . . . 15
10.2. Informative References . . . . . . . . . . . . . . . . . 16 10.2. Informative References . . . . . . . . . . . . . . . . . 16
Appendix A. A Complete Example . . . . . . . . . . . . . . . . . 16 Appendix A. A Complete Example . . . . . . . . . . . . . . . . . 16
Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 18 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 18
B.1. Changes Between Revisions -04 and -05 . . . . . . . . . . 18 B.1. Changes Between Revisions -05 and -06 . . . . . . . . . . 18
B.2. Changes Between Revisions -03 and -04 . . . . . . . . . . 18 B.2. Changes Between Revisions -04 and -05 . . . . . . . . . . 18
B.3. Changes Between Revisions -02 and -03 . . . . . . . . . . 19 B.3. Changes Between Revisions -03 and -04 . . . . . . . . . . 19
B.4. Changes Between Revisions -01 and -02 . . . . . . . . . . 19 B.4. Changes Between Revisions -02 and -03 . . . . . . . . . . 19
B.5. Changes Between Revisions -00 and -01 . . . . . . . . . . 19 B.5. Changes Between Revisions -01 and -02 . . . . . . . . . . 19
B.6. Changes Between Revisions -00 and -01 . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20
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
[I-D.ietf-netmod-rfc6020bis] 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 YANG 1.1 data modelling language The specification of YANG 1.1 data modelling language
[I-D.ietf-netmod-rfc6020bis] defines only XML encoding for data [I-D.ietf-netmod-rfc6020bis] defines only XML encoding for data
instances, i.e., contents of configuration datastores, state data, instances, i.e., contents of configuration datastores, state data,
RPC operation or action input and output parameters, and event RPC operation or action input and output parameters, and event
notifications. The aim of this document is to define rules for notifications. The aim of this document is to define rules for
encoding the same data as JavaScript Object Notation (JSON) encoding the same data as JavaScript Object Notation (JSON)
text [RFC7159]. text [RFC7159].
2. Terminology and Notation 2. Terminology and Notation
skipping to change at page 4, line 41 skipping to change at page 4, line 41
conformance in more detail. conformance in more detail.
4. Names and Namespaces 4. Names and Namespaces
An object member name MUST be in one of the following forms: An object member name MUST be in one of the following forms:
o simple - identical to the identifier of the corresponding YANG o simple - identical to the identifier of the corresponding YANG
data node; data node;
o namespace-qualified - the data node identifier is prefixed with o namespace-qualified - the data node identifier is prefixed with
the name of the module in which the data node is defined, and the name of the module in which the data node is defined,
separated by the colon character (":"). separated from the data node identifier by the colon character
(":").
The name of a module determines the namespace of all data node names 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, 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 then the namespace-qualified member name uses the name of the main
module to which the submodule belongs. module to which the submodule belongs.
ABNF syntax [RFC5234] of a member name is shown in Figure 1, where ABNF syntax [RFC5234] of a member name is shown in Figure 1, where
the production for "identifier" is defined in sec. 13 of the production for "identifier" is defined in sec. 13 of
[I-D.ietf-netmod-rfc6020bis]. [I-D.ietf-netmod-rfc6020bis].
skipping to change at page 9, line 18 skipping to change at page 9, line 18
"baz": "zig" "baz": "zig"
}, },
{ {
"baz": "zag", "baz": "zag",
"foo": 0 "foo": 0
} }
] ]
5.5. The "anydata" Data Node 5.5. The "anydata" Data Node
Anydata data node is a new feature in YANG 1.1. It serves as a Anydata data node serves as a container for an arbitrary set of nodes
container for an unknown set of nodes that however appear as normal that otherwise appear as normal YANG-modeled data. A data model for
YANG-modeled data. A data model for anydata content may or may not anydata content may or may not be known at run time. In the latter
exist at run time. In the latter case, no universal mapping between case, converting JSON-encoded instances to the XML encoding defined
JSON- and XML-encoded instances is available. in [I-D.ietf-netmod-rfc6020bis] may be impossible.
An anydata instance is encoded in the same way as a container, i.e., 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 as a value/object pair. The requirement that anydata content can be
modeled by YANG implies the following rules for JSON text inside the modeled by YANG implies the following rules for the JSON text inside
object: the object:
o It is valid I-JSON [RFC7493]. o It is valid I-JSON [RFC7493].
o All object member names satisfy the ABNF production in Figure 1. o All object member names satisfy the ABNF production in Figure 1.
o Any JSON array contains either only unique scalar values (as a 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 leaf-list, see Section 5.3), or only objects (as a list, see
Section 5.4). Section 5.4).
o The "null" value is only allowed in the single-element array o The "null" value is only allowed in the single-element array
skipping to change at page 10, line 9 skipping to change at page 10, line 9
Example: for the anydata definition Example: for the anydata definition
anydata data; anydata data;
the following is a valid JSON-encoded instance: the following is a valid JSON-encoded instance:
"data": { "data": {
"ietf-notification:notification": { "ietf-notification:notification": {
"eventTime": "2014-07-29T13:43:01Z", "eventTime": "2014-07-29T13:43:01Z",
"example-event:event": { "example-event:event": {
"event-class: "fault", "event-class": "fault",
"reporting-entity": { "reporting-entity": {
"card": "Ethernet0" "card": "Ethernet0"
}, },
"severity": "major" "severity": "major"
} }
} }
} }
5.6. The "anyxml" Data Node 5.6. The "anyxml" Data Node
skipping to change at page 11, line 16 skipping to change at page 11, line 16
"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 the I-JSON The special handling of 64-bit numbers follows from the 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 [RFC7493]. precision range as strings, see sec. 2.2 in [RFC7493].
6.2. The "string" Type 6.2. The "string" Type
A "string" value represented as a JSON string, subject to JSON string A "string" value is represented as a JSON string, subject to JSON
encoding rules. string encoding rules.
6.3. The "boolean" Type 6.3. The "boolean" Type
A "boolean" value is represented as the corresponding JSON literal A "boolean" value is represented as the corresponding JSON literal
name "true" or "false". name "true" or "false".
6.4. The "enumeration" Type 6.4. The "enumeration" Type
An "enumeration" value is represented as a JSON string - one of the An "enumeration" value is represented as a JSON string - one of the
names assigned by "enum" statements in YANG. names assigned by "enum" statements in YANG.
skipping to change at page 13, line 23 skipping to change at page 13, line 23
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.
When validating a value of the "union" type, the type information 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: For example, consider the following YANG definition:
leaf bar { leaf bar {
type union { type union {
type uint16; type uint16;
type string; type string;
} }
} }
skipping to change at page 13, line 47 skipping to change at page 13, line 49
<bar>13.5</bar> <bar>13.5</bar>
because the value may be interpreted as a string, i.e., the second because the value may be interpreted as a string, i.e., the second
member type of the union. When using the "application/ member type of the union. When using the "application/
yang.data+json" media type, however, this is an error: yang.data+json" media type, however, this is an error:
"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, 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 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 [I-D.ietf-netmod-rfc6020bis]. However, the encoding sec. 9.13.3 in [I-D.ietf-netmod-rfc6020bis]. However, the encoding
of namespaces in instance-identifier values follows the rules stated of namespaces in instance-identifier values follows the rules stated
in Section 4, namely: in Section 4, namely:
o The leftmost (top-level) data node name is always in the o The leftmost (top-level) data node name is always in the
skipping to change at page 14, line 52 skipping to change at page 15, line 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 JSON encoding defined in this document deviates from I-JSON only The JSON encoding defined in this document deviates from I-JSON only
in the representation of the "binary" type. In order to remain in the representation of the "binary" type. In order to remain
compatible with XML encoding, the base64 encoding scheme is used 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 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. 16 of security issues beyond those discussed in sec. 16 of
[I-D.ietf-netmod-rfc6020bis]. [I-D.ietf-netmod-rfc6020bis].
JSON processing is rather different from XML, and JSON parsers may JSON processing is rather different from XML, and JSON parsers may
thus suffer from other types of vulnerabilities than their XML thus suffer from other types of vulnerabilities than their XML
skipping to change at page 15, line 30 skipping to change at page 15, line 35
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-netmod-rfc6020bis] [I-D.ietf-netmod-rfc6020bis]
Bjorklund, M., "YANG - A Data Modeling Language for the Bjorklund, M., "The YANG 1.1 Data Modeling Language",
Network Configuration Protocol (NETCONF)", draft-ietf- draft-ietf-netmod-rfc6020bis-07 (work in progress),
netmod-rfc6020bis-06 (work in progress), July 2015. September 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, DOI 10.17487/ Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
RFC2119, March 1997, RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/
RFC5234, January 2008, RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>. <http://www.rfc-editor.org/info/rfc5234>.
skipping to change at page 18, line 36 skipping to change at page 18, line 40
} }
} }
] ]
} }
} }
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 -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 o Removed section "Validation of JSON-encoded Instance Data" and
other text about XML-JSON mapping. other text about XML-JSON mapping.
o Added section "Properties of the JSON Encoding". 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 o I-D.ietf-netmod-rfc6020bis is used as a normative reference
instead of RFC 6020. instead of RFC 6020.
o Removed noncharacters as an I-JSON issue because it doesn't exist o Removed noncharacters as an I-JSON issue because it doesn't exist
in YANG 1.1. in YANG 1.1.
o Section about anydata encoding was added. o Section about anydata encoding was added.
o Require I-JSON for anyxml encoding. o Require I-JSON for anyxml encoding.
o Use ABNF for defining qualified name. 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 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.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 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.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- 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. 19 change blocks. 
33 lines changed or deleted 46 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/