doc: Add RFC documents

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