--- 1/draft-ietf-netmod-yang-instance-file-format-03.txt 2019-08-12 05:16:08.183043993 -0700 +++ 2/draft-ietf-netmod-yang-instance-file-format-04.txt 2019-08-12 05:16:08.227045103 -0700 @@ -1,19 +1,19 @@ Netmod B. Lengyel Internet-Draft Ericsson Intended status: Standards Track B. Claise -Expires: January 6, 2020 Cisco Systems, Inc. - July 5, 2019 +Expires: February 13, 2020 Cisco Systems, Inc. + August 12, 2019 YANG Instance Data File Format - draft-ietf-netmod-yang-instance-file-format-03 + draft-ietf-netmod-yang-instance-file-format-04 Abstract There is a need to document data defined in YANG models when a live server is not available. Data is often needed already at design or implementation time or needed by groups that do not have a live running server available. This document specifies a standard file format for YANG instance data (which follows the syntax and semantic from existing YANG models, re-using the same format as the reply to a operation/request) and decorates it with metadata. @@ -26,21 +26,21 @@ 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 and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on January 6, 2020. + This Internet-Draft will expire on February 13, 2020. Copyright Notice Copyright (c) 2019 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 @@ -50,43 +50,44 @@ the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 4 3. Instance Data File Format . . . . . . . . . . . . . . . . . . 4 3.1. Specifying the Content Schema . . . . . . . . . . . . . . 6 - 3.1.1. INLINE Method . . . . . . . . . . . . . . . . . . . . 7 - 3.1.2. URI Method . . . . . . . . . . . . . . . . . . . . . 7 + 3.1.1. Inline Method . . . . . . . . . . . . . . . . . . . . 7 + 3.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 7 + 3.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 7 3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 - 4. Data Life cycle . . . . . . . . . . . . . . . . . . . . . . . 11 - 5. Delivery of Instance Data . . . . . . . . . . . . . . . . . . 12 - 6. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 12 - 7. Yang Instance Data Model . . . . . . . . . . . . . . . . . . 12 - 7.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 12 - 7.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 13 - 8. Security Considerations . . . . . . . . . . . . . . . . . . . 17 + 4. Data Life cycle . . . . . . . . . . . . . . . . . . . . . . . 12 + 5. Delivery of Instance Data . . . . . . . . . . . . . . . . . . 13 + 6. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 13 + 7. Yang Instance Data Model . . . . . . . . . . . . . . . . . . 13 + 7.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 13 + 7.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 14 + 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 - 9.1. URI Registration . . . . . . . . . . . . . . . . . . . . 18 - 9.2. YANG Module Name Registration . . . . . . . . . . . . . . 18 - 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 - 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 - 11.1. Normative References . . . . . . . . . . . . . . . . . . 18 + 9.1. URI Registration . . . . . . . . . . . . . . . . . . . . 19 + 9.2. YANG Module Name Registration . . . . . . . . . . . . . . 19 + 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 + 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 11.1. Normative References . . . . . . . . . . . . . . . . . . 19 11.2. Informative References . . . . . . . . . . . . . . . . . 20 - Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 20 - Appendix B. Changes between revisions . . . . . . . . . . . . . 20 - Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 23 - C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 23 + Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 21 + Appendix B. Changes between revisions . . . . . . . . . . . . . 21 + Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 22 + C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 22 C.1.1. Use Case 1: Early Documentation of Server - Capabilities . . . . . . . . . . . . . . . . . . . . 23 + Capabilities . . . . . . . . . . . . . . . . . . . . 22 C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 24 C.1.3. Use Case 3: Documenting Factory Default Settings . . 24 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 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 RFC 2119 [RFC2119] RFC 8174 [RFC8174] when, and only when, they @@ -189,23 +190,20 @@ Two formats are specified based on the XML and JSON YANG encodings. Later as other YANG encodings (e.g. CBOR) are defined further instance data formats may be specified. 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]. - entity-tags and timestamps as defined in [RFC8040] encoded - according to [RFC7952] - a default attribute as defined in [RFC6243] section 6. and in [RFC8040] section 4.8.9. origin metadata as specified in [RFC8526] and [RFC8527] implementation specific metadata. Unknown metadata MUST be ignored by users of YANG instance data, allowing it to be used later for other purposes. in the XML format implementation specific XML attributes. Unknown @@ -265,28 +263,30 @@ o Description of the instance data set. The description SHOULD contain information whether and how the data can change during the lifetime of the server. 3.1. Specifying the Content Schema To properly understand and use an instance data set the user needs to know the content-schema. One of the following methods SHOULD be used: - INLINE method: Include the needed information as part of instance - data set. + 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; short specification. 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) - EXTERNAL Method: Do not include the content-schema as it is already known, or the information is available through external documents. Additional methods e.g. a YANG-package based solution may be added later. Note, 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 @@ -291,33 +291,40 @@ 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 "UC2 Preloading Data" the instance data set may not be updated every time the YANG modules on the server are updated) Whether the instance data set is usable for a possibly different real-life YANG module set depends on many factors including the compatibility between the specified and the real-life YANG module set (considering modules, revisions, features, deviations), the scope of the instance data, etc. -3.1.1. INLINE Method +3.1.1. Inline Method One or more inline-target-spec elements define YANG module(s) used to specify the content defining YANG modules. E.g. ietf-yang-library@2016-06-21.yang The anydata inline-content-schema carries instance data (conforming to the inline-target-spec modules) that actually specifies the content defining YANG modules including revision, supported features, deviations and any relevant additional data (e.g. version labels) -3.1.2. URI Method +3.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. + +3.1.3. URI Method A schema-uri 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. The referenced YANG instance data file might use the INLINE method or might use the URI method to reference further instance data file(s). However at the end of this reference chain there MUST be an instance data file using @@ -420,21 +426,21 @@ The following example is based on "UC2, Preloading Default Configuration". It provides a (shortened) default rule set for a read-only operator role. It uses the inline method for specifying the content-schema. read-only-acm-rules - ietf-yang-library@2019-01-04.yang + ietf-yang-library@2019-01-04.yang all ietf-netconf-acm 2012-02-22 @@ -554,20 +560,22 @@ 7.1. Tree Diagram The following tree diagram [RFC8340] provides an overview of the data model. module: ietf-yang-instance-data structure instance-data-set: +--rw name? string +--rw (content-schema-spec)? + | +--:(simplified-inline) + | +--rw module* string | +--:(inline) | | +--rw inline-spec* string | | +--rw inline-content-schema | +--:(uri) | +--rw schema-uri? inet:uri +--rw description? string +--rw contact? string +--rw organization? string +--rw datastore? ds:datastore-ref +--rw revision* [date] @@ -620,47 +628,46 @@ (http://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX; see the RFC itself for full legal notices."; revision 2019-07-04 { description "Initial revision."; reference "RFC XXXX: YANG Instance Data Format"; } - md:annotation entity-tag { - type string; - description "Used to encode the entity-tag defined in - RFC8040 for the annotated instance."; - reference "RESTCONF Protocol RFC8040"; - } - - md:annotation last-modified { - type yang:date-and-time; - description "Contains the date and time when the annotated - instance was last modified (or created)."; - reference "RESTCONF Protocol RFC8040"; - } - sx:structure instance-data-set { description "A data structure to define a format for a YANG instance data set.Consists of meta-data about the instance data set and the real content-data."; leaf name { type string; description "Name of the YANG instance data set."; } choice content-schema-spec { description "Specification of the content-schema"; + case simplified-inline { + leaf-list module { + type string { + pattern '.+@\d{4}-\d{2}-\d{2}\.yang'; + } + description "The list of content defining YANG + modules including the revision date for each. + Usage of this leaf-list implies the modules are + used without any deviations and with all features + supported."; + } + + } case inline { leaf-list inline-spec { type string { pattern '.+@\d{4}-\d{2}-\d{2}\.yang'; } min-elements 1; ordered-by user; description "Indicates that content defining Yang modules are specified inline. @@ -824,22 +832,22 @@ acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe Clarke, Kent Watsen Martin Bjorklund, Ladislav Lhotka, Qin Wu and other members of the Netmod WG. 11. References 11.1. Normative References [I-D.ietf-netmod-yang-data-ext] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data - Structure Extensions", draft-ietf-netmod-yang-data-ext-03 - (work in progress), April 2019. + Structure Extensions", draft-ietf-netmod-yang-data-ext-04 + (work in progress), July 2019. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . @@ -913,35 +921,39 @@ [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . Appendix A. Open Issues o - Appendix B. Changes between revisions + v03 - v04 + + o removed entity-tag and last-modified timestamp + + o Added simplified-inline method of content-schema specification + v02 - v03 o target renamed to "content-schema" and "content defining Yang module(s)" o Made name of instance data set optional - o Updated according to draft-ietf-netmod-tang-data-ext-02 + o Updated according to draft-ietf-netmod-yang-data-ext-03 o Clarified that entity-tag and last-modified timestamp are encoded - as metadata. While htey contain useful data, the HTTP-header + as metadata. While they contain useful data, the HTTP-header based encoding from Restconf is not suitable. - o - v01 - v02 o Removed design time from terminology o 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. o Changed target-ptr to a choice @@ -962,76 +974,20 @@ o Removed usage of dedicated .yid file extension o Added list of use cases o Added list of principles o Updated examples o Moved detailed use case descriptions to appendix - v05 - v00-netmod - - o New name for the draft following Netmod workgroup adoption. No - other changes - - v04 - v05 - - o Changed title and introduction to clarify that this draft is only - about the file format and documenting server capabilities is just - a use case. - - o Added reference to draft-wu-netconf-restconf-factory-restore - o Added new open issues. - - v03 - v04 - - o Updated changelog for v02-v03 - - v02 - v03 - - o Updated the document according to comments received at IETF102 - - o Added parameter to specify datastore - - o Rearranged chapters - - o Added new use case: Documenting Factory Default Settings - - o Added "Target YANG Module" to terminology - - o Clarified that instance data is a snapshot valid at the time of - creation, so it does not contain any later changes. - - o Removed topics from Open Issues according to comments received at - IETF102 - - v01 - v02 - - o The recommendation to document server capabilities was changed to - be just the primary use-case. (Merged chapter 4 into the use case - chapter.) - - o Stated that RFC7950/7951 encoding must be followed which also - defines (dis)allowed whitespace rules. - - o Added UTF-8 encoding as it is not specified in t950 for instance - data - - o added XML declaration - - v00 - v01 - - o Redefined using yang-data-ext - - o Moved metadata into ordinary leafs/leaf-lists - Appendix C. Detailed Use Cases - Non-Normative C.1. Use Cases We present a number of use cases were YANG instance data is needed. C.1.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