draft-ietf-netmod-yang-data-ext-04.txt		draft-ietf-netmod-yang-data-ext-05.txt
	Network Working Group A. Bierman		Network Working Group A. Bierman
	Internet-Draft YumaWorks		Internet-Draft YumaWorks
	Updates: 8340 (if approved) M. Bjorklund		Updates: 8340 (if approved) M. Bjorklund
	Intended status: Standards Track Cisco		Intended status: Standards Track Cisco
	Expires: January 16, 2020 K. Watsen		Expires: June 12, 2020 K. Watsen
	Watsen Networks		Watsen Networks
	July 15, 2019		December 10, 2019
	YANG Data Structure Extensions		YANG Data Structure Extensions
	draft-ietf-netmod-yang-data-ext-04		draft-ietf-netmod-yang-data-ext-05
	Abstract		Abstract
	This document describes YANG mechanisms for defining abstract data		This document describes YANG mechanisms for defining abstract data
	structures with YANG.		structures with YANG.
	Status of This Memo		Status of This Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted in full conformance with the
	provisions of BCP 78 and BCP 79.		provisions of BCP 78 and BCP 79.
	skipping to change at page 1, line 34 ¶		skipping to change at page 1, line 34 ¶
	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 https://datatracker.ietf.org/drafts/current/.		Drafts is at https://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 January 16, 2020.		This Internet-Draft will expire on June 12, 2020.
	Copyright Notice		Copyright Notice
	Copyright (c) 2019 IETF Trust and the persons identified as the		Copyright (c) 2019 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
	(https://trustee.ietf.org/license-info) in effect on the date of		(https://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 12 ¶		skipping to change at page 2, line 12 ¶
	the Trust Legal Provisions and are provided without warranty as		the Trust Legal Provisions and are provided without warranty as
	described in the Simplified BSD License.		described in the Simplified BSD License.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3		1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
	1.1.1. NMDA . . . . . . . . . . . . . . . . . . . . . . . . 3		1.1.1. NMDA . . . . . . . . . . . . . . . . . . . . . . . . 3
	1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . 3		1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . 3
	2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4		2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4
	3. YANG Data Structures in YANG Tree Diagrams . . . . . . . . . 4		3. YANG Data Structures in YANG Tree Diagrams . . . . . . . . . 5
	4. YANG Data Structure Extensions Module . . . . . . . . . . . . 5		4. YANG Data Structure Extensions Module . . . . . . . . . . . . 5
	5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9		5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
	5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 9		5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 10
	6. Security Considerations . . . . . . . . . . . . . . . . . . . 10		6. Security Considerations . . . . . . . . . . . . . . . . . . . 10
	7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10		7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
	7.1. Normative References . . . . . . . . . . . . . . . . . . 10		7.1. Normative References . . . . . . . . . . . . . . . . . . 10
	7.2. Informative References . . . . . . . . . . . . . . . . . 11		7.2. Informative References . . . . . . . . . . . . . . . . . 11
	Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 11		Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 11
	A.1. "structure" Example . . . . . . . . . . . . . . . . . . . 11		A.1. "structure" Example . . . . . . . . . . . . . . . . . . . 11
	A.2. "augment-structure" Example . . . . . . . . . . . . . . . 13		A.2. "augment-structure" Example . . . . . . . . . . . . . . . 13
	A.3. XML Encoding Example . . . . . . . . . . . . . . . . . . 13		A.3. XML Encoding Example . . . . . . . . . . . . . . . . . . 13
	A.4. JSON Encoding Example . . . . . . . . . . . . . . . . . . 14		A.4. JSON Encoding Example . . . . . . . . . . . . . . . . . . 14
	A.5. "structure" example that defines a non-top-level		A.5. "structure" example that defines a non-top-level
	structure . . . . . . . . . . . . . . . . . . . . . . . . 14		structure . . . . . . . . . . . . . . . . . . . . . . . . 14
	Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 15		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15
	B.1. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 15
	B.2. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 15
	B.3. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 15
	Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 16
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
	1. Introduction		1. Introduction
	There is a need for standard mechanisms to allow the definition of		There is a need for standard mechanisms to allow the definition of
	abstract data that is not intended to be implemented as configuration		abstract data that is not intended to be implemented as configuration
	or operational state. The "yang-data" extension statement from RFC		or operational state. The "yang-data" extension statement from RFC
	8040 [RFC8040] was defined for this purpose but it is limited in its		8040 [RFC8040] was defined for this purpose but it is limited in its
	functionality.		functionality.
	The intended use of the "yang-data" extension was to model all or		The intended use of the "yang-data" extension was to model all or
	part of a protocol message, such as the "errors" definition in the		part of a protocol message, such as the "errors" definition in the
	YANG module "ietf-restconf" [RFC8040], or the contents of a file.		YANG module "ietf-restconf" [RFC8040], or the contents of a file.
	However, protocols are often layered such that the header or payload		However, protocols are often layered such that the header or payload
	portions of the message can be extended by external documents. The		portions of the message can be extended by external documents. The
	YANG statements that model a protocol need to support this		YANG statements that model a protocol need to support this
	extensibility that is already found in that protocol.		extensibility that is already found in that protocol.
	The "yang-data" extension from [RFC8040] has been copied here,		This document defines a new YANG extension statement called
	renamed to "structure", and updated to be more flexible. There is no		"structure", which is similar to but more flexible than the
	assumption that a YANG data structure can only be used as a top-level		"yang-data" extension from [RFC8040]. There is no assumption that a
	abstraction, instead of nested within some other data structure.		YANG data structure can only be used as a top-level abstraction, and
			it may also be nested within some other data structure.
	This document also defines a new YANG extension statement called		This document also defines a new YANG extension statement called
	"augment-structure", which allows abstract data structures to be		"augment-structure", which allows abstract data structures to be
	augmented from external modules, similar to the existing YANG		augmented from external modules, similarly to the existing YANG
	"augment" statement. Note that "augment" cannot be used to augment a		"augment" statement. Note that "augment" cannot be used to augment a
	YANG data structure since a YANG compiler or other tool is not		YANG data structure since a YANG compiler or other tool is not
	required to understand the "structure" extension.		required to understand the "structure" extension.
	1.1. Terminology		1.1. Terminology
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and		"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in BCP		"OPTIONAL" in this document are to be interpreted as described in BCP
	14 [RFC2119] [RFC8174] when, and only when, they appear in all		14 [RFC2119] [RFC8174] when, and only when, they appear in all
	capitals, as shown here.		capitals, as shown here.
	The following terms are used within this document:		The following terms are used within this document:
	o YANG data structure: A data structure defined with the "structure"		o YANG data structure: A data structure defined with the "structure"
	statement.		statement.
	1.1.1. NMDA		1.1.1. NMDA
	The following terms are defined in the Network Management Datastore		The following terms are defined in the Network Management Datastore
	Architecture (NMDA) [RFC8342]. and are not redefined here:		Architecture (NMDA) [RFC8342], and are not redefined here:
	o configuration		o configuration
	o operational state		o operational state
	1.1.2. YANG		1.1.2. YANG
	The following terms are defined in [RFC7950]:		The following terms are defined in [RFC7950]:
	o absolute-schema-nodeid		o absolute-schema-nodeid
	skipping to change at page 4, line 4 ¶		skipping to change at page 3, line 46 ¶
	o container		o container
	o data definition statement		o data definition statement
	o data node		o data node
	o leaf		o leaf
	o leaf-list		o leaf-list
	o list		o list
	2. Definitions		2. Definitions
	A YANG Data Structure is defined with the "structure" extension		A YANG data structure is defined with the "structure" extension
	statement, defined in the YANG module "ietf-yang-structure-ext". The		statement, defined in the YANG module "ietf-yang-structure-ext". The
	argument to the "structure" extension statement is the name of the		argument to the "structure" extension statement is the name of the
	data structure. The data structures are considered to be in the same		data structure. The data structures are considered to be in the same
	identifier namespace as defined in section 6.2.1 of [RFC7950]. In		identifier namespace as defined in section 6.2.1 of [RFC7950]. In
	particular, bullet 7:		particular, bullet 7:
	All leafs, leaf-lists, lists, containers, choices, rpcs, actions,		All leafs, leaf-lists, lists, containers, choices, rpcs, actions,
	notifications, anydatas, and anyxmls defined (directly or through		notifications, anydatas, and anyxmls defined (directly or through
	a "uses" statement) within a parent node or at the top level of		a "uses" statement) within a parent node or at the top level of
	the module or its submodules share the same identifier namespace.		the module or its submodules share the same identifier namespace.
	This means that data structures defined with the "structure"		This means that data structures defined with the "structure"
	statement cannot have the same name as sibling nodes from regular		statement cannot have the same name as sibling nodes from regular
	YANG data definition statements or other "structure" statements in		YANG data definition statements or other "structure" statements in
	the same YANG module.		the same YANG module.
	This does not mean a YANG data structure has to be used as a top-		This does not mean a YANG data structure, once defined, has to be
	level protocol message or other top-level data structure.		used as a top-level protocol message or other top-level data
			structure.
			A YANG data structure is encoded in the same way as an "anydata"
			node. This means that the name of the structure is encoded as a
			"container", with the instantiated children encoded as child nodes to
			this node. For example, this structure:
			module example-errors {
			...
			sx:structure my-error {
			leaf error-number {
			type int;
			}
			}
			}
			can be encoded in JSON as:
			"example-errors:my-error": {
			"error-number": 131
			}
	3. YANG Data Structures in YANG Tree Diagrams		3. YANG Data Structures in YANG Tree Diagrams
	A YANG Data Structure can be printed in a YANG Tree Diagram		A YANG data structure can be printed in a YANG Tree Diagram
	[RFC8340]. This document updates RFC 8340 by defining two new		[RFC8340]. This document updates RFC 8340 by defining two new
	sections in the tree diagram for a module:		sections in the tree diagram for a module:
	1. YANG data structures, offset by two spaces and identified by the		1. YANG data structures, offset by two spaces and identified by the
	keyword "structure" followed by the name of the YANG data		keyword "structure" followed by the name of the YANG data
	structure and a colon (":") character.		structure and a colon (":") character.
	2. YANG data structure augmentations, offset by 2 spaces and		2. YANG data structure augmentations, offset by 2 spaces and
	identified by the keyword "augment-structure" followed by the		identified by the keyword "augment-structure" followed by the
	augment target structure name and a colon (":") character.		augment target structure name and a colon (":") character.
	The new sections, including spaces conventions is:		The new sections, including spaces conventions is:
	structure <structure-name>:		structure <structure-name>:
	+--<node>		+--<node>
	+--<node>		+--<node>
	| +--<node>		| +--<node>
	+--<node>		+--<node>
	structure <structure-name>:		structure <structure-name>:
	+--<node>		+--<node>
	augment-structure <structure-name>:		augment-structure <structure-name>:
	+--<node>		+--<node>
	+--<node>		+--<node>
	| +--<node>		| +--<node>
	+--<node>		+--<node>
	augment-structure <structure-name>:		augment-structure <structure-name>:
	+--<node>		+--<node>
			Nodes in YANG data structures are printed according to the rules
			defined in section 2.6 in [RFC8340].
	4. YANG Data Structure Extensions Module		4. YANG Data Structure Extensions Module
	RFC Ed.: update the date below with the date of RFC publication and		RFC Ed.: update the date below with the date of RFC publication and
	remove this note.		remove this note.
	<CODE BEGINS> file "ietf-yang-structure-ext@2019-03-07.yang"		<CODE BEGINS> file "ietf-yang-structure-ext@2019-03-07.yang"
	module ietf-yang-structure-ext {		module ietf-yang-structure-ext {
	yang-version 1.1;		yang-version 1.1;
	skipping to change at page 6, line 8 ¶		skipping to change at page 6, line 27 ¶
	description		description
	"This module contains conceptual YANG specifications for defining		"This module contains conceptual YANG specifications for defining
	abstract data structures.		abstract data structures.
	The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL		The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
	NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',		NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
	'MAY', and 'OPTIONAL' in this document are to be interpreted as		'MAY', and 'OPTIONAL' in this document are to be interpreted as
	described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,		described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
	they appear in all capitals, as shown here.		they appear in all capitals, as shown here.
	Copyright (c) 2019 IETF Trust and the persons identified		Copyright (c) 2019 IETF Trust and the persons identified as
	as authors of the code. All rights reserved.		authors of the code. All rights reserved.
	Redistribution and use in source and binary forms, with or		Redistribution and use in source and binary forms, with or
	without modification, is permitted pursuant to, and subject		without modification, is permitted pursuant to, and subject to
	to the license terms contained in, the Simplified BSD License		the license terms contained in, the Simplified BSD License set
	set forth in Section 4.c of the IETF Trust's Legal Provisions		forth in Section 4.c of the IETF Trust's Legal Provisions
	Relating to IETF Documents		Relating to IETF Documents
	(http://trustee.ietf.org/license-info).";		(http://trustee.ietf.org/license-info).
			This version of this YANG module is part of RFC XXXX
			(https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
			for full legal notices.";
	// RFC Ed.: update the date below with the date of RFC publication		// RFC Ed.: update the date below with the date of RFC publication
	// and remove this note.		// and remove this note.
	revision 2019-03-07 {		revision 2019-03-07 {
	description		description
	"Initial revision.";		"Initial revision.";
	// RFC Ed.: replace XXXX with RFC number and remove this note		// RFC Ed.: replace XXXX with RFC number and remove this note
	reference		reference
	"RFC XXXX: YANG Structure Extensions.";		"RFC XXXX: YANG Structure Extensions.";
	skipping to change at page 7, line 16 ¶		skipping to change at page 7, line 39 ¶
	rules below, where the rules are defined in RFC 7950:		rules below, where the rules are defined in RFC 7950:
	*must-stmt		*must-stmt
	[status-stmt]		[status-stmt]
	[description-stmt]		[description-stmt]
	[reference-stmt]		[reference-stmt]
	*(typedef-stmt / grouping-stmt)		*(typedef-stmt / grouping-stmt)
	*data-def-stmt		*data-def-stmt
	A YANG data structure defined with this extension statement is		A YANG data structure defined with this extension statement is
	encoded in the same way as an 'anydata' statement. This means		encoded in the same way as an 'anydata' node. This means
	that the name of the structure is encoded as a 'container',		that the name of the structure is encoded as a 'container',
	with the instantiated child statements encoded as child nodes		with the instantiated child statements encoded as child nodes
	to this node.		to this node.
	The module name and namespace value for the YANG module using		The module name and namespace value for the YANG module using
	the extension statement is assigned to each of the data		the extension statement is assigned to each of the data
	definition statements resulting from the YANG data structure.		definition statements resulting from the YANG data structure.
	The XPath document element is the extension statement itself,		The XPath document element is the extension statement itself,
	such that the child nodes of the document element are		such that the child nodes of the document element are
	skipping to change at page 11, line 16 ¶		skipping to change at page 11, line 37 ¶
	[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,		[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
	DOI 10.17487/RFC3688, January 2004,		DOI 10.17487/RFC3688, January 2004,
	<https://www.rfc-editor.org/info/rfc3688>.		<https://www.rfc-editor.org/info/rfc3688>.
	[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for		[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
	the Network Configuration Protocol (NETCONF)", RFC 6020,		the Network Configuration Protocol (NETCONF)", RFC 6020,
	DOI 10.17487/RFC6020, October 2010,		DOI 10.17487/RFC6020, October 2010,
	<https://www.rfc-editor.org/info/rfc6020>.		<https://www.rfc-editor.org/info/rfc6020>.
	7.3. URIs
	[1] https://github.com/netmod-wg/yang-data-ext/issues
	Appendix A. Examples		Appendix A. Examples
	A.1. "structure" Example		A.1. "structure" Example
	This example shows a simple address book that could be stored as an		This example shows a simple address book that could be stored as an
	artifact.		artifact.
	module example-module {		module example-module {
	yang-version 1.1;		yang-version 1.1;
	namespace "urn:example:example-module";		namespace "urn:example:example-module";
	skipping to change at page 14, line 13 ¶		skipping to change at page 14, line 13 ¶
	This example shows how an address book can be encoded in XML:		This example shows how an address book can be encoded in XML:
	<address-book xmlns="urn:example:example-module">		<address-book xmlns="urn:example:example-module">
	<address>		<address>
	<last>Flintstone</last>		<last>Flintstone</last>
	<first>Fred</first>		<first>Fred</first>
	<street>301 Cobblestone Way</street>		<street>301 Cobblestone Way</street>
	<city>Bedrock</city>		<city>Bedrock</city>
	<zipcode xmlns="urn:example:example-module-aug">70777</zipcode>		<zipcode xmlns="urn:example:example-module-aug">70777</zipcode>
	</address>		</address>
			<address>
			<last>Root</last>
			<first>Charlie</first>
			<street>4711 Cobblestone Way</street>
			<city>Bedrock</city>
			<zipcode xmlns="urn:example:example-module-aug">70777</zipcode>
			</address>
	</address-book>		</address-book>
	A.4. JSON Encoding Example		A.4. JSON Encoding Example
	This example shows how an address book can be encoded in JSON:		This example shows how an address book can be encoded in JSON:
	"example-module:address-book": {		"example-module:address-book": {
	"address": [		"address": [
	{		{
	"city": "Bedrock",		"city": "Bedrock",
	"example-module-aug:zipcode": "70777",		"example-module-aug:zipcode": "70777",
	"first": "Fred",		"first": "Fred",
	"last": "Flintstone",		"last": "Flintstone",
	"street": "301 Cobblestone Way"		"street": "301 Cobblestone Way"
			},
			{
			"city": "Bedrock",
			"example-module-aug:zipcode": "70777",
			"first": "Charlie",
			"last": "Root",
			"street": "4711 Cobblestone Way"
	}		}
	]		]
	}		}
	A.5. "structure" example that defines a non-top-level structure		A.5. "structure" example that defines a non-top-level structure
	The following example defines a data structure with error		The following example defines a data structure with error
	information, that can be included in an <error-info> element in an		information, that can be included in an <error-info> element in an
	<rpc-error>.		<rpc-error>.
	skipping to change at page 15, line 22 ¶		skipping to change at page 15, line 40 ¶
	<error-severity>error</error-severity>		<error-severity>error</error-severity>
	<error-info>		<error-info>
	<my-example-error-info		<my-example-error-info
	xmlns="urn:example:example-error-info">		xmlns="urn:example:example-error-info">
	<error-code>42</error-code>		<error-code>42</error-code>
	</my-example-error-info>		</my-example-error-info>
	</error-info>		</error-info>
	</rpc-error>		</rpc-error>
	</rpc-reply>		</rpc-reply>
	Appendix B. Change Log
	RFC Ed.: remove this section before publication.
	B.1. v02 to v03
	o added YANG tree diagram syntax
	o added more examples
	B.2. v01 to v02
	o terminology fixes (use the term "structure" instead of "template")
	o renamed the statement to "structure" from "yang-data"
	o removed limitations on if-feature and identities in YANG
	structures
	B.3. v00 to v01
	o moved open issues to github
	o added examples section
	o filled in IANA considerations
	Appendix C. Open Issues
	RFC Ed.: remove this section before publication.
	The YANG Data Structure Extensions issues are tracked on github.com:
	https://github.com/netmod-wg/yang-data-ext/issues [1]
	Authors' Addresses		Authors' Addresses
	Andy Bierman		Andy Bierman
	YumaWorks		YumaWorks
	Email: andy@yumaworks.com		Email: andy@yumaworks.com
	Martin Bjorklund		Martin Bjorklund
	Cisco		Cisco
End of changes. 24 change blocks.
	83 lines changed or deleted		84 lines changed or added
This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/