rfc9195.original		rfc9195.txt
	Netmod B. Lengyel		Internet Engineering Task Force (IETF) B. Lengyel
	Internet-Draft Ericsson		Request for Comments: 9195 Ericsson
	Intended status: Standards Track B. Claise		Category: Standards Track B. Claise
	Expires: 11 April 2022 Huawei		ISSN: 2070-1721 Huawei
	8 October 2021		February 2022
	YANG Instance Data File Format		A File Format for YANG Instance Data
	draft-ietf-netmod-yang-instance-file-format-21
	Abstract		Abstract
	There is a need to document data defined in YANG models at design		There is a need to document data defined in YANG models at design
	time, implementation time or when a live server is unavailable. This		time, implementation time, or when a live server is unavailable.
	document specifies a standard file format for YANG instance data,		This document specifies a standard file format for YANG instance
	which follows the syntax and semantics of existing YANG models, and		data, which follows the syntax and semantics of existing YANG models
	annotates it with metadata.		and annotates it with metadata.
	Status of This Memo		Status of This Memo
	This Internet-Draft is submitted in full conformance with the		This is an Internet Standards Track document.
	provisions of BCP 78 and BCP 79.
	Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-
	Drafts is at https://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		This document is a product of the Internet Engineering Task Force
	and may be updated, replaced, or obsoleted by other documents at any		(IETF). It represents the consensus of the IETF community. It has
	time. It is inappropriate to use Internet-Drafts as reference		received public review and has been approved for publication by the
	material or to cite them other than as "work in progress."		Internet Engineering Steering Group (IESG). Further information on
			Internet Standards is available in Section 2 of RFC 7841.
	This Internet-Draft will expire on 11 April 2022.		Information about the current status of this document, any errata,
			and how to provide feedback on it may be obtained at
			https://www.rfc-editor.org/info/rfc9195.
	Copyright Notice		Copyright Notice
	Copyright (c) 2021 IETF Trust and the persons identified as the		Copyright (c) 2022 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 (https://trustee.ietf.org/		Provisions Relating to IETF Documents
	license-info) in effect on the date of publication of this document.		(https://trustee.ietf.org/license-info) in effect on the date of
	Please review these documents carefully, as they describe your rights		publication of this document. Please review these documents
	and restrictions with respect to this document. Code Components		carefully, as they describe your rights and restrictions with respect
	extracted from this document must include Simplified BSD License text		to this document. Code Components extracted from this document must
	as described in Section 4.e of the Trust Legal Provisions and are		include Revised BSD License text as described in Section 4.e of the
	provided without warranty as described in the Simplified BSD License.		Trust Legal Provisions and are provided without warranty as described
			in the Revised BSD License.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2		1. Introduction
	1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3		1.1. Terminology
	1.2. Principles . . . . . . . . . . . . . . . . . . . . . . . 4		1.2. Principles
	1.3. Delivery of Instance Data . . . . . . . . . . . . . . . . 4		1.3. Delivery of Instance Data
	1.4. Data Life cycle . . . . . . . . . . . . . . . . . . . . . 5		1.4. Data Life Cycle
	2. Instance Data File Format . . . . . . . . . . . . . . . . . . 5		2. Instance Data File Format
	2.1. Specifying the Content Schema . . . . . . . . . . . . . . 7		2.1. Specifying the Content Schema
	2.1.1. Inline Method . . . . . . . . . . . . . . . . . . . . 8		2.1.1. Inline Method
	2.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 8		2.1.2. Simplified-Inline Method
	2.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 8		2.1.3. URI Method
	2.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8		2.2. Examples
	2.2.1. Documentation of server capabilities . . . . . . . . 8		2.2.1. Documentation of Server Capabilities
	2.2.2. Preloading default configuration data . . . . . . . . 10		2.2.2. Preloading Default Configuration Data
	2.2.3. Storing diagnostics data . . . . . . . . . . . . . . 11		2.2.3. Storing Diagnostics Data
	3. YANG Instance Data Model . . . . . . . . . . . . . . . . . . 12		3. YANG Instance Data Model
	3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 12		3.1. Tree Diagram
	3.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 13		3.2. YANG Model
	4. Security Considerations . . . . . . . . . . . . . . . . . . . 19		4. Security Considerations
	5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20		5. IANA Considerations
	5.1. URI Registration . . . . . . . . . . . . . . . . . . . . 20		5.1. URI Registration
	5.2. YANG Module Name Registration . . . . . . . . . . . . . . 20		5.2. YANG Module Name Registration
	6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21		6. References
	7. References . . . . . . . . . . . . . . . . . . . . . . . . . 21		6.1. Normative References
	7.1. Normative References . . . . . . . . . . . . . . . . . . 21		6.2. Informative References
	7.2. Informative References . . . . . . . . . . . . . . . . . 22		Appendix A. Backwards Compatibility
	Appendix A. Changes between revisions . . . . . . . . . . . . . 23		Appendix B. Detailed Use Cases
	Appendix B. Backwards Compatibility . . . . . . . . . . . . . . 26		B.1. Use Case 1: Early Documentation of Server Capabilities
	Appendix C. Detailed Use Cases . . . . . . . . . . . . . . . . . 27		B.2. Use Case 2: Preloading Data
	C.1. Use Case 1: Early Documentation of Server Capabilities . 27		B.3. Use Case 3: Documenting Factory Default Settings
	C.2. Use Case 2: Preloading Data . . . . . . . . . . . . . . . 28		Acknowledgments
	C.3. Use Case 3: Documenting Factory Default Settings . . . . 28		Authors' Addresses
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28
	1. Introduction		1. Introduction
	There is a need to document data defined in YANG models when a live		There is a need to document data defined in YANG models when a live
	server is unavailable. Data is often needed at design,		server is unavailable. Data is often needed at design time,
	implementation time or even later when a live running server is		implementation time, or even later when a live running server is
	unavailable. To facilitate this offline delivery of data, this		unavailable. To facilitate this offline delivery of data, this
	document specifies a standard format for YANG instance data sets and		document specifies a standard format for YANG instance data sets and
	YANG instance data files. The format of the instance data set is		YANG instance data files. The format of the instance data set is
	defined by the "ietf-yang-instance-data" YANG module, see Section 3.		defined by the "ietf-yang-instance-data" YANG module; see Section 3.
	The YANG data model in this document conforms to the Network		The YANG data model in this document conforms to the Network
	Management Datastore Architecture (NMDA) defined in [RFC8342]		Management Datastore Architecture (NMDA) defined in [RFC8342].
	The following is a list of already implemented and potential use
			The following is a list of already-implemented and potential use
	cases.		cases.
	UC1 Documentation of server capabilities		UC1 Documentation of server capabilities
	UC2 Preloading default configuration data		UC2 Preloading default configuration data
	UC3 Documenting factory default settings		UC3 Documenting factory default settings
	UC4 Storing the configuration of a device, e.g., for backup, archive		UC4 Storing the configuration of a device, e.g., for backup,
	or audit purposes		archive, or audit purposes
	UC5 Storing diagnostics data		UC5 Storing diagnostics data
	UC6 Allowing YANG instance data to potentially be carried within		UC6 Allowing YANG instance data to potentially be carried within
	other IPC message formats		other inter-process communication (IPC) message formats
	UC7 Default instance data used as part of a templating solution		UC7 Default instance data used as part of a templating solution
	UC8 Providing data examples in RFCs or internet drafts		UC8 Providing data examples in RFCs or internet drafts
	Appendix C describes the first three use cases in detail.		Appendix B describes the first three use cases in detail.
	There are many and varied use cases where YANG instance data could be		There are many and varied use cases where YANG instance data could be
	used. This document does not limit future uses of instance data		used. This document does not limit future uses of instance data
	sets, so specifying how and when to use YANG instance data is out of		sets, so specifying how and when to use YANG instance data is out of
	scope for this document. It is anticipated that other documents will		scope for this document. It is anticipated that other documents will
	define specific use cases. Use cases are listed only as examples.		define specific use cases. Use cases are listed only as examples.
	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
	14 [RFC2119] [RFC8174] when, and only when, they appear in all		BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
	capitals, as shown here.		capitals, as shown here.
	Instance Data: A collection of instantiated data nodes.		Instance Data: A collection of instantiated data nodes.
	Instance Data Set: A named set of data items annotated with metadata		Instance Data Set: A named set of data items annotated with metadata
	that can be used as instance data in a YANG data tree.		that can be used as instance data in a YANG data tree.
	Instance Data File: A file containing an instance data set formatted		Instance Data File: A file containing an instance data set formatted
	according to the rules described in this document.		according to the rules described in this document.
	Content-schema: A set of YANG modules with their revision, supported		Content-schema: A set of YANG modules with their revision, supported
	features, and deviations for which the instance data set contains		features, and deviations for which the instance data set contains
	instance data.		instance data.
	Content defining YANG module: an individual YANG module that is part		Content-defining YANG Module: An individual YANG module that is part
	of the content-schema.		of the content-schema.
	The term "server" is used as defined in [RFC8342].		The term "server" is used as defined in [RFC8342].
	1.2. Principles		1.2. Principles
	The following is a list of the basic principles of the instance data		The following is a list of the basic principles of the instance data
	format:		format:
	P1 Two standard formats shall be defined based on the XML and JSON		P1 Two standard formats shall be defined based on the XML and JSON
	encodings.		encodings.
	P2 Instance data shall reuse existing encoding rules for YANG		P2 Instance data shall reuse existing encoding rules for YANG-
	defined data.		defined data.
	P3 Metadata about the instance data set (Section 2, Paragraph 12)		P3 Metadata about the instance data set (Section 2, Paragraph 14)
	shall be defined.		shall be defined.
	P4 A YANG instance data set shall be allowed to contain data for		P4 A YANG instance data set shall be allowed to contain data for
	multiple YANG modules.		multiple YANG modules.
	P5 Instance data shall be allowed to contain configuration data,		P5 Instance data shall be allowed to contain configuration data,
	state data, or a mix of the two.		state data, or a mix of the two.
	P6 Partial data sets shall be allowed.		P6 Partial data sets shall be allowed.
	skipping to change at page 4, line 43 ¶		skipping to change at line 180 ¶
	which YANG module(s) are defined and available to the reader,		which YANG module(s) are defined and available to the reader,
	independent of whether the module is implemented by a server.		independent of whether the module is implemented by a server.
	P8 It shall be possible to report the identity of the datastore with		P8 It shall be possible to report the identity of the datastore with
	which the instance data set is associated.		which the instance data set is associated.
	1.3. Delivery of Instance Data		1.3. Delivery of Instance Data
	Instance data sets that are produced as a result of some sort of		Instance data sets that are produced as a result of some sort of
	specification or design effort may be available without the need for		specification or design effort may be available without the need for
	a live server e.g., via download from the vendor's website, or in any		a live server, e.g., via download from the vendor's website or in any
	other way that product documentation is distributed.		other way that product documentation is distributed.
	Other instance data sets may be read from or produced by the YANG		Other instance data sets may be read from or produced by the YANG
	server itself e.g., UC5 documenting diagnostic data.		server itself, e.g., UC5 documenting diagnostic data.
	1.4. Data Life cycle		1.4. Data Life Cycle
	A YANG instance data set is created at a specific point of time. If		A YANG instance data set is created at a specific point of time. If
	the data changes afterwards, the instance data set will no longer		the data changes afterwards, the instance data set will no longer
	represent the current data, unless it is updated. The current values		represent the current data unless it is updated. The current values
	may be retrieved at run-time via NETCONF/RESTCONF or received e.g.,		may be retrieved at runtime via NETCONF/RESTCONF or received, e.g.,
	in YANG-Push notifications.		in YANG-Push notifications.
	Whether the instance data changes and if so, when and how, should be		Whether the instance data changes and, if so, when and how should be
	described either in the instance data set's description statement or		described either in the instance data set's description statement or
	in some other implementation specific manner.		in some other implementation-specific manner.
	2. Instance Data File Format		2. Instance Data File Format
	A YANG instance data file MUST contain a single instance data set and		A YANG instance data file MUST contain a single instance data set and
	no additional data.		no additional data.
	The format of the instance data set is defined by the "ietf-yang-		The format of the instance data set is defined by the "ietf-yang-
	instance-data" YANG module. It is made up of a header part and		instance-data" YANG module. It is made up of a header part and
	content-data. The header part carries metadata for the instance data		content-data. The header part carries metadata for the instance data
	set. The content-data, defined as an anydata data node, carries the		set. The content-data, defined as an anydata data node, carries the
	instance data that the user wants to document/provide. The syntax		instance data that the user wants to document and/or provide. The
	and semantics of content-data is defined by the content-schema.		syntax and semantics of content-data are defined by the content-
			schema.
	Two formats are specified based on the XML and JSON YANG encodings.		Two formats are specified based on the XML and JSON YANG encodings.
	The file formats are achieved by applying the respective XML and JSON		The file formats are achieved by applying the respective XML and JSON
	encoding rules for the YANG structure included in this document.		encoding rules for the YANG structure included in this document.
	Later, as other YANG encodings (e.g., CBOR) are defined, further		Later, as other YANG encodings (e.g., CBOR) are defined, further
	instance data formats may be specified.		instance data formats may be specified.
	The content-data part MUST conform to the content-schema, while		The content-data part MUST conform to the content-schema while
	allowing for the exceptions listed below. The content-data part		allowing for the exceptions listed below. The content-data part
	SHALL follow the encoding rules defined in [RFC7950] for XML and		SHALL follow the encoding rules defined in [RFC7950] for XML and
	[RFC7951] for JSON and MUST use UTF-8 character encoding. Content-		[RFC7951] for JSON and MUST use UTF-8 character encoding. Content-
	data MAY include:		data MAY include:
	* metadata, as defined by [RFC7952].		* metadata, as defined by [RFC7952].
	* origin metadata, as specified in [RFC8526] and [RFC8527]		* origin metadata, as specified in [RFC8526] and [RFC8527].
	* implementation specific metadata relevant to individual data		* implementation-specific metadata relevant to individual data
	nodes. Unknown metadata MUST be ignored by users of instance		nodes. Unknown metadata MUST be ignored by users of instance
	data, allowing it to be used later for other purposes.		data, allowing it to be used later for other purposes.
	An instance data set MAY contain data for any number of YANG modules;		An instance data set MAY contain data for any number of YANG modules;
	if needed it MAY carry the complete configuration and state data for		if needed, it MAY carry the complete configuration and state data for
	a server. Default values should be excluded where they do not		a server. Default values should be excluded where they do not
	provide additional useful data.		provide additional useful data.
	Configuration ("config true") and operational state data ("config		Configuration ("config true") and operational state data ("config
	false") MAY be mixed in the instance data file.		false") MAY be mixed in the instance data file.
	Instance data files MAY contain partial data sets. This means		Instance data files MAY contain partial data sets. This means
	"mandatory", "min-elements", "require-instance true", "must" and		"mandatory", "min-elements", "require-instance true", "must", and
	"when" constraints MAY be violated.		"when" constraints MAY be violated.
	The name of the instance data file SHOULD be of the form (using ABNF		The name of the instance data file SHOULD be of the following form
	notation [RFC5234]):		(using ABNF notation [RFC5234]):
	instance-data-set-name ["@" ( revision-date / timestamp ) ]		instance-data-set-name ["@" ( revision-date / timestamp ) ]
	( ".xml" / ".json" )		( ".xml" / ".json" )
	E.g., acme-router-modules.xml		Examples include:
	E.g., acme-router-modules@2018-01-25.xml
	E.g., acme-router-modules@2018-01-25T15_06_34_3+01_00.json		acme-router-modules.xml
			acme-router-modules@2018-01-25.xml
			acme-router-modules@2018-01-25T15_06_34_3+01_00.json
	If the leaf "name" is present in the instance data header, its value		If the leaf "name" is present in the instance data header, its value
	SHOULD be used for the "instance-data-set-name" in the filename. If		SHOULD be used for the "instance-data-set-name" in the filename. If
	the "revision-date" is present in the filename it MUST conform to the		the "revision-date" is present in the filename, it MUST conform to
	format of the revision-date leaf in the YANG model. If the		the format of the revision-date leaf in the YANG model. If the
	"revision-date" is present in both the filename and in the instance		"revision-date" is present in both the filename and the instance data
	data header, the revision date in the file name MUST be set to the		header, the revision date in the filename MUST be set to the latest
	latest revision date inside the instance data set. If the		revision date inside the instance data set. If the "timestamp" is
	"timestamp" is present in the filename it MUST conform to the format		present in the filename, it MUST conform to the format of the
	of the timestamp leaf in the YANG model except for replacing colons		timestamp leaf in the YANG model except for replacing colons as
	as described below. If the "timestamp" is present both in the		described below. If the "timestamp" is present in both the filename
	filename and in the instance data header, the timestamp in the file		and the instance data header, the timestamp in the filename SHOULD be
	name SHOULD be set to the timestamp inside the instance data set; any		set to the timestamp inside the instance data set; any colons, if
	colons, if present, shall be replaced by underscores.		present, shall be replaced by underscores.
	Metadata, information about the data set itself MUST be included.		Metadata, information about the data set itself, MUST be included.
	Some metadata items are defined in the YANG module "ietf-yang-		Some metadata items are defined in the YANG module "ietf-yang-
	instance-data", but other items MAY be used.		instance-data", but other items MAY be used.
	Metadata MUST include:		Metadata MUST include:
	- Version of the YANG Instance Data format (if not explicitly		- Version of the YANG instance data format (if not explicitly
	present the default value is used)		present, the default value is used).
	Metadata SHOULD include:		Metadata SHOULD include:
	- Name of the data set		- Name of the data set.
			- Content-schema specification (i.e., the "content-schema" node).
	- Content-schema specification (i.e., the "content-schema" node)
	- Description of the instance data set. The description SHOULD		- Description of the instance data set. The description SHOULD
	contain information whether and how the data can change during		contain information on whether and how the data can change
	the lifetime of the server		during the lifetime of the server.
	- An indication whether default values are included. The default		- An indication of whether default values are included. The
	handling uses the concepts defined in [RFC6243], however as		default handling uses the concepts defined in [RFC6243];
	only concepts are re-used, users of instance data sets, do not		however, as only concepts are re-used, users of instance data
	need to support RFC 6243.		sets do not need to support [RFC6243].
	2.1. Specifying the Content Schema		2.1. Specifying the Content Schema
	To properly understand and use an instance data set, the user needs		To properly understand and use an instance data set, the user needs
	to know the content-schema. The content-schema can be either		to know the content-schema. The content-schema can be specified
	specified in external documents or within the instance data set. In		either in external documents or within the instance data set. In the
	the latter case one of the following methods MUST be used:		latter case, one of the following methods MUST be used:
	Inline method: Include the needed information as part of the		Inline method: Include the needed information as part of the
	instance data set.		instance data set.
	Simplified-Inline method: Include the needed information as part		Simplified-inline method: Include the needed information as part of
	of the instance data set; short specification, only the module		the instance data set; only the modules' name and revision-date
	name and revision-date is used.		are used.
	URI method: Include a URI that references another YANG instance		URI method: Include a URI that references another YANG instance data
	data file. This instance data file will use the same content-		file. This instance data file will use the same content-schema as
	schema as the referenced YANG instance data file. (if you don't		the referenced YANG instance data file (if you don't want to
	want to repeat the info again and again)		repeat the info again and again).
	Additional methods e.g., a YANG-package based solution may be added		Additional methods, e.g., a YANG-package-based solution may be added
	later.		later.
	Note, the specified content-schema only indicates the set of modules		Note that the specified content-schema only indicates the set of
	that were used to define this YANG instance data set. Sometimes		modules that were used to define this YANG instance data set.
	instance data may be used for a server supporting a different YANG		Sometimes instance data may be used for a server supporting a
	module set (e.g., for the "Preloading default configuration data"		different YANG module set (e.g., for the "Preloading default
	use-case, UC2 in Section 1, the instance data set may not be updated		configuration data" use case, UC2 in Section 1, the instance data set
	every time the YANG modules on the server are updated). Whether an		may not be updated every time the YANG modules on the server are
	instance data set originally defined using a specific content-schema		updated). Whether an instance data set originally defined using a
	is usable with a different other schema depends on many factors		specific content-schema is usable with another schema depends on many
	including the amount of differences and the compatibility between the		factors, including the number of differences and the compatibility
	original and the other schema, considering modules, revisions,		between the original and the other schema when considering modules,
	features, deviations, the scope of the instance data, etc.		revisions, features, deviations, the scope of the instance data, etc.
	2.1.1. Inline Method		2.1.1. Inline Method
	The inline-yang-library anydata data node carries instance data		The "inline-yang-library" anydata data node carries instance data
	(conforming to ietf-yang-library@2019-01-04) [RFC8525] that specifies		(conforming to "ietf-yang-library@2019-01-04") [RFC8525] that
	the content defining YANG modules including revision, supported		specifies the content-defining YANG modules, including revision,
	features, deviations and any relevant additional data. An example of		supported features, deviations, and any additional relevant data. An
	the "inline" method is provided in Section 2.2.1.		example of the inline method is provided in Section 2.2.1.
	2.1.2. Simplified-Inline Method		2.1.2. Simplified-Inline Method
	The instance data set contains a list of content defining YANG		The instance data set contains a list of content-defining YANG
	modules including the revision date for each. Usage of this method		modules, including the revision date for each. Usage of this method
	implies that the modules are used without any deviations and with all		implies that the modules are used without any deviations and with all
	features supported. YANG modules that are only required to satisfy		features supported. YANG modules that are only required to satisfy
	import-only dependencies MAY be excluded from the leaf-list. If they		import-only dependencies MAY be excluded from the leaf-list. If they
	are excluded then the consumer of the instance data set has to apply		are excluded, then the consumer of the instance data set has to apply
	the YANG language rules to resolve the imports. An example of the		the YANG language rules to resolve the imports. An example of the
	"simplified-inline" method is provided in Section 2.2.2.		simplified-inline method is provided in Section 2.2.2.
	2.1.3. URI Method		2.1.3. URI Method
	The "same-schema-as-file" leaf SHALL contain a URI that references		The "same-schema-as-file" leaf SHALL contain a URI that references
	another YANG instance data file. The current instance data file will		another YANG instance data file. The current instance data file will
	use the same content-schema as the referenced file.		use the same content-schema as the referenced file.
	The referenced instance data file MAY have no content-data if it is		The referenced instance data file MAY have no content-data if it is
	used solely for specifying the content-schema.		used solely for specifying the content-schema.
	If a referenced instance data file is unavailable, content-schema is		If a referenced instance data file is unavailable, the content-schema
	unknown.		is unknown.
	The URI method is advantageous when the user wants to avoid the		The URI method is advantageous when the user wants to avoid the
	overhead of specifying the content-schema in each instance data file:		overhead of specifying the content-schema in each instance data file
	E.g., In UC6, when the system creates a diagnostic file every minute		-- for example, in UC6, when the system creates a diagnostic file
	to document the state of the server.		every minute to document the state of the server.
	An example of the "URI" method is provided in Section 2.2.3.		An example of the URI method is provided in Section 2.2.3.
	2.2. Examples		2.2. Examples
	2.2.1. Documentation of server capabilities		2.2.1. Documentation of Server Capabilities
	The example file acme-router-modules@2021-09-16.xml reflects UC1 in		The example file acme-router-modules@2022-01-20.xml reflects UC1 in
	Section 1. It provides a list of supported YANG modules and NETCONF		Section 1. It provides a list of supported YANG modules and NETCONF
	capabilities for a server. It uses the "inline" method to specify		capabilities for a server. It uses the inline method to specify the
	the content-schema.		content-schema.
	The example uses artwork folding [RFC8792].		The example uses artwork folding [RFC8792].
	========== NOTE: '\' line wrapping per RFC 8792 ===========		========== NOTE: '\' line wrapping per RFC 8792 ===========
	<?xml version="1.0" encoding="UTF-8"?>		<?xml version="1.0" encoding="UTF-8"?>
	<instance-data-set xmlns=\		<instance-data-set xmlns=\
	"urn:ietf:params:xml:ns:yang:ietf-yang-instance-data">		"urn:ietf:params:xml:ns:yang:ietf-yang-instance-data">
	<name>acme-router-modules</name>		<name>acme-router-modules</name>
	<content-schema>		<content-schema>
	<inline-yang-library>		<inline-yang-library>
	<modules-state \		<modules-state \
	xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">		xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
	<module>		<module>
	<name>ietf-yang-library</name>		<name>ietf-yang-library</name>
	<revision>2019-01-04</revision>		<revision>2019-01-04</revision>
	</module>		</module>
	<module>		<module>
	<name>ietf-netconf-monitoring</name>		<name>ietf-netconf-monitoring</name>
	<revision>2010-10-04</revision>		<revision>2010-10-04</revision>
	</module>		</module>
	</modules-state>		</modules-state>
	</inline-yang-library>		</inline-yang-library>
	</content-schema>		</content-schema>
	<revision>		<revision>
	<date>2020-10-23</date>		<date>2020-10-23</date>
	<description>Initial version</description>		<description>Initial version</description>
	</revision>		</revision>
	<description>Defines the minimal set of modules that any \		<description>Defines the minimal set of modules that any \
	acme-router will contain. This minimal set will \		acme-router will contain. This minimal set will \
	only change when a new SW release is \		only change when a new software release is \
	introduced.</description>		introduced.</description>
	<contact>info@acme.example.com</contact>		<contact>info@acme.example.com</contact>
	<content-data>		<content-data>
	<modules-state \		<modules-state \
	xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">		xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
	<module>		<module>
	<name>ietf-yang-library</name>		<name>ietf-yang-library</name>
	<revision>2019-01-04</revision>		<revision>2019-01-04</revision>
	<namespace>\		<namespace>\
	urn:ietf:params:xml:ns:yang:ietf-yang-library\		urn:ietf:params:xml:ns:yang:ietf-yang-library\
	</namespace>		</namespace>
	<conformance-type>implement</conformance-type>		<conformance-type>implement</conformance-type>
	</module>		</module>
	<module>		<module>
	<name>ietf-system</name>		<name>ietf-system</name>
	<revision>2014-08-06</revision>		<revision>2014-08-06</revision>
	<namespace>urn:ietf:params:xml:ns:yang:ietf-system</namespace>		<namespace>urn:ietf:params:xml:ns:yang:ietf-system</namespace>
	<feature>sys:authentication</feature>		<feature>sys:authentication</feature>
	<feature>sys:local-users</feature>		<feature>sys:local-users</feature>
	<deviation>		<deviation>
	<name>acme-system-ext</name>		<name>acme-system-ext</name>
	<revision>2018-08-06</revision>		<revision>2018-08-06</revision>
	</deviation>		</deviation>
	<conformance-type>implement</conformance-type>		<conformance-type>implement</conformance-type>
	</module>		</module>
	<module>		<module>
	<name>ietf-netconf-monitoring</name>		<name>ietf-netconf-monitoring</name>
	<revision>2010-10-04</revision>		<revision>2010-10-04</revision>
	<namespace>\		<namespace>\
	urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring\		urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring\
	</namespace>		</namespace>
	<conformance-type>implement</conformance-type>		<conformance-type>implement</conformance-type>
	</module>		</module>
	<module>		<module>
	<name>ietf-yang-types</name>		<name>ietf-yang-types</name>
	<revision>2013-07-15</revision>		<revision>2013-07-15</revision>
	<namespace>urn:ietf:params:xml:ns:yang:ietf-yang-types\		<namespace>urn:ietf:params:xml:ns:yang:ietf-yang-types\
	</namespace>		</namespace>
	<conformance-type>import</conformance-type>		<conformance-type>import</conformance-type>
	</module>		</module>
	<module>		<module>
	<name>acme-system-ext</name>		<name>acme-system-ext</name>
	<revision>2018-08-06</revision>		<revision>2018-08-06</revision>
	<namespace>\		<namespace>\
	urn:rdns:acme.example.com:oammodel:acme-system-ext\		urn:rdns:acme.example.com:oammodel:acme-system-ext\
	</namespace>		</namespace>
	<conformance-type>implement</conformance-type>		<conformance-type>implement</conformance-type>
	</module>		</module>
	</modules-state>		</modules-state>
	<netconf-state \		<netconf-state \
	xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">		xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
	<capabilities>		<capabilities>
	<capability>\		<capability>\
	urn:ietf:params:netconf:capability:validate:1.1\		urn:ietf:params:netconf:capability:validate:1.1\
	</capability>		</capability>
	</capabilities>		</capabilities>
	</netconf-state>		</netconf-state>
	</content-data>		</content-data>
	</instance-data-set>		</instance-data-set>
	Figure 1		Figure 1
	2.2.2. Preloading default configuration data		2.2.2. Preloading Default Configuration Data
	The example file read-only-acm-rules@2021-09-16.xml reflects UC2 in		The example file read-only-acm-rules@2022-01-20.xml reflects UC2 in
	Section 1. It provides a default rule set for a read-only operator		Section 1. It provides a default rule set for a read-only operator
	role. It uses the "simplified-inline" method for specifying the		role. It uses the simplified-inline method for specifying the
	content-schema.		content-schema.
	========== NOTE: '\' line wrapping per RFC 8792 ===========		========== NOTE: '\' line wrapping per RFC 8792 ===========
	<?xml version="1.0" encoding="UTF-8"?>		<?xml version="1.0" encoding="UTF-8"?>
	<instance-data-set		<instance-data-set
	xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-instance-data">		xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-instance-data">
	<name>read-only-acm-rules</name>		<name>read-only-acm-rules</name>
	<content-schema>		<content-schema>
	<module>ietf-netconf-acm@2018-02-14</module>		<module>ietf-netconf-acm@2018-02-14</module>
	</content-schema>		</content-schema>
	<revision>		<revision>
	<date>2018-07-04</date>		<date>2018-07-04</date>
	<description>Initial version</description>		<description>Initial version</description>
	</revision>		</revision>
	<description>Default access control rules for a read-only \		<description>Default access control rules for a read-only \
	role. This set of rules will only change when a new \		role. This set of rules will only change when a new \
	SW release is introduced.</description>		software release is introduced.</description>
	<content-data>		<content-data>
	<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">		<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
	<enable-nacm>true</enable-nacm>		<enable-nacm>true</enable-nacm>
	<read-default>deny</read-default>		<read-default>deny</read-default>
	<exec-default>deny</exec-default>		<exec-default>deny</exec-default>
	<rule-list>		<rule-list>
	<name>read-only-role</name>		<name>read-only-role</name>
	<group>read-only-group</group>		<group>read-only-group</group>
	<rule>		<rule>
	<name>read-all</name>		<name>read-all</name>
	skipping to change at page 11, line 42 ¶		skipping to change at line 510 ¶
	<access-operation>read</access-operation>		<access-operation>read</access-operation>
	<action>permit</action>		<action>permit</action>
	</rule>		</rule>
	</rule-list>		</rule-list>
	</nacm>		</nacm>
	</content-data>		</content-data>
	</instance-data-set>		</instance-data-set>
	Figure 2		Figure 2
	2.2.3. Storing diagnostics data		2.2.3. Storing Diagnostics Data
	The example file acme-router-netconf-		The example file acme-router-netconf-
	diagnostics@2018-01-25T17_00_38Z.json reflects UC5 in Section 1. An		diagnostics@2018-01-25T17_00_38Z.json reflects UC5 in Section 1. An
	instance data set is produced by the server every 15 minutes that		instance data set that contains statistics about the NETCONF server
	contains statistics about the NETCONF server. As a new set is		is produced by the server every 15 minutes. As a new set is produced
	produced periodically many times a day a revision-date would be		periodically many times a day, a revision-date would be useless;
	useless; instead a timestamp is included.		instead, a timestamp is included.
	========== NOTE: '\' line wrapping per RFC 8792 ===========		========== NOTE: '\' line wrapping per RFC 8792 ===========
	{		{
	"ietf-yang-instance-data:instance-data-set": {		"ietf-yang-instance-data:instance-data-set": {
	"name": "acme-router-netconf-diagnostics",		"name": "acme-router-netconf-diagnostics",
	"content-schema": {		"content-schema": {
	"same-schema-as-file": "file:///acme-diagnostics-schema.json"		"same-schema-as-file": "file:///acme-diagnostics-schema.json"
	},		},
	"timestamp": "2018-01-25T17:00:38Z",		"timestamp": "2018-01-25T17:00:38Z",
	skipping to change at page 13, line 6 ¶		skipping to change at line 557 ¶
	Figure 3		Figure 3
	3. YANG Instance Data Model		3. YANG Instance Data Model
	3.1. Tree Diagram		3.1. Tree Diagram
	The following tree diagram [RFC8340] provides an overview of the data		The following tree diagram [RFC8340] provides an overview of the data
	model.		model.
	module: ietf-yang-instance-data		module: ietf-yang-instance-data
	structure instance-data-set:		structure instance-data-set:
	+-- name? string		+--name? string
	+-- format-version? string		+--format-version? string
	+-- includes-defaults? enumeration		+--includes-defaults? enumeration
	+-- content-schema		+--content-schema
	| +-- (content-schema-spec)?		| +--(content-schema-spec)?
	| +--:(simplified-inline)		| +--:(simplified-inline)
	| | +-- module* module-with-revision-date		| | +--module* module-with-revision-date
	| +--:(inline)		| +--:(inline)
	| | +-- inline-yang-library <anydata>		| | +--inline-yang-library <anydata>
	| +--:(uri)		| +--:(uri)
	| +-- same-schema-as-file? inet:uri		| +--same-schema-as-file? inet:uri
	+-- description* string		+--description* string
	+-- contact? string		+--contact? string
	+-- organization? string		+--organization? string
	+-- datastore? ds:datastore-ref		+--datastore? ds:datastore-ref
	+-- revision* [date]		+--revision* [date]
	| +-- date string		| +--date string
	| +-- description? string		| +--description? string
	+-- timestamp? yang:date-and-time		+--timestamp? yang:date-and-time
	+-- content-data? <anydata>		+--content-data? <anydata>
	3.2. YANG Model		3.2. YANG Model
	This YANG module imports typedefs from [RFC6991], [RFC6243],		This YANG module imports typedefs from [RFC6991], [RFC6243],
	identities from [RFC8342] and the "structure" extension from		identities from [RFC8342], and the "structure" extension from
	[RFC8791]. It also references [RFC8525].		[RFC8791]. It also references [RFC8525].
	<CODE BEGINS> file "ietf-yang-instance-data@2021-09-16.yang"		<CODE BEGINS> file "ietf-yang-instance-data@2022-01-20.yang"
	// RFC Ed.: replace the date above if the module gets changed in
	//any way during reviews or RFC editor process and remove this note
	module ietf-yang-instance-data {		module ietf-yang-instance-data {
	yang-version 1.1;		yang-version 1.1;
	namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data";		namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data";
	prefix yid;		prefix yid;
	import ietf-yang-structure-ext {		import ietf-yang-structure-ext {
	prefix sx;		prefix sx;
	reference		reference
	"YANG Data Structure Extensions:		"RFC 8791: YANG Data Structure Extensions";
	draft-ietf-netmod-yang-data-ext-05";
	}		}
	import ietf-datastores {		import ietf-datastores {
	prefix ds;		prefix ds;
	reference		reference
	"RFC 8342: Network Management Datastore Architecture (NMDA)";		"RFC 8342: Network Management Datastore Architecture (NMDA)";
	}		}
	import ietf-inet-types {		import ietf-inet-types {
	prefix inet;		prefix inet;
	reference		reference
	"RFC 6991: Common YANG Data Types";		"RFC 6991: Common YANG Data Types";
	}		}
	import ietf-yang-types {		import ietf-yang-types {
	prefix yang;		prefix yang;
	reference		reference
	"RFC 6991: Common YANG Data Types";		"RFC 6991: Common YANG Data Types";
	skipping to change at page 14, line 45 ¶		skipping to change at line 639 ¶
	"The module defines the structure and content of YANG		"The module defines the structure and content of YANG
	instance data sets.		instance data sets.
	The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',		The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
	'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',		'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
	'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document		'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
	are to be interpreted as described in BCP 14 (RFC 2119)		are to be interpreted as described in BCP 14 (RFC 2119)
	(RFC 8174) when, and only when, they appear in all		(RFC 8174) when, and only when, they appear in all
	capitals, as shown here.		capitals, as shown here.
	Copyright (c) 2021 IETF Trust and the persons identified as		Copyright (c) 2022 IETF Trust and the persons identified 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 the license terms contained in, the Simplified BSD License		to the license terms contained in, the Revised BSD License
	set forth in Section 4.c of the IETF Trust's Legal Provisions		set forth in Section 4.c of the IETF Trust's
	Relating to IETF Documents		Legal Provisions Relating to IETF Documents
	(http://trustee.ietf.org/license-info).		(https://trustee.ietf.org/license-info).
	This version of this YANG module is part of RFC XXXX; see		This version of this YANG module is part of RFC 9195
	the RFC itself for full legal notices.";		(https://www.rfc-editor.org/info/rfc9195); see the RFC itself
	// RFC Ed.: replace XXXX with RFC number and remove this note		for full legal notices.";
	revision 2021-09-16 {		revision 2022-01-20 {
	// RFC Ed.: replace the date above if the module gets changed in
	// anyway during reviews or RFC editor process and remove
	//this note
	description		description
	"Initial revision.";		"Initial revision.";
	reference		reference
	"RFC XXXX: YANG Instance Data Format";		"RFC 9195: YANG Instance Data File Format";
	// RFC Ed.: replace XXXX with RFC number and remove this note
	}		}
	typedef module-with-revision-date {		typedef module-with-revision-date {
	type string {		type string {
	pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'		pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'
	+ '(@\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1]))?';		+ '(@\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1]))?';
	pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*';		pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*';
	}		}
	description		description
	"A type defining a module name and an optional revision		"A type defining a module name and an optional revision
	date, e.g. ietf-yang-library@2019-01-04";		date, e.g., ietf-yang-library@2019-01-04.";
	}		}
	sx:structure "instance-data-set" {		sx:structure instance-data-set {
	description		description
	"A data structure to define a format for YANG instance		"A data structure to define a format for YANG instance
	data. The majority of the YANG nodes provide meta-data		data. The majority of the YANG nodes provides metadata
	about the instance data; the instance data itself is		about the instance data; the instance data itself is
	contained only in the 'content-data' node.";		contained only in the 'content-data' node.";
	leaf name {		leaf name {
	type string;		type string;
	description		description
	"An arbitrary name for the YANG instance data set. This		"An arbitrary name for the YANG instance data set. This
	value is primarily used for descriptive purposes. However,		value is primarily used for descriptive purposes. However,
	when the instance data set is saved to a file, then the		when the instance data set is saved to a file, then the
	filename MUST encode the name's value, per Section 2		filename MUST encode the name's value per Section 2
	of RFC XXXX.";		of RFC 9195.";
	// RFC Ed.: replace XXXX with RFC number and remove this note
	}		}
	leaf format-version {		leaf format-version {
	type string {		type string {
	pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';		pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
	}		}
	default "2021-09-16";		default "2022-01-20";
	// RFC Ed.: replace the date above if the module gets changed
	// in anyway during reviews or RFC editor process and remove
	// this note
	description		description
	"The 'revision' of the 'ietf-yang-instance-data' module		"The 'revision' of the 'ietf-yang-instance-data' module
	used to encode this 'instance-data-set'.";		used to encode this 'instance-data-set'.";
	}		}
	leaf includes-defaults {		leaf includes-defaults {
	type ncwd:with-defaults-mode;		type ncwd:with-defaults-mode;
	default report-all;		default "report-all";
	description "		description
	Indicates how data nodes with default values are		"Indicates how data nodes with default values are
	represented for all data nodes contained in the		represented for all data nodes contained in the
	instance-data-set.		instance-data-set.
	It uses the same definitions as per section 3 of RFC 6243,		It uses the same definitions as per Section 3 of RFC 6243
	but applied in the context of an instance data file rather		but applied in the context of an instance data file rather
	than a NETCONF request using the <with-defaults>		than a NETCONF request using the <with-defaults>
	parameter.		parameter.
	For JSON files, the encoding of the 'report-all-tagged'		For JSON files, the encoding of the 'report-all-tagged'
	option is as defined in section 4.8.9 of RFC 8040.";		option is as defined in Section 4.8.9 of RFC 8040.";
	reference "With-defaults Capability for NETCONF, RFC 6243.";		reference
			"RFC 6243: With-defaults Capability for NETCONF";
	}		}
	container content-schema {		container content-schema {
	description		description
	"The content schema (i.e., YANG modules) used to create		"The content schema (i.e., YANG modules) used to create
	the instance data set.		the instance data set.
	If not present the user needs to obtain the information		If not present, the user needs to obtain the information
	through external documents.";		through external documents.";
	choice content-schema-spec {		choice content-schema-spec {
	description		description
	"Specification of the content-schema.";		"Specification of the content-schema.";
	case simplified-inline {		case simplified-inline {
	leaf-list module {		leaf-list module {
	type module-with-revision-date;		type module-with-revision-date;
	min-elements 1;		min-elements 1;
	description		description
	"The list of content defining YANG modules.		"The list of content-defining YANG modules.
	The value SHALL start with the module name.		The value SHALL start with the module name.
	If the module contains a revision statement the		If the module contains a revision statement, the
	revision date SHALL be included in the leaf-list		revision date SHALL be included in the leaf-list
	entry.		entry, e.g., ietf-yang-library@2019-01-04.
	E.g., ietf-yang-library@2019-01-04
	Usage of this leaf-list implies the modules are		Usage of this leaf-list implies the modules are
	used without any deviations and with all features		used without any deviations and with all features
	supported. Multiple revisions of the same module		supported. Multiple revisions of the same module
	MUST NOT be specified.";		MUST NOT be specified.";
	}		}
	}		}
	case inline {		case inline {
	anydata inline-yang-library {		anydata inline-yang-library {
	mandatory true;		mandatory true;
	description		description
	"Instance data corresponding to the		"Instance data corresponding to the
	ietf-yang-library@2019-01-04 defining		ietf-yang-library@2019-01-04 defining
	the set of content defining YANG modules for		the set of content-defining YANG modules for
	this instance-data-set.";		this instance-data-set.";
	}		}
	}		}
	case uri {		case uri {
	leaf same-schema-as-file {		leaf same-schema-as-file {
	type inet:uri;		type inet:uri;
	description		description
	"A reference to another YANG instance data file.		"A reference to another YANG instance data file.
	This instance data file uses the same		This instance data file uses the same
	content schema as the referenced file.		content schema as the referenced file.
	Referenced files using the 'inline' or the		Referenced files using the 'inline' or the
	'simplified-inline' methods MUST be supported.		'simplified-inline' methods MUST be supported.
	Referenced files using the 'URI Method' MAY be		Referenced files using the 'URI method' MAY be
	supported.		supported.
	The URL schemes 'file://' and 'https://' MUST		The URL schemes 'file://' and 'https://' MUST
	be supported, other schemes MAY also be		be supported; other schemes MAY also be
	supported.";		supported.";
	}		}
	}		}
	}		}
	}		}
	leaf-list description {		leaf-list description {
	type string;		type string;
	description		description
	"Description of the instance data set.";		"Description of the instance data set.";
	}		}
	skipping to change at page 18, line 15 ¶		skipping to change at line 793 ¶
	type string;		type string;
	description		description
	"Organization responsible for the instance		"Organization responsible for the instance
	data set.";		data set.";
	}		}
	leaf datastore {		leaf datastore {
	type ds:datastore-ref;		type ds:datastore-ref;
	description		description
	"The identity of the datastore with which the		"The identity of the datastore with which the
	instance data set is associated, e.g., the datastore from		instance data set is associated, e.g., the datastore from
	where the data was read or the datastore into which the data		where the data was read, the datastore into which the data
	may be loaded or the datastore which is being documented.		may be loaded, or the datastore that is being documented.
	If a single specific datastore cannot be specified, the		If a single specific datastore cannot be specified, the
	leaf MUST be absent.		leaf MUST be absent.
	If this leaf is absent, then the datastore to which the		If this leaf is absent, then the datastore to which the
	instance data belongs is unspecified.";		instance data belongs is unspecified.";
	}		}
	list revision {		list revision {
	key "date";		key "date";
	description		description
	"Instance data sets that are produced as		"Instance data sets that are produced as
	a result of some sort of specification or design effort		a result of some sort of specification or design effort
	SHOULD have at least one revision entry. For every		SHOULD have at least one revision entry. For every
	published editorial change, a new unique revision SHOULD		published editorial change, a new unique revision SHOULD
	be added in front of the revisions sequence so that all		be added in front of the revisions sequence so that all
	revisions are in reverse chronological order.		revisions are in reverse chronological order.
	In case of instance data sets that are read from		In cases of instance data sets that are read from
	or produced by a server or otherwise subject to		or produced by a server or otherwise subject to
	frequent updates or changes, revision		frequent updates or changes, revision
	SHOULD NOT be present";		SHOULD NOT be present.";
	leaf date {		leaf date {
	type string {		type string {
	pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';		pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
	}		}
	description		description
	"Specifies the date the instance data set		"Specifies the date the instance data set
	was last modified. Formatted as YYYY-MM-DD";		was last modified. Formatted as YYYY-MM-DD.";
	}		}
	leaf description {		leaf description {
	type string;		type string;
	description		description
	"Description of this revision of the instance data set.";		"Description of this revision of the instance data set.";
	}		}
	}		}
	leaf timestamp {		leaf timestamp {
	type yang:date-and-time;		type yang:date-and-time;
	description		description
	"The date and time when the instance data set		"The date and time when the instance data set
	was last modified.		was last modified.
	In case of instance data sets that are read from or		In cases of instance data sets that are read from or
	produced by a server or otherwise subject to frequent		produced by a server or otherwise subject to frequent
	updates or changes, timestamp SHOULD be present.		updates or changes, the timestamp SHOULD be present.
	If both a revision list entry and timestamp are present		If both a revision list entry and timestamp are present,
	the timestamp SHOULD contain the same date as the		the timestamp SHOULD contain the same date as the
	latest revision statement.";		latest revision statement.";
	}		}
	anydata content-data {		anydata content-data {
	description		description
	"Contains the real instance data.		"Contains the real instance data.
	The data MUST conform to the relevant YANG modules		The data MUST conform to the relevant YANG modules
	specified either in the content-schema or in some other		specified either in the content-schema or in some other
	implementation specific manner.";		implementation-specific manner.";
	}		}
	}		}
	}		}
	<CODE ENDS>		<CODE ENDS>
	4. Security Considerations		4. Security Considerations
	The YANG module defined in this document only defines a wrapper		The YANG module defined in this document only defines a wrapper
	structure specifying a format and a metadata header for YANG instance		structure specifying a format and a metadata header for YANG instance
	data defined by the content-schema. Because of this the security		data defined by the content-schema. Because of this, the security
	considerations template for YANG models in section 3.7.1 in [RFC8407]		considerations template for YANG models in Section 3.7.1 of [RFC8407]
	is not followed. The instance data is designed to be accessed as a		is not followed. The instance data is designed to be accessed as a
	stored file or over any file access method or protocol.		stored file or over any file access method or protocol.
	The document does not specify any method to influence the behavior of		The document does not specify any method to influence the behavior of
	a server.		a server.
	The header part is usually not security sensitive, however sensitive		The header part is usually not security sensitive; however, sensitive
	information may be included, in which case it needs to be handled		information may be included, in which case it needs to be handled
	securely as mentioned below. Information to consider includes:		securely, as mentioned below. Information to consider includes:
	* If the URI method is used for specification of the content-schema		* If the URI method is used for specification of the content-schema
	and the URI includes a userinfo subcomponent		and the URI includes a userinfo subcomponent
	* Any description text		* Any description text
	The content part may contain sensitive data. The security		The content part may contain sensitive data. The security
	sensitivity of this data is completely dependent on the content-		sensitivity of this data is completely dependent on the content-
	schema. Depending on the nature of the instance data, instance data		schema. Depending on the nature of the instance data, instance data
	files MAY need to be handled securely. The same kind of handling		files MAY need to be handled securely. The same kind of handling
	should be applied to this file at-rest and in-transit that would be		should be applied to this file at rest and in transit that would be
	needed for the result of a read operation returning the same data.		needed for the result of a read operation returning the same data.
	These in-transit protection mechanisms will also mitigate integrity		These in-transit protection mechanisms will also mitigate integrity
	issues when transporting the file.		issues when transporting the file.
	Instance data files should be protected against modification or		Instance data files should be protected against modification or
	unauthorized access using normal file handling mechanisms. Care		unauthorized access using normal file-handling mechanisms. When
	should be taken, when copying the original files or providing file		copying the original files or providing file access for additional
	access for additional users, not to reveal information		users, care should be taken not to reveal information
	unintentionally.		unintentionally.
	If the URI method is used for specification of the content-schema,		If the URI method is used for specification of the content-schema,
	there is a risk that the config schema section in the referenced YANG		there is a risk that the config schema section in the referenced YANG
	instance data file may be altered maliciously or even as part of its		instance data file may be altered maliciously or even as part of its
	normal handling. In this case the content-schema might differ from		normal handling. In this case, the content-schema might differ from
	the one expected. Protecting the integrity and stability of the		the one expected. Protecting the integrity and stability of the
	referenced file should be ensured.		referenced file should be ensured.
	5. IANA Considerations		5. IANA Considerations
	This document registers one URI and one YANG module.		This document registers one URI and one YANG module.
	5.1. URI Registration		5.1. URI Registration
	This document registers one URI in the IETF XML registry [RFC3688].		This document registers the following URI in the "IETF XML Registry"
	Following the format in RFC 3688, the following registration is		[RFC3688]:
	requested to be made:
	URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data		URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data
	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.
	5.2. YANG Module Name Registration		5.2. YANG Module Name Registration
	This document registers one YANG module in the YANG Module Names		This document registers the following YANG module in the "YANG Module
	registry [RFC6020]. Following the format in [RFC6020], the following		Names" registry [RFC6020]:
	registrations are requested:
	name: ietf-yang-instance-data
	namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data
	prefix: yid
	reference: RFC XXXX
	// RFC Ed.: replace XXXX with RFC number and remove this note
	6. Acknowledgments
	For their valuable comments, discussions, and feedback, we wish to		Name: ietf-yang-instance-data
	acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe		Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data
	Clarke, Kent Watsen, Martin Bjorklund, Ladislav Lhotka, Qin Wu and		Prefix: yid
	other members of the Netmod WG.		Reference: RFC 9195
	7. References		6. References
	7.1. Normative References		6.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,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<https://www.rfc-editor.org/info/rfc2119>.		<https://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,		Specifications: ABNF", STD 68, RFC 5234,
	DOI 10.17487/RFC5234, January 2008,		DOI 10.17487/RFC5234, January 2008,
	<https://www.rfc-editor.org/info/rfc5234>.		<https://www.rfc-editor.org/info/rfc5234>.
	skipping to change at page 22, line 35 ¶		skipping to change at line 989 ¶
	[RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,		[RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
	and R. Wilton, "RESTCONF Extensions to Support the Network		and R. Wilton, "RESTCONF Extensions to Support the Network
	Management Datastore Architecture", RFC 8527,		Management Datastore Architecture", RFC 8527,
	DOI 10.17487/RFC8527, March 2019,		DOI 10.17487/RFC8527, March 2019,
	<https://www.rfc-editor.org/info/rfc8527>.		<https://www.rfc-editor.org/info/rfc8527>.
	[RFC8791] Bierman, A., Björklund, M., and K. Watsen, "YANG Data		[RFC8791] Bierman, A., Björklund, M., and K. Watsen, "YANG Data
	Structure Extensions", RFC 8791, DOI 10.17487/RFC8791,		Structure Extensions", RFC 8791, DOI 10.17487/RFC8791,
	June 2020, <https://www.rfc-editor.org/info/rfc8791>.		June 2020, <https://www.rfc-editor.org/info/rfc8791>.
	7.2. Informative References		6.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,		DOI 10.17487/RFC3688, January 2004,
	<https://www.rfc-editor.org/info/rfc3688>.		<https://www.rfc-editor.org/info/rfc3688>.
	[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",		[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
	BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,		BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
	<https://www.rfc-editor.org/info/rfc8340>.		<https://www.rfc-editor.org/info/rfc8340>.
	[RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of		[RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of
	skipping to change at page 23, line 18 ¶		skipping to change at line 1021 ¶
	[RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,		[RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
	"Handling Long Lines in Content of Internet-Drafts and		"Handling Long Lines in Content of Internet-Drafts and
	RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,		RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
	<https://www.rfc-editor.org/info/rfc8792>.		<https://www.rfc-editor.org/info/rfc8792>.
	[RFC8808] Wu, Q., Lengyel, B., and Y. Niu, "A YANG Data Model for		[RFC8808] Wu, Q., Lengyel, B., and Y. Niu, "A YANG Data Model for
	Factory Default Settings", RFC 8808, DOI 10.17487/RFC8808,		Factory Default Settings", RFC 8808, DOI 10.17487/RFC8808,
	August 2020, <https://www.rfc-editor.org/info/rfc8808>.		August 2020, <https://www.rfc-editor.org/info/rfc8808>.
	Appendix A. Changes between revisions		Appendix A. Backwards Compatibility
	RFC Ed.: Remove section "Changes between revisions"
	v20 - v21
	* Minor updates for IESG comments
	* Added ABNF as a normative reference for the filename's definition.
	* Enhanced security considerations
	* Added data change information to the description of the examples.
	v19 - v20
	* Minor updates for IESG comments
	v18 - v19
	* Updated leaf includes-defaults
	v17 - v18
	* Added the report-all-tagged mode to the leaf includes-defaults
	v16 - v17
	* Removed default statement from includes-default
	v15 - v16
	* Editorial changes
	v14 - v15
	* Removed reference to revision-label
	* For the inline method made the usage of ietf-yang-
	library@2019-01-04 mandatory. Simplified the case "inline" in the
	YANG module.
	* Removed the "inline-module" leaf as it does not carry useful
	information anymore.
	* Removed YANG feature
	v13 - v14
	* Added leaf includes-defaults
	* Many small changes based on AD review
	v09 - v13
	* Editorial updates
	v08 - v09
	* Removed statement "the format will be similar to the response of a
	NETCONF get operation"
	* Introduced artwork folding in the examples
	v07 - v08
	* Moved compatibility into appendix
	* Renamed yid-version to format-version. Changed format to date of
	the YANG module
	* Made support of ietf-yang-library mandatory if inline-content-
	schema is supported
	* Many small changes based on WGLC
	v06 - v07
	* Updated terminology, use-cases
	* Many small changes based on WGLC
	v05 - v06
	* Modified module name format, removed .yin or .yang extension
	* Removed pattern for module and inline-module. The usage of
	revision-label should also be allowed.
	v04 - v05
	* Updated according to YANG-Doctor review
	* Updated security considerations
	* Added a wrapping container for the schema, and renamed the data
	nodes in the inline and uri cases.
	* Allowed .yin for simplified-inline schema naming. Made date
	optional if it is unavailable in the YANG module.
	* Added a mandatory yid-version to the header metadata to allow
	later updates of the module.
	v03 - v04
	* removed entity-tag and last-modified timestamp
	* Added simplified-inline method of content-schema specification
	v02 - v03
	* target renamed to "content-schema" and "content defining YANG
	module(s)"
	* Made name of instance data set optional
	* Updated according to draft-ietf-netmod-yang-data-ext-03
	* Clarified that entity-tag and last-modified timestamp are encoded
	as metadata. While they contain useful data, the HTTP-header
	based encoding from Restconf is not suitable.
	v01 - v02
	* Removed design time from terminology
	* Defined the format of the content-data part by referencing various
	RFCs and drafts instead of the result of the get-data and get
	operations.
	* Changed target-ptr to a choice
	* Inline target-ptr may include augmenting modules and alternatives
	to ietf-yang-library
	* Moved list of target modules into a separate <target-modules>
	element.
	* Added backwards compatibility considerations
	v00 - v01
	* Added the target-ptr metadata with 3 methods
	* Added timestamp metadata
	* Removed usage of dedicated .yid file extension
	* Added list of use cases
	* Added list of principles
	* Updated examples
	* Moved detailed use case descriptions to appendix
	Appendix B. Backwards Compatibility
	The concept of backwards compatibility and what changes are backwards		The concept of "backwards compatibility" and what changes are
	compatible are not defined for "instance data sets" as it is highly		backwards compatible are not defined for instance data sets as they
	dependent on the specific use case and the content-schema.		are highly dependent on the specific use case and the content-schema.
	In case of "instance data sets" that are the result of design or		In case of "instance data sets" that are the result of design or
	specification activity, some changes that may be good to avoid are		specification activity, some changes that may be good to avoid are
	listed below.		listed below.
	YANG uses the concept of managed entities identified by key values;		YANG uses the concept of managed entities identified by key values;
	if the connection between the represented entity and the key value is		if the connection between the represented entity and the key value is
	not preserved during an update, this may lead to the following		not preserved during an update, this may lead to the following
	problems.		problems.
	* If the key value of a list entry that represents the same managed		* If the key value of a list entry that represents the same managed
	entity as before is changed, the user may mistakenly identify the		entity as before is changed, the user may mistakenly identify the
	list entry as new.		list entry as new.
	* If the meaning of a list entry is changed, but the key values are		* If the meaning of a list entry is changed but the key values are
	not (e.g., redefining an alarm-type but not changing its alarm-		not (e.g., redefining an alarm-type but not changing its alarm-
	type-id) the change may not be noticed.		type-id), the change may not be noticed.
	* If the key value of a previously removed list entry is reused for		* If the key value of a previously removed list entry is reused for
	a different entity, the change may be misinterpreted as		a different entity, the change may be misinterpreted as
	reintroducing the previous entity.		reintroducing the previous entity.
	Appendix C. Detailed Use Cases		Appendix B. Detailed Use Cases
	This section is non-normative.		This section is non-normative.
	C.1. Use Case 1: Early Documentation of Server Capabilities		B.1. Use Case 1: Early Documentation of Server Capabilities
	A server has a number of server-capabilities that are defined in YANG		A server has a number of server capabilities that are defined in YANG
	modules and can be retrieved from the server using protocols like		modules and can be retrieved from the server using protocols like
	NETCONF or RESTCONF. Server capabilities include:		NETCONF or RESTCONF. Server capabilities include:
	* data defined in "ietf-yang-library": YANG modules, submodules,		* data defined in "ietf-yang-library": YANG modules, submodules,
	features, deviations, schema-mounts, and datastores supported		features, deviations, schema-mounts, and datastores supported
	([RFC8525])		([RFC8525]).
	* alarms supported ([RFC8632])		* alarms supported ([RFC8632]).
	* data nodes and subtrees that support or do not support on-change		* data nodes and subtrees that support or do not support on-change
	notifications ([RFC8641])		notifications ([RFC8641]).
	* netconf-capabilities in ietf-netconf-monitoring.		* netconf-capabilities in ietf-netconf-monitoring.
	While it is good practice to allow a client to query these		While it is good practice to allow a client to query these
	capabilities from the live server, that is often not possible.		capabilities from the live server, that is often not possible.
	Often when a network node is released, an associated NMS (network		Often when a network node is released, an associated Network
	management system) is also released with it. The NMS depends on the		Management System (NMS) is also released with it. The NMS depends on
	capabilities of the server. During NMS implementation, information		the capabilities of the server. During NMS implementation,
	about server capabilities is needed. If the information is		information about server capabilities is needed. If the information
	unavailable early in some offline document, but only as instance data		is unavailable early in some offline document but only as instance
	from the live network node, the NMS implementation will be delayed,		data from the live network node, the NMS implementation will be
	because it has to wait until the network node is ready. Also		delayed because it has to wait until the network node is ready.
	assuming that all NMS implementors will have a correctly configured		Also, assuming that all NMS implementors will have correctly
	network nodes from which data can be retrieved, is a very expensive		configured network nodes from which data can be retrieved is a very
	proposition. (An NMS may handle dozens of node types.)		expensive proposition. (An NMS may handle dozens of node types.)
	Network operators often build their own home-grown NMS systems that		Network operators often build their own homegrown NMS systems that
	need to be integrated with a vendor's network node. The operator		need to be integrated with a vendor's network node. The operator
	needs to know the network node's server capabilities in order to do		needs to know the network node's server capabilities in order to do
	this. Moreover, the network operator's decision to buy a vendor's		this. Moreover, the network operator's decision to buy a vendor's
	product may even be influenced by the network node's OAM feature set		product may even be influenced by the network node's Operations,
	documented as the server's capabilities.		Administration, and Maintenance (OAM) feature set documented as the
			server's capabilities.
	Beside NMS implementors, system integrators and many others also need		Beside NMS implementors, system integrators and many others also need
	the same information early. Examples could be model driven testing,		the same information early. Examples could be model-driven testing,
	generating documentation, etc.		generating documentation, etc.
	Most server-capabilities are relatively stable and change only during		Most server capabilities are relatively stable and change only during
	upgrade or due to licensing or the addition or removal of hardware.		upgrade or due to licensing or the addition or removal of hardware.
	They are usually defined by a vendor at design time, before the		They are usually defined by a vendor at design time, before the
	product is released. It is feasible and advantageous to define/		product is released. It is feasible and advantageous to define and
	document them early e.g., in a YANG instance data File.		document them early, e.g., in a YANG instance data file.
	It is anticipated that a separate IETF document will define in detail		It is anticipated that a separate IETF document will define in detail
	how and which set of server capabilities should be documented.		how and which set of server capabilities should be documented.
	C.2. Use Case 2: Preloading Data		B.2. Use Case 2: Preloading Data
	There are parts of the configuration that must be fully configurable		There are parts of the configuration that must be fully configurable
	by the operator. However, often a simple default configuration will		by the operator. However, a simple default configuration often will
	be sufficient.		be sufficient.
	One example is access control groups/roles and related rules. While		One example is access control groups/roles and related rules. While
	a sophisticated operator may define dozens of different groups, often		a sophisticated operator may define dozens of different groups, often
	a basic (read-only operator, read-write system administrator,		a basic (read-only operator, read-write system administrator,
	security-administrator) triplet will be enough. Vendors will often		security-administrator) triplet will be enough. Vendors will often
	provide such default configuration data to make device configuration		provide such default configuration data to make device configuration
	easier for an operator.		easier for an operator.
	The device vendor may define a set of default groups (/nacm:nacm/		The device vendor may define a set of default groups (/nacm:nacm/
	groups) and rules for these groups to access specific parts of the		groups) and rules for these groups to access specific parts of the
	common models (/nacm:nacm/rule-list/rule).		common models (/nacm:nacm/rule-list/rule).
	YANG instance data files can be used to document and/or preload the		YANG instance data files can be used to document and/or preload the
	default configuration.		default configuration.
	C.3. Use Case 3: Documenting Factory Default Settings		B.3. Use Case 3: Documenting Factory Default Settings
	Nearly every server has a factory default configuration. If the		Nearly every server has a factory default configuration. If the
	system is really badly misconfigured or if the current configuration		system is really badly misconfigured or if the current configuration
	is to be abandoned, the system can be reset to the default factory		is to be abandoned, the system can be reset to the default factory
	configuration.		configuration.
	YANG instance data can be used to document the factory default		YANG instance data can be used to document the factory default
	configuration. See [RFC8808].		configuration. See [RFC8808].
			Acknowledgments
			For their valuable comments, discussions, and feedback, we wish to
			acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe
			Clarke, Kent Watsen, Martin Bjorklund, Ladislav Lhotka, Qin Wu, and
			other members of the Netmod Working Group.
	Authors' Addresses		Authors' Addresses
	Balazs Lengyel		Balazs Lengyel
	Ericsson		Ericsson
			Budapest
			Magyar Tudosok korutja 11
			1117
			Hungary
	Email: balazs.lengyel@ericsson.com		Email: balazs.lengyel@ericsson.com
	Benoit Claise		Benoit Claise
	Huawei		Huawei
	Email: benoit.claise@huawei.com		Email: benoit.claise@huawei.com
End of changes. 142 change blocks.
	561 lines changed or deleted		398 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/