draft-ietf-netmod-yang-metadata-00.txt		draft-ietf-netmod-yang-metadata-01.txt
	NETMOD Working Group L. Lhotka		NETMOD Working Group L. Lhotka
	Internet-Draft CZ.NIC		Internet-Draft CZ.NIC
	Intended status: Standards Track April 16, 2015		Intended status: Standards Track June 10, 2015
	Expires: October 18, 2015		Expires: December 12, 2015
	Defining and Using Metadata with YANG		Defining and Using Metadata with YANG
	draft-ietf-netmod-yang-metadata-00		draft-ietf-netmod-yang-metadata-01
	Abstract		Abstract
	This document defines a YANG extension statement that allows for		This document defines a YANG extension statement that allows for
	defining syntax of metadata annotions in YANG modules. The document		defining syntax of metadata annotions in YANG modules. The document
	also specifies XML and JSON encoding of annotations and other rules		also specifies XML and JSON encoding of annotations and other rules
	for annotating instances of YANG data nodes.		for annotating instances of YANG data nodes.
	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 October 18, 2015.		This Internet-Draft will expire on December 12, 2015.
	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 14		skipping to change at page 2, line 14
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4		2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
	3. Defining Annotations in YANG . . . . . . . . . . . . . . . . 5		3. Defining Annotations in YANG . . . . . . . . . . . . . . . . 5
	4. The Encoding of Annotations . . . . . . . . . . . . . . . . . 7		4. The Encoding of Annotations . . . . . . . . . . . . . . . . . 7
	4.1. XML Encoding . . . . . . . . . . . . . . . . . . . . . . 7		4.1. XML Encoding . . . . . . . . . . . . . . . . . . . . . . 7
	4.2. JSON Encoding . . . . . . . . . . . . . . . . . . . . . . 7		4.2. JSON Encoding . . . . . . . . . . . . . . . . . . . . . . 7
	4.2.1. Metadata Object and Annotations . . . . . . . . . . . 8		4.2.1. Metadata Object and Annotations . . . . . . . . . . . 8
	4.2.2. Adding Annotations to Container and List Instances . 8		4.2.2. Adding Annotations to Anydata, Container and List
			Instances . . . . . . . . . . . . . . . . . . . . . . 8
	4.2.3. Adding Annotations to Anyxml and Leaf Instances . . . 9		4.2.3. Adding Annotations to Anyxml and Leaf Instances . . . 9
	4.2.4. Adding Annotations to Leaf-list Instances . . . . . . 9		4.2.4. Adding Annotations to Leaf-list Instances . . . . . . 9
	5. Representing Annotations in DSDL Schemas . . . . . . . . . . 10		5. Representing Annotations in DSDL Schemas . . . . . . . . . . 10
	6. Metadata YANG Module . . . . . . . . . . . . . . . . . . . . 11		6. Metadata YANG Module . . . . . . . . . . . . . . . . . . . . 11
	7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13		7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
	8. Security Considerations . . . . . . . . . . . . . . . . . . . 14		8. Security Considerations . . . . . . . . . . . . . . . . . . . 14
	9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14		9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14
	10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14		10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
	10.1. Normative References . . . . . . . . . . . . . . . . . . 14		10.1. Normative References . . . . . . . . . . . . . . . . . . 14
	10.2. Informative References . . . . . . . . . . . . . . . . . 15		10.2. Informative References . . . . . . . . . . . . . . . . . 15
	Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 15		Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 15
	A.1. Changes Between draft-lhotka-netmod-yang-metadata-01 and		A.1. Changes Between Revisions -00 and -01 . . . . . . . . . . 15
			A.2. Changes Between draft-lhotka-netmod-yang-metadata-01 and
	draft-ietf-netmod-yang-metadata-00 . . . . . . . . . . . 15		draft-ietf-netmod-yang-metadata-00 . . . . . . . . . . . 15
	A.2. Changes Between draft-lhotka-netmod-yang-metadata-00 and		A.3. Changes Between draft-lhotka-netmod-yang-metadata-00 and
	-01 . . . . . . . . . . . . . . . . . . . . . . . . . . . 16		-01 . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
	1. Introduction		1. Introduction
	There is a need to be able to annotate instances of		There is a need to be able to annotate instances of
	YANG [I-D.ietf-netmod-rfc6020bis] data nodes with metadata. Typical		YANG [I-D.ietf-netmod-rfc6020bis] data nodes with metadata. Typical
	use cases are:		use cases are:
	o Deactivating a subtree in a configuration datastore while keeping		o Deactivating a subtree in a configuration datastore while keeping
	skipping to change at page 4, line 25		skipping to change at page 4, line 25
	o datastore,		o datastore,
	o message,		o message,
	o operation,		o operation,
	o server.		o server.
	The following terms are defined in [I-D.ietf-netmod-rfc6020bis]:		The following terms are defined in [I-D.ietf-netmod-rfc6020bis]:
			o anydata,
	o anyxml,		o anyxml,
	o built-in type,		o built-in type,
	o derived type,		o derived type,
	o container,		o container,
	o data model,		o data model,
	skipping to change at page 8, line 34		skipping to change at page 8, line 34
	specified in the argument of the corresponding "md:annotation"		specified in the argument of the corresponding "md:annotation"
	statement.		statement.
	Note that unlike YANG data node instances, for annotations the		Note that unlike YANG data node instances, for annotations the
	explicit namespace identifier (MODULE_NAME) must always be used.		explicit namespace identifier (MODULE_NAME) must always be used.
	The value of a metadata annotation SHALL be encoded in exactly the		The value of a metadata annotation SHALL be encoded in exactly the
	same way as the value of a YANG leaf node having the same type as the		same way as the value of a YANG leaf node having the same type as the
	annotation, see [I-D.ietf-netmod-yang-json], sec. 6.		annotation, see [I-D.ietf-netmod-yang-json], sec. 6.
	4.2.2. Adding Annotations to Container and List Instances		4.2.2. Adding Annotations to Anydata, Container and List Instances
	For an instance that is encoded as a JSON object (i.e., a container		For an instance that is encoded as a JSON object (i.e., a container,
	or list entry), the metadata object is added as a new member of that		a list entry, or anydata node), the metadata object is added as a new
	object with the name "@".		member of that object with the name "@".
	Examples:		Examples:
	o "cask" is a container node:		o "cask" is a container node:
	"cask": {		"cask": {
	"@": {		"@": {
	"example-inactive:inactive": true		"example-inactive:inactive": true
	},		},
	...		...
	skipping to change at page 11, line 49		skipping to change at page 11, line 49
	The second step of the DSDL mapping procedure, i.e., the		The second step of the DSDL mapping procedure, i.e., the
	transformation of the hybrid schema to RELAX NG, Schematron and DSRL		transformation of the hybrid schema to RELAX NG, Schematron and DSRL
	schemas, is unaffected by the inclusion of "md:annotation".		schemas, is unaffected by the inclusion of "md:annotation".
	6. Metadata YANG Module		6. Metadata YANG Module
	RFC Editor: In this section, replace all occurrences of 'XXXX' with		RFC Editor: In this section, replace all occurrences of 'XXXX' with
	the actual RFC number and all occurrences of the revision date below		the actual RFC number and all occurrences of the revision date below
	with the date of RFC publication (and remove this note).		with the date of RFC publication (and remove this note).
	<CODE BEGINS> file "ietf-yang-metadata@2015-04-16.yang"		<CODE BEGINS> file "ietf-yang-metadata@2015-06-09.yang"
	module ietf-yang-metadata {		module ietf-yang-metadata {
	namespace "urn:ietf:params:xml:ns:yang:ietf-yang-metadata";		namespace "urn:ietf:params:xml:ns:yang:ietf-yang-metadata";
	prefix "md";		prefix "md";
	organization		organization
	"IETF NETMOD (NETCONF Data Modeling Language) Working Group";		"IETF NETMOD (NETCONF Data Modeling Language) Working Group";
	contact		contact
	skipping to change at page 12, line 47		skipping to change at page 12, line 47
	The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL		The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
	NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and		NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and
	'OPTIONAL' in the module text are to be interpreted as described		'OPTIONAL' in the module text are to be interpreted as described
	in RFC 2119 (http://tools.ietf.org/html/rfc2119).		in RFC 2119 (http://tools.ietf.org/html/rfc2119).
	This version of this YANG module is part of RFC XXXX		This version of this YANG module is part of RFC XXXX
	(http://tools.ietf.org/html/rfcXXXX); see the RFC itself for		(http://tools.ietf.org/html/rfcXXXX); see the RFC itself for
	full legal notices.";		full legal notices.";
	revision 2015-04-16 {		revision 2015-06-09 {
	description		description
	"Initial revision.";		"Initial revision.";
	reference		reference
	"RFC XXXX: Defining and Using Metadata with YANG";		"RFC XXXX: Defining and Using Metadata with YANG";
	}		}
	extension annotation {		extension annotation {
	argument name;		argument name;
	description		description
	skipping to change at page 14, line 44		skipping to change at page 14, line 44
	The author wishes to thank Andy Bierman, Martin Bjorklund and Kent		The author wishes to thank Andy Bierman, Martin Bjorklund and Kent
	Watsen for their helpful comments and suggestions.		Watsen for 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., "YANG - A Data Modeling Language for the
	Network Configuration Protocol (NETCONF)", draft-ietf-		Network Configuration Protocol (NETCONF)", draft-ietf-
	netmod-rfc6020bis-04 (work in progress), March 2015.		netmod-rfc6020bis-05 (work in progress), May 2015.
	[I-D.ietf-netmod-yang-json]		[I-D.ietf-netmod-yang-json]
	Lhotka, L., "JSON Encoding of Data Modeled with YANG",		Lhotka, L., "JSON Encoding of Data Modeled with YANG",
	draft-ietf-netmod-yang-json-03 (work in progress),		draft-ietf-netmod-yang-json-03 (work in progress),
	February 2015.		February 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, March 1997.		Requirement Levels", BCP 14, RFC 2119, March 1997.
	[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,		[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
	skipping to change at page 15, line 29		skipping to change at page 15, line 29
	[W3C.REC-xml-infoset-20040204]		[W3C.REC-xml-infoset-20040204]
	Cowan, J. and R. Tobin, "XML Information Set (Second		Cowan, J. and R. Tobin, "XML Information Set (Second
	Edition)", World Wide Web Consortium Recommendation REC-		Edition)", World Wide Web Consortium Recommendation REC-
	xml-infoset-20040204, February 2004,		xml-infoset-20040204, February 2004,
	<http://www.w3.org/TR/2004/REC-xml-infoset-20040204>.		<http://www.w3.org/TR/2004/REC-xml-infoset-20040204>.
	10.2. Informative References		10.2. Informative References
	[I-D.ietf-netconf-restconf]		[I-D.ietf-netconf-restconf]
	Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF		Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
	Protocol", draft-ietf-netconf-restconf-04 (work in		Protocol", draft-ietf-netconf-restconf-05 (work in
	progress), January 2015.		progress), June 2015.
	[ISO.19757-1]		[ISO.19757-1]
	International Organization for Standardization, "Document		International Organization for Standardization, "Document
	Schema Definition Languages (DSDL) - Part 1: Overview",		Schema Definition Languages (DSDL) - Part 1: Overview",
	ISO/IEC 19757-1, November 2004.		ISO/IEC 19757-1, November 2004.
	Appendix A. Change Log		Appendix A. Change Log
	RFC Editor: Remove this section upon publication as an RFC.		RFC Editor: Remove this section upon publication as an RFC.
	A.1. Changes Between draft-lhotka-netmod-yang-metadata-01 and draft-		A.1. Changes Between Revisions -00 and -01
			o Define JSON encoding for annotations attached to 'anydata' nodes.
			A.2. Changes Between draft-lhotka-netmod-yang-metadata-01 and draft-
	ietf-netmod-yang-metadata-00		ietf-netmod-yang-metadata-00
	o References to RFC 6020 were changed to the 6021bis I-D.		o References to RFC 6020 were changed to the 6021bis I-D.
	o Text about RFC 2119 key words was added to "ietf-yang-metadata"		o Text about RFC 2119 key words was added to "ietf-yang-metadata"
	module description.		module description.
	A.2. Changes Between draft-lhotka-netmod-yang-metadata-00 and -01		A.3. Changes Between draft-lhotka-netmod-yang-metadata-00 and -01
	o Encoding of annotations for anyxml nodes was changed to be the		o Encoding of annotations for anyxml nodes was changed to be the
	same as for leafs. This was necessary because anyxml value now		same as for leafs. This was necessary because anyxml value now
	needn't be an object.		needn't be an object.
	o It is stated that "md:annotation" statement defines only the		o It is stated that "md:annotation" statement defines only the
	syntax of an annotation.		syntax of an annotation.
	o Allowed "if-feature" as a substatement of "md:annotation".		o Allowed "if-feature" as a substatement of "md:annotation".
End of changes. 15 change blocks.
	18 lines changed or deleted		26 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/