summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc9195.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc9195.txt')
-rw-r--r--doc/rfc/rfc9195.txt1158
1 files changed, 1158 insertions, 0 deletions
diff --git a/doc/rfc/rfc9195.txt b/doc/rfc/rfc9195.txt
new file mode 100644
index 0000000..11bbf3d
--- /dev/null
+++ b/doc/rfc/rfc9195.txt
@@ -0,0 +1,1158 @@
+
+
+
+
+Internet Engineering Task Force (IETF) B. Lengyel
+Request for Comments: 9195 Ericsson
+Category: Standards Track B. Claise
+ISSN: 2070-1721 Huawei
+ February 2022
+
+
+ A File Format for YANG Instance Data
+
+Abstract
+
+ There is a need to document data defined in YANG models at design
+ time, implementation time, or when a live server is unavailable.
+ This document specifies a standard file format for YANG instance
+ data, which follows the syntax and semantics of existing YANG models
+ and annotates it with metadata.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 7841.
+
+ 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 (c) 2022 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (https://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Revised BSD License text as described in Section 4.e of the
+ Trust Legal Provisions and are provided without warranty as described
+ in the Revised BSD License.
+
+Table of Contents
+
+ 1. Introduction
+ 1.1. Terminology
+ 1.2. Principles
+ 1.3. Delivery of Instance Data
+ 1.4. Data Life Cycle
+ 2. Instance Data File Format
+ 2.1. Specifying the Content Schema
+ 2.1.1. Inline Method
+ 2.1.2. Simplified-Inline Method
+ 2.1.3. URI Method
+ 2.2. Examples
+ 2.2.1. Documentation of Server Capabilities
+ 2.2.2. Preloading Default Configuration Data
+ 2.2.3. Storing Diagnostics Data
+ 3. YANG Instance Data Model
+ 3.1. Tree Diagram
+ 3.2. YANG Model
+ 4. Security Considerations
+ 5. IANA Considerations
+ 5.1. URI Registration
+ 5.2. YANG Module Name Registration
+ 6. References
+ 6.1. Normative References
+ 6.2. Informative References
+ Appendix A. Backwards Compatibility
+ Appendix B. Detailed Use Cases
+ B.1. Use Case 1: Early Documentation of Server Capabilities
+ B.2. Use Case 2: Preloading Data
+ B.3. Use Case 3: Documenting Factory Default Settings
+ Acknowledgments
+ Authors' Addresses
+
+1. Introduction
+
+ There is a need to document data defined in YANG models when a live
+ server is unavailable. Data is often needed at design time,
+ implementation time, or even later when a live running server is
+ unavailable. To facilitate this offline delivery of data, this
+ document specifies a standard format for YANG instance data sets and
+ YANG instance data files. The format of the instance data set is
+ defined by the "ietf-yang-instance-data" YANG module; see Section 3.
+ The YANG data model in this document conforms to the Network
+ Management Datastore Architecture (NMDA) defined in [RFC8342].
+
+ The following is a list of already-implemented and potential use
+ cases.
+
+ UC1 Documentation of server capabilities
+
+ UC2 Preloading default configuration data
+
+ UC3 Documenting factory default settings
+
+ UC4 Storing the configuration of a device, e.g., for backup,
+ archive, or audit purposes
+
+ UC5 Storing diagnostics data
+
+ UC6 Allowing YANG instance data to potentially be carried within
+ other inter-process communication (IPC) message formats
+
+ UC7 Default instance data used as part of a templating solution
+
+ UC8 Providing data examples in RFCs or internet drafts
+
+ Appendix B describes the first three use cases in detail.
+
+ There are many and varied use cases where YANG instance data could be
+ 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
+ scope for this document. It is anticipated that other documents will
+ define specific use cases. Use cases are listed only as examples.
+
+1.1. Terminology
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+ "OPTIONAL" in this document are to be interpreted as described in
+ BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
+ capitals, as shown here.
+
+ Instance Data: A collection of instantiated data nodes.
+
+ Instance Data Set: A named set of data items annotated with metadata
+ that can be used as instance data in a YANG data tree.
+
+ Instance Data File: A file containing an instance data set formatted
+ according to the rules described in this document.
+
+ Content-schema: A set of YANG modules with their revision, supported
+ features, and deviations for which the instance data set contains
+ instance data.
+
+ Content-defining YANG Module: An individual YANG module that is part
+ of the content-schema.
+
+ The term "server" is used as defined in [RFC8342].
+
+1.2. Principles
+
+ The following is a list of the basic principles of the instance data
+ format:
+
+ P1 Two standard formats shall be defined based on the XML and JSON
+ encodings.
+
+ P2 Instance data shall reuse existing encoding rules for YANG-
+ defined data.
+
+ P3 Metadata about the instance data set (Section 2, Paragraph 14)
+ shall be defined.
+
+ P4 A YANG instance data set shall be allowed to contain data for
+ multiple YANG modules.
+
+ P5 Instance data shall be allowed to contain configuration data,
+ state data, or a mix of the two.
+
+ P6 Partial data sets shall be allowed.
+
+ P7 The YANG instance data format shall be usable for any data for
+ which YANG module(s) are defined and available to the reader,
+ independent of whether the module is implemented by a server.
+
+ P8 It shall be possible to report the identity of the datastore with
+ which the instance data set is associated.
+
+1.3. Delivery of Instance Data
+
+ Instance data sets that are produced as a result of some sort of
+ 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
+ other way that product documentation is distributed.
+
+ Other instance data sets may be read from or produced by the YANG
+ server itself, e.g., UC5 documenting diagnostic data.
+
+1.4. Data Life Cycle
+
+ 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
+ represent the current data unless it is updated. The current values
+ may be retrieved at runtime via NETCONF/RESTCONF or received, e.g.,
+ in YANG-Push notifications.
+
+ Whether the instance data changes and, if so, when and how should be
+ described either in the instance data set's description statement or
+ in some other implementation-specific manner.
+
+2. Instance Data File Format
+
+ A YANG instance data file MUST contain a single instance data set and
+ no additional data.
+
+ 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
+ content-data. The header part carries metadata for the instance data
+ set. The content-data, defined as an anydata data node, carries the
+ instance data that the user wants to document and/or provide. The
+ syntax and semantics of content-data are defined by the content-
+ schema.
+
+ Two formats are specified based on the XML and JSON YANG encodings.
+ The file formats are achieved by applying the respective XML and JSON
+ encoding rules for the YANG structure included in this document.
+ Later, as other YANG encodings (e.g., CBOR) are defined, further
+ instance data formats may be specified.
+
+ The content-data part MUST conform to the content-schema while
+ allowing for the exceptions listed below. The content-data part
+ SHALL follow the encoding rules defined in [RFC7950] for XML and
+ [RFC7951] for JSON and MUST use UTF-8 character encoding. Content-
+ data MAY include:
+
+ * metadata, as defined by [RFC7952].
+
+ * origin metadata, as specified in [RFC8526] and [RFC8527].
+
+ * implementation-specific metadata relevant to individual data
+ nodes. Unknown metadata MUST be ignored by users of instance
+ data, allowing it to be used later for other purposes.
+
+ 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
+ a server. Default values should be excluded where they do not
+ provide additional useful data.
+
+ Configuration ("config true") and operational state data ("config
+ false") MAY be mixed in the instance data file.
+
+ Instance data files MAY contain partial data sets. This means
+ "mandatory", "min-elements", "require-instance true", "must", and
+ "when" constraints MAY be violated.
+
+ The name of the instance data file SHOULD be of the following form
+ (using ABNF notation [RFC5234]):
+
+ instance-data-set-name ["@" ( revision-date / timestamp ) ]
+ ( ".xml" / ".json" )
+
+ Examples include:
+
+ 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
+ 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 format of the revision-date leaf in the YANG model. If the
+ "revision-date" is present in both the filename and the instance data
+ header, the revision date in the filename MUST be set to the latest
+ revision date inside the instance data set. If the "timestamp" is
+ present in the filename, it MUST conform to the format of the
+ timestamp leaf in the YANG model except for replacing colons as
+ described below. If the "timestamp" is present in both the filename
+ and the instance data header, the timestamp in the filename SHOULD be
+ set to the timestamp inside the instance data set; any colons, if
+ present, shall be replaced by underscores.
+
+ Metadata, information about the data set itself, MUST be included.
+ Some metadata items are defined in the YANG module "ietf-yang-
+ instance-data", but other items MAY be used.
+
+ Metadata MUST include:
+
+ - Version of the YANG instance data format (if not explicitly
+ present, the default value is used).
+
+ Metadata SHOULD include:
+
+ - Name of the data set.
+
+ - Content-schema specification (i.e., the "content-schema" node).
+
+ - Description of the instance data set. The description SHOULD
+ contain information on whether and how the data can change
+ during the lifetime of the server.
+
+ - An indication of whether default values are included. The
+ default handling uses the concepts defined in [RFC6243];
+ however, as only concepts are re-used, users of instance data
+ sets do not need to support [RFC6243].
+
+2.1. Specifying the Content Schema
+
+ To properly understand and use an instance data set, the user needs
+ to know the content-schema. The content-schema can be specified
+ either in external documents or within the instance data set. In the
+ latter case, one of the following methods MUST be used:
+
+ Inline method: Include the needed information as part of the
+ instance data set.
+
+ Simplified-inline method: Include the needed information as part of
+ the instance data set; only the modules' name and revision-date
+ are used.
+
+ URI method: Include a URI that references another YANG instance data
+ file. This instance data file will use the same content-schema as
+ the referenced YANG instance data file (if you don't want to
+ repeat the info again and again).
+
+ Additional methods, e.g., a YANG-package-based solution may be added
+ later.
+
+ Note that the specified content-schema only indicates the set of
+ modules that were used to define this YANG instance data set.
+ Sometimes instance data may be used for a server supporting a
+ different YANG module set (e.g., for the "Preloading default
+ configuration data" use case, UC2 in Section 1, the instance data set
+ may not be updated every time the YANG modules on the server are
+ updated). Whether an instance data set originally defined using a
+ specific content-schema is usable with another schema depends on many
+ factors, including the number of differences and the compatibility
+ between the original and the other schema when considering modules,
+ revisions, features, deviations, the scope of the instance data, etc.
+
+2.1.1. Inline Method
+
+ The "inline-yang-library" anydata data node carries instance data
+ (conforming to "ietf-yang-library@2019-01-04") [RFC8525] that
+ specifies the content-defining YANG modules, including revision,
+ supported features, deviations, and any additional relevant data. An
+ example of the inline method is provided in Section 2.2.1.
+
+2.1.2. Simplified-Inline Method
+
+ The instance data set contains a list of content-defining YANG
+ modules, including the revision date for each. Usage of this method
+ implies that the modules are used without any deviations and with all
+ features supported. YANG modules that are only required to satisfy
+ 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
+ the YANG language rules to resolve the imports. An example of the
+ simplified-inline method is provided in Section 2.2.2.
+
+2.1.3. URI Method
+
+ The "same-schema-as-file" leaf SHALL contain a URI that references
+ another YANG instance data file. The current instance data file will
+ use the same content-schema as the referenced file.
+
+ The referenced instance data file MAY have no content-data if it is
+ used solely for specifying the content-schema.
+
+ If a referenced instance data file is unavailable, the content-schema
+ is unknown.
+
+ The URI method is advantageous when the user wants to avoid the
+ overhead of specifying the content-schema in each instance data file
+ -- for example, in UC6, when the system creates a diagnostic file
+ every minute to document the state of the server.
+
+ An example of the URI method is provided in Section 2.2.3.
+
+2.2. Examples
+
+2.2.1. Documentation of Server Capabilities
+
+ 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
+ capabilities for a server. It uses the inline method to specify the
+ content-schema.
+
+ The example uses artwork folding [RFC8792].
+
+ ========== NOTE: '\' line wrapping per RFC 8792 ===========
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <instance-data-set xmlns=\
+ "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data">
+ <name>acme-router-modules</name>
+ <content-schema>
+ <inline-yang-library>
+ <modules-state \
+ xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
+ <module>
+ <name>ietf-yang-library</name>
+ <revision>2019-01-04</revision>
+ </module>
+ <module>
+ <name>ietf-netconf-monitoring</name>
+ <revision>2010-10-04</revision>
+ </module>
+ </modules-state>
+ </inline-yang-library>
+ </content-schema>
+ <revision>
+ <date>2020-10-23</date>
+ <description>Initial version</description>
+ </revision>
+ <description>Defines the minimal set of modules that any \
+ acme-router will contain. This minimal set will \
+ only change when a new software release is \
+ introduced.</description>
+ <contact>info@acme.example.com</contact>
+ <content-data>
+ <modules-state \
+ xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
+ <module>
+ <name>ietf-yang-library</name>
+ <revision>2019-01-04</revision>
+ <namespace>\
+ urn:ietf:params:xml:ns:yang:ietf-yang-library\
+ </namespace>
+ <conformance-type>implement</conformance-type>
+ </module>
+ <module>
+ <name>ietf-system</name>
+ <revision>2014-08-06</revision>
+ <namespace>urn:ietf:params:xml:ns:yang:ietf-system</namespace>
+ <feature>sys:authentication</feature>
+ <feature>sys:local-users</feature>
+ <deviation>
+ <name>acme-system-ext</name>
+ <revision>2018-08-06</revision>
+ </deviation>
+ <conformance-type>implement</conformance-type>
+ </module>
+ <module>
+ <name>ietf-netconf-monitoring</name>
+ <revision>2010-10-04</revision>
+ <namespace>\
+ urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring\
+ </namespace>
+ <conformance-type>implement</conformance-type>
+ </module>
+ <module>
+ <name>ietf-yang-types</name>
+ <revision>2013-07-15</revision>
+ <namespace>urn:ietf:params:xml:ns:yang:ietf-yang-types\
+ </namespace>
+ <conformance-type>import</conformance-type>
+ </module>
+ <module>
+ <name>acme-system-ext</name>
+ <revision>2018-08-06</revision>
+ <namespace>\
+ urn:rdns:acme.example.com:oammodel:acme-system-ext\
+ </namespace>
+ <conformance-type>implement</conformance-type>
+ </module>
+ </modules-state>
+ <netconf-state \
+ xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
+ <capabilities>
+ <capability>\
+ urn:ietf:params:netconf:capability:validate:1.1\
+ </capability>
+ </capabilities>
+ </netconf-state>
+ </content-data>
+ </instance-data-set>
+
+ Figure 1
+
+2.2.2. Preloading Default Configuration Data
+
+ 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
+ role. It uses the simplified-inline method for specifying the
+ content-schema.
+
+ ========== NOTE: '\' line wrapping per RFC 8792 ===========
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <instance-data-set
+ xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-instance-data">
+ <name>read-only-acm-rules</name>
+ <content-schema>
+ <module>ietf-netconf-acm@2018-02-14</module>
+ </content-schema>
+ <revision>
+ <date>2018-07-04</date>
+ <description>Initial version</description>
+ </revision>
+ <description>Default access control rules for a read-only \
+ role. This set of rules will only change when a new \
+ software release is introduced.</description>
+ <content-data>
+ <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
+ <enable-nacm>true</enable-nacm>
+ <read-default>deny</read-default>
+ <exec-default>deny</exec-default>
+ <rule-list>
+ <name>read-only-role</name>
+ <group>read-only-group</group>
+ <rule>
+ <name>read-all</name>
+ <module-name>*</module-name>
+ <access-operation>read</access-operation>
+ <action>permit</action>
+ </rule>
+ </rule-list>
+ </nacm>
+ </content-data>
+ </instance-data-set>
+
+ Figure 2
+
+2.2.3. Storing Diagnostics Data
+
+ The example file acme-router-netconf-
+ diagnostics@2018-01-25T17_00_38Z.json reflects UC5 in Section 1. An
+ instance data set that contains statistics about the NETCONF server
+ is produced by the server every 15 minutes. As a new set is produced
+ periodically many times a day, a revision-date would be useless;
+ instead, a timestamp is included.
+
+ ========== NOTE: '\' line wrapping per RFC 8792 ===========
+
+ {
+ "ietf-yang-instance-data:instance-data-set": {
+ "name": "acme-router-netconf-diagnostics",
+ "content-schema": {
+ "same-schema-as-file": "file:///acme-diagnostics-schema.json"
+ },
+ "timestamp": "2018-01-25T17:00:38Z",
+ "description": ["NETCONF statistics, \
+ The data may change at any time."],
+ "content-data": {
+ "ietf-netconf-monitoring:netconf-state": {
+ "statistics": {
+ "netconf-start-time ": "2018-12-05T17:45:00Z",
+ "in-bad-hellos ": "32",
+ "in-sessions ": "397",
+ "dropped-sessions ": "87",
+ "in-rpcs ": "8711",
+ "in-bad-rpcs ": "408",
+ "out-rpc-errors ": "408",
+ "out-notifications": "39007"
+ }
+ }
+ }
+ }
+ }
+
+ Figure 3
+
+3. YANG Instance Data Model
+
+3.1. Tree Diagram
+
+ The following tree diagram [RFC8340] provides an overview of the data
+ model.
+
+ module: ietf-yang-instance-data
+ structure instance-data-set:
+ +--name? string
+ +--format-version? string
+ +--includes-defaults? enumeration
+ +--content-schema
+ | +--(content-schema-spec)?
+ | +--:(simplified-inline)
+ | | +--module* module-with-revision-date
+ | +--:(inline)
+ | | +--inline-yang-library <anydata>
+ | +--:(uri)
+ | +--same-schema-as-file? inet:uri
+ +--description* string
+ +--contact? string
+ +--organization? string
+ +--datastore? ds:datastore-ref
+ +--revision* [date]
+ | +--date string
+ | +--description? string
+ +--timestamp? yang:date-and-time
+ +--content-data? <anydata>
+
+3.2. YANG Model
+
+ This YANG module imports typedefs from [RFC6991], [RFC6243],
+ identities from [RFC8342], and the "structure" extension from
+ [RFC8791]. It also references [RFC8525].
+
+ <CODE BEGINS> file "ietf-yang-instance-data@2022-02-17.yang"
+ module ietf-yang-instance-data {
+ yang-version 1.1;
+ namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data";
+ prefix yid;
+
+ import ietf-yang-structure-ext {
+ prefix sx;
+ reference
+ "RFC 8791: YANG Data Structure Extensions";
+ }
+ import ietf-datastores {
+ prefix ds;
+ reference
+ "RFC 8342: Network Management Datastore Architecture (NMDA)";
+ }
+ import ietf-inet-types {
+ prefix inet;
+ reference
+ "RFC 6991: Common YANG Data Types";
+ }
+ import ietf-yang-types {
+ prefix yang;
+ reference
+ "RFC 6991: Common YANG Data Types";
+ }
+ import ietf-netconf-with-defaults {
+ prefix ncwd;
+ reference
+ "RFC 6243: With-defaults Capability for NETCONF";
+ }
+
+ organization
+ "IETF NETMOD Working Group";
+ contact
+ "WG Web: <https://datatracker.ietf.org/wg/netmod/>
+ WG List: <mailto:netmod@ietf.org>
+
+ Author: Balazs Lengyel
+ <mailto:balazs.lengyel@ericsson.com>
+
+ Author: Benoit Claise
+ <mailto:benoit.claise@huawei.com>";
+ description
+ "The module defines the structure and content of YANG
+ instance data sets.
+
+ The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
+ 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
+ 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
+ are to be interpreted as described in BCP 14 (RFC 2119)
+ (RFC 8174) when, and only when, they appear in all
+ capitals, as shown here.
+
+ Copyright (c) 2022 IETF Trust and the persons identified as
+ authors of the code. All rights reserved.
+
+ Redistribution and use in source and binary forms, with or
+ without modification, is permitted pursuant to, and subject
+ to the license terms contained in, the Revised BSD License
+ set forth in Section 4.c of the IETF Trust's
+ Legal Provisions Relating to IETF Documents
+ (https://trustee.ietf.org/license-info).
+
+ This version of this YANG module is part of RFC 9195
+ (https://www.rfc-editor.org/info/rfc9195); see the RFC itself
+ for full legal notices.";
+
+ revision 2022-02-17 {
+ description
+ "Initial revision.";
+ reference
+ "RFC 9195: YANG Instance Data File Format";
+ }
+
+ typedef module-with-revision-date {
+ type string {
+ 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]))?';
+ pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*';
+ }
+ description
+ "A type defining a module name and an optional revision
+ date, e.g., ietf-yang-library@2019-01-04.";
+ }
+
+ sx:structure instance-data-set {
+ description
+ "A data structure to define a format for YANG instance
+ data. The majority of the YANG nodes provides metadata
+ about the instance data; the instance data itself is
+ contained only in the 'content-data' node.";
+ leaf name {
+ type string;
+ description
+ "An arbitrary name for the YANG instance data set. This
+ value is primarily used for descriptive purposes. However,
+ when the instance data set is saved to a file, then the
+ filename MUST encode the name's value per Section 2
+ of RFC 9195.";
+ }
+ leaf format-version {
+ type string {
+ pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
+ }
+ default "2022-01-20";
+ description
+ "The 'revision' of the 'ietf-yang-instance-data' module
+ used to encode this 'instance-data-set'.";
+ }
+ leaf includes-defaults {
+ type ncwd:with-defaults-mode;
+ default "report-all";
+ description
+ "Indicates how data nodes with default values are
+ represented for all data nodes contained in the
+ instance-data-set.
+
+ It uses the same definitions as per Section 3 of RFC 6243
+ but applied in the context of an instance data file rather
+ than a NETCONF request using the <with-defaults>
+ parameter.
+
+ For JSON files, the encoding of the 'report-all-tagged'
+ option is as defined in Section 4.8.9 of RFC 8040.";
+ reference
+ "RFC 6243: With-defaults Capability for NETCONF";
+ }
+ container content-schema {
+ description
+ "The content schema (i.e., YANG modules) used to create
+ the instance data set.
+ If not present, the user needs to obtain the information
+ through external documents.";
+ choice content-schema-spec {
+ description
+ "Specification of the content-schema.";
+ case simplified-inline {
+ leaf-list module {
+ type module-with-revision-date;
+ min-elements 1;
+ description
+ "The list of content-defining YANG modules.
+
+ The value SHALL start with the module name.
+ If the module contains a revision statement, the
+ revision date SHALL be included in the leaf-list
+ entry, e.g., ietf-yang-library@2019-01-04.
+
+ Usage of this leaf-list implies the modules are
+ used without any deviations and with all features
+ supported. Multiple revisions of the same module
+ MUST NOT be specified.";
+ }
+ }
+ case inline {
+ anydata inline-yang-library {
+ mandatory true;
+ description
+ "Instance data corresponding to the
+ ietf-yang-library@2019-01-04 defining
+ the set of content-defining YANG modules for
+ this instance-data-set.";
+ }
+ }
+ case uri {
+ leaf same-schema-as-file {
+ type inet:uri;
+ description
+ "A reference to another YANG instance data file.
+ This instance data file uses the same
+ content schema as the referenced file.
+
+ Referenced files using the 'inline' or the
+ 'simplified-inline' methods MUST be supported.
+ Referenced files using the 'URI method' MAY be
+ supported.
+
+ The URL schemes 'file://' and 'https://' MUST
+ be supported; other schemes MAY also be
+ supported.";
+ }
+ }
+ }
+ }
+ leaf-list description {
+ type string;
+ description
+ "Description of the instance data set.";
+ }
+ leaf contact {
+ type string;
+ description
+ "Contact information for the person or
+ organization to whom queries concerning this
+ instance data set should be sent.";
+ }
+ leaf organization {
+ type string;
+ description
+ "Organization responsible for the instance
+ data set.";
+ }
+ leaf datastore {
+ type ds:datastore-ref;
+ description
+ "The identity of the datastore with which the
+ instance data set is associated, e.g., the datastore from
+ where the data was read, the datastore into which the data
+ may be loaded, or the datastore that is being documented.
+ If a single specific datastore cannot be specified, the
+ leaf MUST be absent.
+
+ If this leaf is absent, then the datastore to which the
+ instance data belongs is unspecified.";
+ }
+ list revision {
+ key "date";
+ description
+ "Instance data sets that are produced as
+ a result of some sort of specification or design effort
+ SHOULD have at least one revision entry. For every
+ published editorial change, a new unique revision SHOULD
+ be added in front of the revisions sequence so that all
+ revisions are in reverse chronological order.
+
+ In cases of instance data sets that are read from
+ or produced by a server or otherwise subject to
+ frequent updates or changes, revision
+ SHOULD NOT be present.";
+ leaf date {
+ type string {
+ pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
+ }
+ description
+ "Specifies the date the instance data set
+ was last modified. Formatted as YYYY-MM-DD.";
+ }
+ leaf description {
+ type string;
+ description
+ "Description of this revision of the instance data set.";
+ }
+ }
+ leaf timestamp {
+ type yang:date-and-time;
+ description
+ "The date and time when the instance data set
+ was last modified.
+
+ In cases of instance data sets that are read from or
+ produced by a server or otherwise subject to frequent
+ updates or changes, the timestamp SHOULD be present.
+
+ If both a revision list entry and timestamp are present,
+ the timestamp SHOULD contain the same date as the
+ latest revision statement.";
+ }
+ anydata content-data {
+ description
+ "Contains the real instance data.
+ The data MUST conform to the relevant YANG modules
+ specified either in the content-schema or in some other
+ implementation-specific manner.";
+ }
+ }
+ }
+ <CODE ENDS>
+
+4. Security Considerations
+
+ The YANG module defined in this document only defines a wrapper
+ structure specifying a format and a metadata header for YANG instance
+ data defined by the content-schema. Because of this, the security
+ 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
+ stored file or over any file access method or protocol.
+
+ The document does not specify any method to influence the behavior of
+ a server.
+
+ The header part is usually not security sensitive; however, sensitive
+ information may be included, in which case it needs to be handled
+ securely, as mentioned below. Information to consider includes:
+
+ * If the URI method is used for specification of the content-schema
+ and the URI includes a userinfo subcomponent
+
+ * Any description text
+
+ The content part may contain sensitive data. The security
+ sensitivity of this data is completely dependent on the content-
+ schema. Depending on the nature of the instance data, instance data
+ 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
+ needed for the result of a read operation returning the same data.
+ These in-transit protection mechanisms will also mitigate integrity
+ issues when transporting the file.
+
+ Instance data files should be protected against modification or
+ unauthorized access using normal file-handling mechanisms. When
+ copying the original files or providing file access for additional
+ users, care should be taken not to reveal information
+ unintentionally.
+
+ 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
+ instance data file may be altered maliciously or even as part of its
+ normal handling. In this case, the content-schema might differ from
+ the one expected. Protecting the integrity and stability of the
+ referenced file should be ensured.
+
+5. IANA Considerations
+
+ This document registers one URI and one YANG module.
+
+5.1. URI Registration
+
+ This document registers the following URI in the "IETF XML Registry"
+ [RFC3688]:
+
+ URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data
+ Registrant Contact: The IESG.
+ XML: N/A, the requested URI is an XML namespace.
+
+5.2. YANG Module Name Registration
+
+ This document registers the following YANG module in the "YANG Module
+ Names" registry [RFC6020]:
+
+ Name: ietf-yang-instance-data
+ Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data
+ Prefix: yid
+ Reference: RFC 9195
+
+6. References
+
+6.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <https://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234,
+ DOI 10.17487/RFC5234, January 2008,
+ <https://www.rfc-editor.org/info/rfc5234>.
+
+ [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
+ the Network Configuration Protocol (NETCONF)", RFC 6020,
+ DOI 10.17487/RFC6020, October 2010,
+ <https://www.rfc-editor.org/info/rfc6020>.
+
+ [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for
+ NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011,
+ <https://www.rfc-editor.org/info/rfc6243>.
+
+ [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
+ RFC 6991, DOI 10.17487/RFC6991, July 2013,
+ <https://www.rfc-editor.org/info/rfc6991>.
+
+ [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
+ RFC 7950, DOI 10.17487/RFC7950, August 2016,
+ <https://www.rfc-editor.org/info/rfc7950>.
+
+ [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
+ RFC 7951, DOI 10.17487/RFC7951, August 2016,
+ <https://www.rfc-editor.org/info/rfc7951>.
+
+ [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG",
+ RFC 7952, DOI 10.17487/RFC7952, August 2016,
+ <https://www.rfc-editor.org/info/rfc7952>.
+
+ [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+ 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+ May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
+ [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
+ and R. Wilton, "Network Management Datastore Architecture
+ (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
+ <https://www.rfc-editor.org/info/rfc8342>.
+
+ [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
+ and R. Wilton, "YANG Library", RFC 8525,
+ DOI 10.17487/RFC8525, March 2019,
+ <https://www.rfc-editor.org/info/rfc8525>.
+
+ [RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
+ and R. Wilton, "NETCONF Extensions to Support the Network
+ Management Datastore Architecture", RFC 8526,
+ DOI 10.17487/RFC8526, March 2019,
+ <https://www.rfc-editor.org/info/rfc8526>.
+
+ [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
+ and R. Wilton, "RESTCONF Extensions to Support the Network
+ Management Datastore Architecture", RFC 8527,
+ DOI 10.17487/RFC8527, March 2019,
+ <https://www.rfc-editor.org/info/rfc8527>.
+
+ [RFC8791] Bierman, A., Björklund, M., and K. Watsen, "YANG Data
+ Structure Extensions", RFC 8791, DOI 10.17487/RFC8791,
+ June 2020, <https://www.rfc-editor.org/info/rfc8791>.
+
+6.2. Informative References
+
+ [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
+ DOI 10.17487/RFC3688, January 2004,
+ <https://www.rfc-editor.org/info/rfc3688>.
+
+ [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
+ BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
+ <https://www.rfc-editor.org/info/rfc8340>.
+
+ [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of
+ Documents Containing YANG Data Models", BCP 216, RFC 8407,
+ DOI 10.17487/RFC8407, October 2018,
+ <https://www.rfc-editor.org/info/rfc8407>.
+
+ [RFC8632] Vallin, S. and M. Bjorklund, "A YANG Data Model for Alarm
+ Management", RFC 8632, DOI 10.17487/RFC8632, September
+ 2019, <https://www.rfc-editor.org/info/rfc8632>.
+
+ [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications
+ for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641,
+ September 2019, <https://www.rfc-editor.org/info/rfc8641>.
+
+ [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
+ "Handling Long Lines in Content of Internet-Drafts and
+ RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
+ <https://www.rfc-editor.org/info/rfc8792>.
+
+ [RFC8808] Wu, Q., Lengyel, B., and Y. Niu, "A YANG Data Model for
+ Factory Default Settings", RFC 8808, DOI 10.17487/RFC8808,
+ August 2020, <https://www.rfc-editor.org/info/rfc8808>.
+
+Appendix A. Backwards Compatibility
+
+ The concept of "backwards compatibility" and what changes are
+ backwards compatible are not defined for instance data sets as they
+ 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
+ specification activity, some changes that may be good to avoid are
+ listed below.
+
+ YANG uses the concept of managed entities identified by key values;
+ if the connection between the represented entity and the key value is
+ not preserved during an update, this may lead to the following
+ problems.
+
+ * If the key value of a list entry that represents the same managed
+ entity as before is changed, the user may mistakenly identify the
+ list entry as new.
+
+ * 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-
+ type-id), the change may not be noticed.
+
+ * If the key value of a previously removed list entry is reused for
+ a different entity, the change may be misinterpreted as
+ reintroducing the previous entity.
+
+Appendix B. Detailed Use Cases
+
+ This section is non-normative.
+
+B.1. Use Case 1: Early Documentation of Server Capabilities
+
+ A server has a number of server capabilities that are defined in YANG
+ modules and can be retrieved from the server using protocols like
+ NETCONF or RESTCONF. Server capabilities include:
+
+ * data defined in "ietf-yang-library": YANG modules, submodules,
+ features, deviations, schema-mounts, and datastores supported
+ ([RFC8525]).
+
+ * alarms supported ([RFC8632]).
+
+ * data nodes and subtrees that support or do not support on-change
+ notifications ([RFC8641]).
+
+ * netconf-capabilities in ietf-netconf-monitoring.
+
+ While it is good practice to allow a client to query these
+ capabilities from the live server, that is often not possible.
+
+ Often when a network node is released, an associated Network
+ Management System (NMS) is also released with it. The NMS depends on
+ the capabilities of the server. During NMS implementation,
+ information about server capabilities is needed. If the information
+ is unavailable early in some offline document but only as instance
+ data from the live network node, the NMS implementation will be
+ delayed because it has to wait until the network node is ready.
+ Also, assuming that all NMS implementors will have correctly
+ configured network nodes from which data can be retrieved is a very
+ expensive proposition. (An NMS may handle dozens of node types.)
+
+ Network operators often build their own homegrown NMS systems that
+ 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
+ this. Moreover, the network operator's decision to buy a vendor's
+ product may even be influenced by the network node's Operations,
+ Administration, and Maintenance (OAM) feature set documented as the
+ server's capabilities.
+
+ Beside NMS implementors, system integrators and many others also need
+ the same information early. Examples could be model-driven testing,
+ generating documentation, etc.
+
+ Most server capabilities are relatively stable and change only during
+ upgrade or due to licensing or the addition or removal of hardware.
+ They are usually defined by a vendor at design time, before the
+ product is released. It is feasible and advantageous to define and
+ document them early, e.g., in a YANG instance data file.
+
+ It is anticipated that a separate IETF document will define in detail
+ how and which set of server capabilities should be documented.
+
+B.2. Use Case 2: Preloading Data
+
+ There are parts of the configuration that must be fully configurable
+ by the operator. However, a simple default configuration often will
+ be sufficient.
+
+ One example is access control groups/roles and related rules. While
+ a sophisticated operator may define dozens of different groups, often
+ a basic (read-only operator, read-write system administrator,
+ security-administrator) triplet will be enough. Vendors will often
+ provide such default configuration data to make device configuration
+ easier for an operator.
+
+ The device vendor may define a set of default groups (/nacm:nacm/
+ groups) and rules for these groups to access specific parts of the
+ common models (/nacm:nacm/rule-list/rule).
+
+ YANG instance data files can be used to document and/or preload the
+ default configuration.
+
+B.3. Use Case 3: Documenting Factory Default Settings
+
+ Nearly every server has a factory default configuration. If the
+ system is really badly misconfigured or if the current configuration
+ is to be abandoned, the system can be reset to the default factory
+ configuration.
+
+ YANG instance data can be used to document the factory default
+ 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
+
+ Balazs Lengyel
+ Ericsson
+ Budapest
+ Magyar Tudosok korutja 11
+ 1117
+ Hungary
+ Email: balazs.lengyel@ericsson.com
+
+
+ Benoit Claise
+ Huawei
+ Email: benoit.claise@huawei.com