--- 1/draft-ietf-netmod-yang-instance-file-format-05.txt 2019-12-04 05:13:13.390806551 -0800 +++ 2/draft-ietf-netmod-yang-instance-file-format-06.txt 2019-12-04 05:13:13.438807777 -0800 @@ -1,19 +1,19 @@ Netmod B. Lengyel Internet-Draft Ericsson Intended status: Standards Track B. Claise -Expires: May 20, 2020 Cisco Systems, Inc. - November 17, 2019 +Expires: June 5, 2020 Cisco Systems, Inc. + December 3, 2019 YANG Instance Data File Format - draft-ietf-netmod-yang-instance-file-format-05 + draft-ietf-netmod-yang-instance-file-format-06 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 annotates 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 May 20, 2020. + This Internet-Draft will expire on June 5, 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 @@ -75,21 +75,21 @@ 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 11.1. Normative References . . . . . . . . . . . . . . . . . . 20 11.2. Informative References . . . . . . . . . . . . . . . . . 22 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 22 Appendix B. Changes between revisions . . . . . . . . . . . . . 22 Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 24 C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 24 C.1.1. Use Case 1: Early Documentation of Server Capabilities . . . . . . . . . . . . . . . . . . . . 24 C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 25 - C.1.3. Use Case 3: Documenting Factory Default Settings . . 25 + C.1.3. Use Case 3: Documenting Factory Default Settings . . 26 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 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 appear in all capitals, as shown here. @@ -230,37 +230,37 @@ constrains MAY be violated. The name of the instance data file SHOULD take one of the following two forms: If revision information inside the data set is present * instance-data-set-name ['@' revision-date] '.filetype' * E.g., acme-router-modules@2018-01-25.xml - If the leaf name is present in the instance data header, this MUST - be used. If the revision-date is present in both the filename and - in the instance data header, the revision date in the file name - MUST be set to the latest revision date inside the instance data - set. + If the leaf "name" is present in the instance data header, this + MUST be used. If the "revision-date" is present in both the + filename and in the instance data header, the revision date in the + file name MUST be set to the latest revision date inside the + instance data set. If timestamp information inside the data set is present * instance-data-set-name ['@' timestamp] '.filetype' * E.g., acme-router-modules@2018-01-25T15_06_34_3+01_00.json - If the leaf name is present in the instance data header, this MUST - be used. If the timestamp is present both in the filename and in - the instance data header, the timestamp in the file name MUST be - set to the timestamp inside the instance data set; the semicolons - and the decimal point, if present, shall be replaced by + If the leaf "name" is present in the instance data header, this + MUST be used. If the "timestamp" is present both in the filename + and in the instance data header, the timestamp in the file name + MUST be set to the timestamp inside the instance data set; the + semicolons and the decimal point, if present, shall be replaced by underscores. The revision date or timestamp is optional. ".filetype" SHALL be ".json" or ".xml" according to the format used. Metadata, information about the data set itself SHOULD be included in the instance data set. Some metadata items are defined in the YANG module ietf-yang-instance-data, but other items MAY also be used. Metadata MUST include: @@ -309,21 +309,21 @@ 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 One or more inline-module elements define YANG module(s) used to specify the content defining YANG modules. - E.g., ietf-yang-library@2016-06-21.yang + E.g., ietf-yang-library@2016-06-21 The anydata inline-schema carries instance data (conforming to the inline-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. 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 @@ -354,21 +354,21 @@ modules and NETCONF capabilities for a server. It uses the inline method to specify the content-schema. acme-router-modules 1 - ietf-yang-library@2016-06-21.yang + ietf-yang-library@2016-06-21 ietf-yang-library 2016-06-21 ietf-netconf-monitoring @@ -443,21 +443,21 @@ 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 1 - ietf-yang-library@2019-01-04.yang + ietf-yang-library@2019-01-04 all ietf-netconf-acm 2012-02-22 @@ -693,55 +693,58 @@ based on this specification."; } container content-schema { description "The content schema used to create the instance data set"; choice content-schema-spec { description "Specification of the content-schema"; case simplified-inline { leaf-list module { - type string { - pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*' + - '(@\d{4}-\d{2}-\d{2})?\.((yang)|(yin))'; - } + type string ; 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. + If other methods (e.g., revision-label) are + defined to identify individual module revisions + those MAY be used instead of using a revision date. - E.g., ietf-yang-library@2016-06-21.yang + E.g., ietf-yang-library@2016-06-21 Usage of this leaf-list implies the modules are used without any deviations and with all features - supported."; + supported. Multiple revisions of the same module + MUST NOT be specified."; } } case inline { if-feature inline-content-schema; leaf-list inline-module { - type string { - pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*' + - '(@\d{4}-\d{2}-\d{2})?\.((yang)|(yin))'; - } + type string ; min-elements 1; ordered-by user; description "Indicates that content defining YANG modules are specified inline. + 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. + If other methods (e.g., revision-label) are + defined to identify individual module revisions + those MAY be used instead of using a revision date. - E.g., ietf-yang-library@2016-06-21.yang + E.g., ietf-yang-library@2016-06-21 The first item is either ietf-yang-library or some other YANG module that contains a list of YANG modules with their name, revision-date, supported-features, and deviations. As some versions of ietf-yang-library MAY contain different module-sets for different datastores, if multiple module-sets are included, the instance data set's meta-data MUST contain the datastore information and instance data for the ietf-yang-library MUST also @@ -964,22 +969,22 @@ [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, . 11.2. Informative References [I-D.ietf-netmod-factory-default] WU, Q., Lengyel, B., and Y. Niu, "Factory Default - Setting", draft-ietf-netmod-factory-default-05 (work in - progress), October 2019. + Setting", draft-ietf-netmod-factory-default-07 (work in + progress), November 2019. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . @@ -995,26 +1000,32 @@ [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, September 2019, . Appendix A. Open Issues o - Appendix B. Changes between revisions + v05 - v06 + + o Modified module name format, removed .yin or .yang extension + + o Removed pattern for module and inline-module. We want to allow + the usage of revision-label later + v04 - v05 - o Updated according to YANG-Doctor revied + o Updated according to YANG-Doctor review o Updated security considerations - o Added a wrapping container for the schema, and renamed the data nodes in the inline and uri cases. o Allowed .yin for simplified-inline schema naming. Made date optional if it is not available in the YANG module. o Added a mandatory yid-version to the header metadata to allow later updates of the module. v03 - v04