draft-ietf-netmod-yang-instance-file-format-09.txt   draft-ietf-netmod-yang-instance-file-format-10.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: September 18, 2020 Cisco Systems, Inc. Expires: September 21, 2020 Cisco Systems, Inc.
March 17, 2020 March 20, 2020
YANG Instance Data File Format YANG Instance Data File Format
draft-ietf-netmod-yang-instance-file-format-09 draft-ietf-netmod-yang-instance-file-format-10
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 semantics format for YANG instance data, which follows the syntax and semantics
of existing YANG models, and annotates it with metadata. of existing YANG models, and annotates it with metadata.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
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 September 18, 2020. This Internet-Draft will expire on September 21, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2020 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 23 skipping to change at page 2, line 23
2.3. Data Life cycle . . . . . . . . . . . . . . . . . . . . . 5 2.3. Data Life cycle . . . . . . . . . . . . . . . . . . . . . 5
3. Instance Data File Format . . . . . . . . . . . . . . . . . . 5 3. Instance Data File Format . . . . . . . . . . . . . . . . . . 5
3.1. Specifying the Content Schema . . . . . . . . . . . . . . 7 3.1. Specifying the Content Schema . . . . . . . . . . . . . . 7
3.1.1. Inline Method . . . . . . . . . . . . . . . . . . . . 7 3.1.1. Inline Method . . . . . . . . . . . . . . . . . . . . 7
3.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 8 3.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 8
3.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 8 3.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 8
3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8
4. YANG Instance Data Model . . . . . . . . . . . . . . . . . . 12 4. YANG Instance Data Model . . . . . . . . . . . . . . . . . . 12
4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 12 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 12
4.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 13 4.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 13
5. Security Considerations . . . . . . . . . . . . . . . . . . . 18 5. Security Considerations . . . . . . . . . . . . . . . . . . . 19
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
6.1. URI Registration . . . . . . . . . . . . . . . . . . . . 19 6.1. URI Registration . . . . . . . . . . . . . . . . . . . . 19
6.2. YANG Module Name Registration . . . . . . . . . . . . . . 19 6.2. YANG Module Name Registration . . . . . . . . . . . . . . 20
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
8.1. Normative References . . . . . . . . . . . . . . . . . . 20 8.1. Normative References . . . . . . . . . . . . . . . . . . 20
8.2. Informative References . . . . . . . . . . . . . . . . . 21 8.2. Informative References . . . . . . . . . . . . . . . . . 21
Appendix A. Changes between revisions . . . . . . . . . . . . . 22 Appendix A. Changes between revisions . . . . . . . . . . . . . 22
Appendix B. Backwards Compatibility . . . . . . . . . . . . . . 24 Appendix B. Backwards Compatibility . . . . . . . . . . . . . . 24
Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 25 Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 25
C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 25 C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 25
C.1.1. Use Case 1: Early Documentation of Server C.1.1. Use Case 1: Early Documentation of Server
Capabilities . . . . . . . . . . . . . . . . . . . . 25 Capabilities . . . . . . . . . . . . . . . . . . . . 25
C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 26 C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 26
C.1.3. Use Case 3: Documenting Factory Default Settings . . 26 C.1.3. Use Case 3: Documenting Factory Default Settings . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27
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 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
Instance Data: A collection of instantiated data nodes. Instance Data: A collection of instantiated data nodes.
skipping to change at page 3, line 27 skipping to change at page 3, line 27
The term Server is used as defined in [RFC8342]. The term Server is used as defined in [RFC8342].
2. Introduction 2. Introduction
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. To facilitate this offline delivery of running server available. To facilitate this offline delivery of
data, this document specifies a standard format for YANG instance data, this document specifies a standard format for YANG instance
data sets and YANG instance data files. 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 4. 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 The following is a list of already implemented and potential use
cases. cases.
UC1 Documentation of server capabilities UC1 Documentation of server capabilities
UC2 Preloading default configuration data UC2 Preloading default configuration data
UC3 Documenting Factory Default Settings UC3 Documenting Factory Default Settings
skipping to change at page 8, line 51 skipping to change at page 8, line 51
Capabilities". It provides (a shortened) list of supported YANG Capabilities". It provides (a shortened) list of supported YANG
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.
========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) ===========
<?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>
<format-version>2020-03-06</format-version>
<content-schema> <content-schema>
<inline-module>ietf-yang-library@2016-06-21</inline-module> <inline-module>ietf-yang-library@2016-06-21</inline-module>
<inline-schema> <inline-schema>
<modules-state \ <modules-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>
<revision>2010-10-04</revision> <revision>2010-10-04</revision>
</module> </module>
</modules-state> </modules-state>
</inline-schema> </inline-schema>
<content-schema> </content-schema>
<revision> <revision>
<date>1956-10-23</date> <date>1956-10-23</date>
<description>Initial version</description> <description>Initial version</description>
</revision> </revision>
<description>Defines the minimal set of modules that any \ <description>Defines the minimal set of modules that any \
acme-router will contain.</description> acme-router will contain.</description>
<contact>info@acme.com</contact> <contact>info@acme.com</contact>
<content-data> <content-data>
<!-- The example lists only 4 modules, but it could list the <!-- The example lists only 4 modules, but it could list the
full set of supported modules for a server, potentially many full set of supported modules for a server, potentially many
skipping to change at page 11, line 9 skipping to change at page 11, line 9
The following example is based on "UC2, Preloading Default The following example is based on "UC2, Preloading Default
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 <instance-data-set
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"> xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-instance-data">
<name>read-only-acm-rules</name> <name>read-only-acm-rules</name>
<format-version>2020-03-06</format-version>
<content-schema> <content-schema>
<inline-module>ietf-yang-library@2019-01-04</inline-module> <module>ietf-netconf-acm@2018-02-14</module>
<inline-schema>
<yang-library
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<module-set>
<name>all</name>
<module>
<name>ietf-netconf-acm</name>
<revision>2012-02-22</revision>
</module>
</module-set>
</yang-library>
</inline-schema>
</content-schema> </content-schema>
<revision> <revision>
<date>1776-07-04</date> <date>1776-07-04</date>
<description>Initial version</description> <description>Initial version</description>
</revision> </revision>
<description>Access control rules for a read-only role.</description> <description>Access control rules for a read-only role.</description>
<content-data> <content-data>
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"> <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<enable-nacm>true</enable-nacm> <enable-nacm>true</enable-nacm>
<read-default>deny</read-default> <read-default>deny</read-default>
skipping to change at page 12, line 14 skipping to change at page 12, line 8
The following example is based on UC5 Storing diagnostics data. An The following example is based on UC5 Storing diagnostics data. An
instance data set is produced by the server every 15 minutes that instance data set is produced by the server every 15 minutes that
contains statistics about NETCONF. As a new set is produced contains statistics about NETCONF. As a new set is produced
periodically many times a day a revision-date would be useless; periodically many times a day a revision-date would be useless;
instead a timestamp is included. instead a timestamp is included.
{ {
"ietf-yang-instance-data:instance-data-set": { "ietf-yang-instance-data:instance-data-set": {
"name": "acme-router-netconf-diagnostics", "name": "acme-router-netconf-diagnostics",
"format-version": "2020-03-06",
"content-schema": { "content-schema": {
"same-schema-as-file": "file:///acme-diagnostics-schema.json", "same-schema-as-file": "file:///acme-diagnostics-schema.json"
}, },
"timestamp": "2018-01-25T17:00:38Z", "timestamp": "2018-01-25T17:00:38Z",
"description": "description": ["NETCONF statistics"],
"NETCONF statistics",
"content-data": { "content-data": {
"ietf-netconf-monitoring:netconf-state": { "ietf-netconf-monitoring:netconf-state": {
"statistics": { "statistics": {
"netconf-start-time ": "2018-12-05T17:45:00Z", "netconf-start-time ": "2018-12-05T17:45:00Z",
"in-bad-hellos ": "32", "in-bad-hellos ": "32",
"in-sessions ": "397", "in-sessions ": "397",
"dropped-sessions ": "87", "dropped-sessions ": "87",
"in-rpcs ": "8711", "in-rpcs ": "8711",
"in-bad-rpcs ": "408", "in-bad-rpcs ": "408",
"out-rpc-errors ": "408", "out-rpc-errors ": "408",
skipping to change at page 13, line 7 skipping to change at page 13, line 7
4. YANG Instance Data Model 4. YANG Instance Data Model
4.1. Tree Diagram 4.1. Tree Diagram
The following tree diagram [RFC8340] provides an overview of the data The following tree diagram [RFC8340] provides an overview of the data
model. model.
module: ietf-yang-instance-data module: ietf-yang-instance-data
structure instance-data-set: structure instance-data-set:
+--rw name? string +-- name? string
+--rw format-version string +-- format-version? string
+--rw content-schema +-- content-schema
| +--rw (content-schema-spec)? | +-- (content-schema-spec)?
| +--:(simplified-inline) | +--:(simplified-inline)
| | +--rw module* string | | +-- module* string
| +--:(inline) {inline-content-schema}? | +--:(inline) {inline-content-schema}?
| | +--rw inline-module* string | | +-- inline-module* string
| | +--rw inline-schema <anydata> | | +-- inline-schema <anydata>
| +--:(uri) | +--:(uri)
| +--rw same-schema-as-file? inet:uri | +-- same-schema-as-file? inet:uri
+--rw description* string +-- description* string
+--rw contact? string +-- contact? string
+--rw organization? string +-- organization? string
+--rw datastore? ds:datastore-ref +-- datastore? ds:datastore-ref
+--rw revision* [date] +-- revision* [date]
| +--rw date string | +-- date string
| +--rw description? string | +-- description? string
+--rw timestamp? yang:date-and-time +-- timestamp? yang:date-and-time
+--rw content-data? <anydata> +-- content-data? <anydata>
4.2. YANG Model 4.2. YANG Model
This YANG module imports typedefs from [RFC6991], identities from This YANG module imports typedefs from [RFC6991], identities from
[RFC8342] and the "structure" extension from [RFC8342] and the "structure" extension from
[I-D.ietf-netmod-yang-data-ext]. [I-D.ietf-netmod-yang-data-ext].
The YANG data model in this document conforms to the Network <CODE BEGINS> file "ietf-yang-instance-data@2020-03-19.yang"
Management Datastore Architecture (NMDA) defined in [RFC8342]
<CODE BEGINS> file "ietf-yang-instance-data@2020-03-06.yang"
module ietf-yang-instance-data { module ietf-yang-instance-data {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data";
prefix yid; prefix yid;
import ietf-yang-structure-ext { import ietf-yang-structure-ext {
prefix sx; prefix sx;
reference
"YANG Data Structure Extensions:
draft-ietf-netmod-yang-data-ext-05";
} }
import ietf-datastores { import ietf-datastores {
prefix ds; prefix ds;
reference
"RFC 8342: Network Management Datastore Architecture (NMDA)";
} }
import ietf-inet-types { import ietf-inet-types {
prefix inet; prefix inet;
} reference
"RFC 6991: Common YANG Data Types";
}
import ietf-yang-types { import ietf-yang-types {
prefix yang; prefix yang;
reference
"RFC 6991: Common YANG Data Types";
} }
organization organization
"IETF NETMOD Working Group"; "IETF NETMOD Working Group";
contact contact
"WG Web: <https://datatracker.ietf.org/wg/netmodf/> "WG Web: <https://datatracker.ietf.org/wg/netmodf/>
WG List: <mailto:netmod@ietf.org> WG List: <mailto:netmod@ietf.org>
Author: Balazs Lengyel Author: Balazs Lengyel
<mailto:balazs.lengyel@ericsson.com>"; <mailto:balazs.lengyel@ericsson.com>";
skipping to change at page 14, line 39 skipping to change at page 14, line 45
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
revision 2020-03-06 { revision 2020-03-19 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: YANG Instance Data Format"; "RFC XXXX: YANG Instance Data Format";
} }
feature inline-content-schema { feature inline-content-schema {
description description
"This feature indicates that inline content-schema "This feature indicates that inline content-schema
option is supported."; option is supported.";
} }
sx:structure "instance-data-set" { sx:structure "instance-data-set" {
description description
"A data structure to define a format for "A data structure to define a format for
YANG instance data sets. Consists of meta-data about YANG instance data sets. Consists of meta-data about
the instance data set and the real content-data."; the instance data set and the real content-data.";
leaf name { leaf name {
type string; type string;
description description
"Name of the YANG instance data set."; "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 3
of RFC XXXX.";
} }
leaf format-version { leaf format-version {
type string; type string {
default "2020-03-06"; pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
}
default "2020-03-19";
description description
"Version of the 'YANG Instance Data format'. "Version of the 'YANG Instance Data format'.
It SHALL contain the revision date of the It SHALL contain the revision date of the
ietf-yang-instance-data module used when creating the ietf-yang-instance-data module used when creating the
instance data set in a YYYY-MM-DD format"; instance data set in a YYYY-MM-DD format";
} }
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.
If not present the user needs to obtain the information
through external documents.";
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;
description description
"The list of content defining YANG modules. "The list of content defining YANG modules.
The value SHALL start with the module name. 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. If other methods (e.g., revision-label) are entry. If other methods (e.g., revision-label) are
skipping to change at page 18, line 13 skipping to change at page 18, line 27
published editorial change, a new one SHOULD be added published editorial change, a new one SHOULD be added
in front of the revisions sequence so that all in front of the revisions sequence so that all
revisions are in reverse chronological order. revisions are in reverse chronological order.
For instance data sets that are read from For instance data sets that are read from
or produced by a server or otherwise or produced by a server or otherwise
subject to frequent updates or changes, revision subject to frequent updates or changes, revision
SHOULD NOT be present"; SHOULD NOT be present";
leaf date { leaf date {
type string { type string {
pattern '\d{4}-\d{2}-\d{2}'; pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
} }
description description
"Specifies the date the instance data set "Specifies the date the instance data set
was last modified. Formatted as YYYY-MM-DD"; was last modified. Formatted as YYYY-MM-DD";
} }
leaf description { leaf description {
type string; type string;
description description
"Description of this revision of the instance data set."; "Description of this revision of the instance data set.";
} }
skipping to change at page 22, line 22 skipping to change at page 22, line 37
2019, <https://www.rfc-editor.org/info/rfc8632>. 2019, <https://www.rfc-editor.org/info/rfc8632>.
[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. Changes between revisions Appendix A. Changes between revisions
Note to RFC Editor (To be removed by RFC Editor) Note to RFC Editor (To be removed by RFC Editor)
v09 - v10
o Editorial updates
v08 - v09 v08 - v09
o Removed reference to similar to get reply o Removed reference to similar to get reply
o Introduced artwork folding in the examples o Introduced artwork folding in the examples
v07 - v08 v07 - v08
o Moved compatibility into appendix o Moved compatibility into appendix
o Renamed yid-version to format-version as "yid" can be regarded as o Renamed yid-version to format-version. Changed format to date of
a racial slur. Changed format to date of the YANG module the YANG module
o Made support of ietf-yang-library mandatory if inline-content- o Made support of ietf-yang-library mandatory if inline-content-
schema is supported schema is supported
o Many small changes based on WGLC o Many small changes based on WGLC
v06 - v07 v06 - v07
o Updated terminology, use-cases o Updated terminology, use-cases
 End of changes. 32 change blocks. 
62 lines changed or deleted 67 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/