draft-ietf-netmod-yang-instance-file-format-05.txt   draft-ietf-netmod-yang-instance-file-format-06.txt 
Netmod B. Lengyel Netmod B. Lengyel
Internet-Draft Ericsson Internet-Draft Ericsson
Intended status: Standards Track B. Claise Intended status: Standards Track B. Claise
Expires: May 20, 2020 Cisco Systems, Inc. Expires: June 5, 2020 Cisco Systems, Inc.
November 17, 2019 December 3, 2019
YANG Instance Data File Format YANG Instance Data File Format
draft-ietf-netmod-yang-instance-file-format-05 draft-ietf-netmod-yang-instance-file-format-06
Abstract Abstract
There is a need to document data defined in YANG models when a live There is a need to document data defined in YANG models when a live
server is not available. Data is often needed already at design or server is not available. Data is often needed already at design or
implementation time or needed by groups that do not have a live implementation time or needed by groups that do not have a live
running server available. This document specifies a standard file running server available. This document specifies a standard file
format for YANG instance data (which follows the syntax and semantic 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 from existing YANG models, re-using the same format as the reply to a
<get> operation/request) and annotates it with metadata. <get> operation/request) and annotates it with metadata.
skipping to change at page 1, line 37 skipping to change at page 1, line 37
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." 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 Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 40 skipping to change at page 2, line 40
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
11.1. Normative References . . . . . . . . . . . . . . . . . . 20 11.1. Normative References . . . . . . . . . . . . . . . . . . 20
11.2. Informative References . . . . . . . . . . . . . . . . . 22 11.2. Informative References . . . . . . . . . . . . . . . . . 22
Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 22 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 22
Appendix B. Changes between revisions . . . . . . . . . . . . . 22 Appendix B. Changes between revisions . . . . . . . . . . . . . 22
Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 24 Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 24
C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 24 C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 24
C.1.1. Use Case 1: Early Documentation of Server C.1.1. Use Case 1: Early Documentation of Server
Capabilities . . . . . . . . . . . . . . . . . . . . 24 Capabilities . . . . . . . . . . . . . . . . . . . . 24
C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 25 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 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26
1. Terminology 1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 RFC 2119 [RFC2119] RFC 8174 [RFC8174] when, and only when, they 14 RFC 2119 [RFC2119] RFC 8174 [RFC8174] when, and only when, they
appear in all capitals, as shown here. appear in all capitals, as shown here.
skipping to change at page 6, line 6 skipping to change at page 6, line 6
constrains MAY be violated. constrains MAY be violated.
The name of the instance data file SHOULD take one of the following The name of the instance data file SHOULD take one of the following
two forms: two forms:
If revision information inside the data set is present If revision information inside the data set is present
* instance-data-set-name ['@' revision-date] '.filetype' * instance-data-set-name ['@' revision-date] '.filetype'
* E.g., acme-router-modules@2018-01-25.xml * E.g., acme-router-modules@2018-01-25.xml
If the leaf name is present in the instance data header, this MUST If the leaf "name" is present in the instance data header, this
be used. If the revision-date is present in both the filename and MUST be used. If the "revision-date" is present in both the
in the instance data header, the revision date in the file name filename and in the instance data header, the revision date in the
MUST be set to the latest revision date inside the instance data file name MUST be set to the latest revision date inside the
set. instance data set.
If timestamp information inside the data set is present If timestamp information inside the data set is present
* instance-data-set-name ['@' timestamp] '.filetype' * instance-data-set-name ['@' timestamp] '.filetype'
* E.g., acme-router-modules@2018-01-25T15_06_34_3+01_00.json * 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 If the leaf "name" is present in the instance data header, this
be used. If the timestamp is present both in the filename and in MUST be used. If the "timestamp" is present both in the filename
the instance data header, the timestamp in the file name MUST be and in the instance data header, the timestamp in the file name
set to the timestamp inside the instance data set; the semicolons MUST be set to the timestamp inside the instance data set; the
and the decimal point, if present, shall be replaced by semicolons and the decimal point, if present, shall be replaced by
underscores. underscores.
The revision date or timestamp is optional. ".filetype" SHALL be The revision date or timestamp is optional. ".filetype" SHALL be
".json" or ".xml" according to the format used. ".json" or ".xml" according to the format used.
Metadata, information about the data set itself SHOULD be included in Metadata, information about the data set itself SHOULD be included in
the instance data set. Some metadata items are defined in the YANG the instance data set. Some metadata items are defined in the YANG
module ietf-yang-instance-data, but other items MAY also be used. module ietf-yang-instance-data, but other items MAY also be used.
Metadata MUST include: Metadata MUST include:
skipping to change at page 7, line 39 skipping to change at page 7, line 39
different real-life YANG module set depends on many factors including different real-life YANG module set depends on many factors including
the compatibility between the specified and the real-life YANG module the compatibility between the specified and the real-life YANG module
set, considering modules, revisions, features, deviations, the scope set, considering modules, revisions, features, deviations, the scope
of the instance data, etc. of the instance data, etc.
3.1.1. Inline Method 3.1.1. Inline Method
One or more inline-module elements define YANG module(s) used to One or more inline-module elements define YANG module(s) used to
specify the content defining YANG modules. 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 The anydata inline-schema carries instance data (conforming to the
inline-modules) that actually specifies the content defining YANG inline-modules) that actually specifies the content defining YANG
modules including revision, supported features, deviations and any modules including revision, supported features, deviations and any
relevant additional data (e.g., version labels) relevant additional data (e.g., version labels)
3.1.2. Simplified-Inline Method 3.1.2. Simplified-Inline Method
The instance data set contains a list of content defining YANG The instance data set contains a list of content defining YANG
modules including the revision date for each. Usage of this method modules including the revision date for each. Usage of this method
skipping to change at page 8, line 36 skipping to change at page 8, line 36
modules and NETCONF capabilities for a server. It uses the inline modules and NETCONF capabilities for a server. It uses the inline
method to specify the content-schema. method to specify the content-schema.
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<instance-data-set xmlns= <instance-data-set xmlns=
"urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"> "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data">
<name>acme-router-modules</name> <name>acme-router-modules</name>
<yid-version>1</yid-version> <yid-version>1</yid-version>
<content-schema> <content-schema>
<inline-module> <inline-module>
ietf-yang-library@2016-06-21.yang ietf-yang-library@2016-06-21
</inline-module> </inline-module>
<inline-schema> <inline-schema>
<module-state <module-state
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<module> <module>
<name>ietf-yang-library</name> <name>ietf-yang-library</name>
<revision>2016-06-21</revision> <revision>2016-06-21</revision>
</module> </module>
<module> <module>
<name>ietf-netconf-monitoring</name> <name>ietf-netconf-monitoring</name>
skipping to change at page 11, line 11 skipping to change at page 11, line 11
Configuration". It provides a (shortened) default rule set for a Configuration". It provides a (shortened) default rule set for a
read-only operator role. It uses the inline method for specifying read-only operator role. It uses the inline method for specifying
the content-schema. the content-schema.
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<instance-data-set xmlns= <instance-data-set xmlns=
"urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"> "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data">
<name>read-only-acm-rules</name> <name>read-only-acm-rules</name>
<yid-version>1</yid-version> <yid-version>1</yid-version>
<content-schema> <content-schema>
<inline-module>ietf-yang-library@2019-01-04.yang</inline-module> <inline-module>ietf-yang-library@2019-01-04</inline-module>
<inline-schema> <inline-schema>
<yang-library <yang-library
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<module-set> <module-set>
<name>all</name> <name>all</name>
<module> <module>
<name>ietf-netconf-acm</name> <name>ietf-netconf-acm</name>
<revision>2012-02-22</revision> <revision>2012-02-22</revision>
</module> </module>
</module-set> </module-set>
skipping to change at page 16, line 23 skipping to change at page 16, line 23
based on this specification."; based on this specification.";
} }
container content-schema { container content-schema {
description description
"The content schema used to create the instance data set"; "The content schema used to create the instance data set";
choice content-schema-spec { choice content-schema-spec {
description description
"Specification of the content-schema"; "Specification of the content-schema";
case simplified-inline { case simplified-inline {
leaf-list module { leaf-list module {
type string { type string ;
pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*' +
'(@\d{4}-\d{2}-\d{2})?\.((yang)|(yin))';
}
description description
"The list of content defining YANG modules. "The list of content defining YANG modules.
The value SHALL start with the module name.
If the module contains a revision statement the If the module contains a revision statement the
revision date SHALL be included in the leaf-list revision date SHALL be included in the leaf-list
entry. entry.
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 Usage of this leaf-list implies the modules are
used without any deviations and with all features used without any deviations and with all features
supported."; supported. Multiple revisions of the same module
MUST NOT be specified.";
} }
} }
case inline { case inline {
if-feature inline-content-schema; if-feature inline-content-schema;
leaf-list inline-module { leaf-list inline-module {
type string { type string ;
pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*' +
'(@\d{4}-\d{2}-\d{2})?\.((yang)|(yin))';
}
min-elements 1; min-elements 1;
ordered-by user; ordered-by user;
description description
"Indicates that content defining YANG modules "Indicates that content defining YANG modules
are specified inline. are specified inline.
The value SHALL start with the module name.
If the module contains a revision statement the If the module contains a revision statement the
revision date SHALL be included in the leaf-list revision date SHALL be included in the leaf-list
entry. entry.
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 The first item is either ietf-yang-library or some other
YANG module that contains a list of YANG modules with YANG module that contains a list of YANG modules with
their name, revision-date, supported-features, and their name, revision-date, supported-features, and
deviations. deviations.
As some versions of ietf-yang-library MAY contain As some versions of ietf-yang-library MAY contain
different module-sets for different datastores, if different module-sets for different datastores, if
multiple module-sets are included, the instance data multiple module-sets are included, the instance data
set's meta-data MUST contain the datastore information set's meta-data MUST contain the datastore information
and instance data for the ietf-yang-library MUST also and instance data for the ietf-yang-library MUST also
skipping to change at page 22, line 9 skipping to change at page 22, line 9
[RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "RESTCONF Extensions to Support the Network and R. Wilton, "RESTCONF Extensions to Support the Network
Management Datastore Architecture", RFC 8527, Management Datastore Architecture", RFC 8527,
DOI 10.17487/RFC8527, March 2019, DOI 10.17487/RFC8527, March 2019,
<https://www.rfc-editor.org/info/rfc8527>. <https://www.rfc-editor.org/info/rfc8527>.
11.2. Informative References 11.2. Informative References
[I-D.ietf-netmod-factory-default] [I-D.ietf-netmod-factory-default]
WU, Q., Lengyel, B., and Y. Niu, "Factory Default WU, Q., Lengyel, B., and Y. Niu, "Factory Default
Setting", draft-ietf-netmod-factory-default-05 (work in Setting", draft-ietf-netmod-factory-default-07 (work in
progress), October 2019. progress), November 2019.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
skipping to change at page 22, line 40 skipping to change at page 22, line 40
[RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications
for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641,
September 2019, <https://www.rfc-editor.org/info/rfc8641>. September 2019, <https://www.rfc-editor.org/info/rfc8641>.
Appendix A. Open Issues Appendix A. Open Issues
o - o -
Appendix B. Changes between revisions 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 v04 - v05
o Updated according to YANG-Doctor revied o Updated according to YANG-Doctor review
o Updated security considerations o Updated security considerations
o Added a wrapping container for the schema, and renamed the data o Added a wrapping container for the schema, and renamed the data
nodes in the inline and uri cases. nodes in the inline and uri cases.
o Allowed .yin for simplified-inline schema naming. Made date o Allowed .yin for simplified-inline schema naming. Made date
optional if it is not available in the YANG module. optional if it is not available in the YANG module.
o Added a mandatory yid-version to the header metadata to allow o Added a mandatory yid-version to the header metadata to allow
later updates of the module. later updates of the module.
v03 - v04 v03 - v04
 End of changes. 22 change blocks. 
33 lines changed or deleted 42 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/