draft-ietf-netmod-yang-data-ext-02.txt		draft-ietf-netmod-yang-data-ext-03.txt
	Network Working Group A. Bierman		Network Working Group A. Bierman
	Internet-Draft YumaWorks		Internet-Draft YumaWorks
	Intended status: Standards Track M. Bjorklund		Intended status: Standards Track M. Bjorklund
	Expires: September 9, 2019 Cisco		Expires: October 17, 2019 Cisco
	K. Watsen		K. Watsen
	Watsen Networks		Watsen Networks
	March 8, 2019		April 15, 2019
	YANG Data Structure Extensions		YANG Data Structure Extensions
	draft-ietf-netmod-yang-data-ext-02		draft-ietf-netmod-yang-data-ext-03
	Abstract		Abstract
	This document describes YANG mechanisms for defining abstract data		This document describes YANG mechanisms for defining abstract data
	structures with YANG. It is intended to replace and extend the		structures with YANG.
	"yang-data" extension statement defined in RFC 8040.
	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.
	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 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 September 9, 2019.		This Internet-Draft will expire on October 17, 2019.
	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
	(http://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
	carefully, as they describe your rights and restrictions with respect		carefully, as they describe your rights and restrictions with respect
	to this document. Code Components extracted from this document must		to this document. Code Components extracted from this document must
	include Simplified BSD License text as described in Section 4.e of		include Simplified BSD License text as described in Section 4.e of
	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 Structure Extensions Module . . . . . . . . . . . . 4		3. YANG Data Structures in YANG Tree Diagrams . . . . . . . . . 4
	4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9		4. YANG Data Structure Extensions Module . . . . . . . . . . . . 5
	4.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 9		5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
	5. Security Considerations . . . . . . . . . . . . . . . . . . . 9		5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 9
	6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9		6. Security Considerations . . . . . . . . . . . . . . . . . . . 10
	6.1. Normative References . . . . . . . . . . . . . . . . . . 9		7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
	6.2. Informative References . . . . . . . . . . . . . . . . . 10		7.1. Normative References . . . . . . . . . . . . . . . . . . 10
	Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 10		7.2. Informative References . . . . . . . . . . . . . . . . . 11
	A.1. "structure" Example . . . . . . . . . . . . . . . . . . . 10		Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 11
	A.2. "augment-structure" Example . . . . . . . . . . . . . . . 11		A.1. "structure" Example . . . . . . . . . . . . . . . . . . . 11
	A.3. XML Encoding Example . . . . . . . . . . . . . . . . . . 12		A.2. "augment-structure" Example . . . . . . . . . . . . . . . 13
	A.4. JSON Encoding Example . . . . . . . . . . . . . . . . . . 12		A.3. XML Encoding Example . . . . . . . . . . . . . . . . . . 13
	Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 13		A.4. JSON Encoding Example . . . . . . . . . . . . . . . . . . 14
	B.1. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 13		A.5. "structure" example that defines a non-top-level
	B.2. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 13		structure . . . . . . . . . . . . . . . . . . . . . . . . 14
	Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 13		Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 15
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13		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
	skipping to change at page 4, line 27 ¶		skipping to change at page 4, line 28 ¶
	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 has to be used as a top-
	level protocol message or other top-level data structure.		level protocol message or other top-level data structure.
	3. YANG Data Structure Extensions Module		3. YANG Data Structures in YANG Tree Diagrams
			A YANG Data Structure can be printed in a YANG Tree Diagram
			[RFC8340]. This document defines two new sections in the tree
			diagram for a module:
			1. YANG data structures, offset by two spaces and identified by the
			keyword "structure" followed by the name of the YANG data
			structure and a colon (":") character.
			2. YANG data structure augmentations, offset by 2 spaces and
			identified by the keyword "augment-structure" followed by the
			augment target structure name and a colon (":") character.
			The new sections, including spaces conventions is:
			structure <structure-name>:
			+--<node>
			+--<node>
			| +--<node>
			+--<node>
			structure <structure-name>:
			+--<node>
			augment-structure <structure-name>:
			+--<node>
			+--<node>
			| +--<node>
			+--<node>
			augment-structure <structure-name>:
			+--<node>
			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;
	namespace "urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext";		namespace "urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext";
	prefix sx;		prefix sx;
	skipping to change at page 9, line 5 ¶		skipping to change at page 9, line 42 ¶
	leaf add-leaf1 { type int32; }		leaf add-leaf1 { type int32; }
	leaf add-leaf2 { type string; }		leaf add-leaf2 { type string; }
	}		}
	}		}
	";		";
	}		}
	}		}
	<CODE ENDS>		<CODE ENDS>
	4. IANA Considerations		5. IANA Considerations
	4.1. YANG Module Registry		5.1. YANG Module Registry
	This document registers one URI as a namespace in the "IETF XML		This document registers one URI as a namespace in the "IETF XML
	Registry" [RFC3688]:		Registry" [RFC3688]:
	URI: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext		URI: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext
	Registrant Contact: The IESG.		Registrant Contact: The IESG.
	XML: N/A; the requested URI is an XML namespace.		XML: N/A; the requested URI is an XML namespace.
	This document registers one YANG module in the "YANG Module Names"		This document registers one YANG module in the "YANG Module Names"
	registry [RFC6020]:		registry [RFC6020]:
	name: ietf-yang-structure-ext		name: ietf-yang-structure-ext
	namespace: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext		namespace: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext
	prefix: sx		prefix: sx
	// RFC Ed.: replace XXXX with RFC number and remove this note		// RFC Ed.: replace XXXX with RFC number and remove this note
	reference: RFC XXXX		reference: RFC XXXX
	5. Security Considerations		6. Security Considerations
	This document defines YANG extensions that are used to define		This document defines YANG extensions that are used to define
	conceptual YANG data structures. It does not introduce any new		conceptual YANG data structures. It does not introduce any new
	vulnerabilities beyond those specified in YANG 1.1 [RFC7950].		vulnerabilities beyond those specified in YANG 1.1 [RFC7950].
	6. References		7. References
	6.1. Normative References		7.1. Normative References
	[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,
	RFC2119, March 1997, <https://www.rfc-editor.org/info/		DOI 10.17487/RFC2119, March 1997,
	rfc2119>.		<https://www.rfc-editor.org/info/rfc2119>.
	[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",		[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
	RFC 7950, DOI 10.17487/RFC7950, August 2016,		RFC 7950, DOI 10.17487/RFC7950, August 2016,
	<https://www.rfc-editor.org/info/rfc7950>.		<https://www.rfc-editor.org/info/rfc7950>.
	[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF		[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
	Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,		Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
	<https://www.rfc-editor.org/info/rfc8040>.		<https://www.rfc-editor.org/info/rfc8040>.
	[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC		[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
	2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,		2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
	May 2017, <https://www.rfc-editor.org/info/rfc8174>.		May 2017, <https://www.rfc-editor.org/info/rfc8174>.
			[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
			BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
			<https://www.rfc-editor.org/info/rfc8340>.
	[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,		[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
	and R. Wilton, "Network Management Datastore Architecture		and R. Wilton, "Network Management Datastore Architecture
	(NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,		(NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
	<https://www.rfc-editor.org/info/rfc8342>.		<https://www.rfc-editor.org/info/rfc8342>.
	6.2. Informative References		7.2. Informative References
	[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, <https://www.rfc-		DOI 10.17487/RFC3688, January 2004,
	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, <https://www.rfc-		DOI 10.17487/RFC6020, October 2010,
	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;
	skipping to change at page 11, line 41 ¶		skipping to change at page 12, line 41 ¶
	description "City name";		description "City name";
	}		}
	leaf state {		leaf state {
	type string;		type string;
	description "State name";		description "State name";
	}		}
	}		}
	}		}
	}		}
			Below is the tree diagram of this module.
			module: example-module
			structure address-book:
			+-- address* [last first]
			+-- last string
			+-- first string
			+-- street? string
			+-- city? string
			+-- state? string
	A.2. "augment-structure" Example		A.2. "augment-structure" Example
	This example adds "county" and "zipcode" leafs to the address book:		This example adds "county" and "zipcode" leafs to the address book:
	module example-module-aug {		module example-module-aug {
	yang-version 1.1;		yang-version 1.1;
	namespace "urn:example:example-module-aug";		namespace "urn:example:example-module-aug";
	prefix exma;		prefix exma;
	import ietf-yang-structure-ext {		import ietf-yang-structure-ext {
	skipping to change at page 12, line 29 ¶		skipping to change at page 13, line 33 ¶
	type string;		type string;
	description "County name";		description "County name";
	}		}
	leaf zipcode {		leaf zipcode {
	type string;		type string;
	description "Postal zipcode";		description "Postal zipcode";
	}		}
	}		}
	}		}
			Below is the tree diagram of this module.
			module: example-module-aug
			augment-structure /exm:address-book/exm:address:
			+-- county? string
			+-- zipcode? string
	A.3. XML Encoding Example		A.3. XML Encoding Example
	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>
	skipping to change at page 13, line 17 ¶		skipping to change at page 14, line 31 ¶
	{		{
	"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"
	}		}
	]		]
	}		}
			A.5. "structure" example that defines a non-top-level structure
			The following example defines a data structure with error
			information, that can be included in an <error-info> element in an
			<rpc-error>.
			module example-error-info {
			yang-version 1.1;
			namespace "urn:example:example-error-info";
			prefix exei;
			import ietf-yang-structure-ext {
			prefix sx;
			}
			sx:structure my-example-error-info {
			leaf error-code {
			type uint32;
			}
			}
			}
			The example below shows how this structure can be used in an
			<rpc-error>.
			<rpc-reply message-id="101"
			xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
			<rpc-error>
			<error-type>protocol</error-type>
			<error-tag>operation-failed</error-tag>
			<error-severity>error</error-severity>
			<error-info>
			<my-example-error-info
			xmlns="urn:example:example-error-info">
			<error-code>42</error-code>
			</my-example-error-info>
			</error-info>
			</rpc-error>
			</rpc-reply>
	Appendix B. Change Log		Appendix B. Change Log
	RFC Ed.: remove this section before publication.		RFC Ed.: remove this section before publication.
	B.1. v01 to v02		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 terminology fixes (use the term "structure" instead of "template")
	o renamed the statement to "structure" from "yang-data"		o renamed the statement to "structure" from "yang-data"
	o removed limitations on if-feature and identities in YANG		o removed limitations on if-feature and identities in YANG
	structures		structures
	B.2. v00 to v01		B.3. v00 to v01
	o moved open issues to github		o moved open issues to github
	o added examples section		o added examples section
	o filled in IANA considerations		o filled in IANA considerations
	Appendix C. Open Issues		Appendix C. Open Issues
	RFC Ed.: remove this section before publication.		RFC Ed.: remove this section before publication.
	The YANG Data Structure Extensions issues are tracked on github.com:		The YANG Data Structure Extensions issues are tracked on github.com:
	https://github.com/netmod-wg/yang-data-ext/issues		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
	Email: mbj@tail-f.com		Email: mbj@tail-f.com
	Kent Watsen		Kent Watsen
	Watsen Networks		Watsen Networks
	Email: kent+ietf@watsen.net		Email: kent+ietf@watsen.net
End of changes. 26 change blocks.
	42 lines changed or deleted		152 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/