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/