idnits 2.17.1
draft-ietf-netmod-yang-instance-file-format-18.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
== There is 1 instance of lines with non-ascii characters in the document.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (9 September 2021) is 959 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
No issues found here.
Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Netmod B. Lengyel
3 Internet-Draft Ericsson
4 Intended status: Standards Track B. Claise
5 Expires: 13 March 2022 Huawei
6 9 September 2021
8 YANG Instance Data File Format
9 draft-ietf-netmod-yang-instance-file-format-18
11 Abstract
13 There is a need to document data defined in YANG models at design
14 time, implementation time or when a live server is unavailable. This
15 document specifies a standard file format for YANG instance data,
16 which follows the syntax and semantics of existing YANG models, and
17 annotates it with metadata.
19 Status of This Memo
21 This Internet-Draft is submitted in full conformance with the
22 provisions of BCP 78 and BCP 79.
24 Internet-Drafts are working documents of the Internet Engineering
25 Task Force (IETF). Note that other groups may also distribute
26 working documents as Internet-Drafts. The list of current Internet-
27 Drafts is at https://datatracker.ietf.org/drafts/current/.
29 Internet-Drafts are draft documents valid for a maximum of six months
30 and may be updated, replaced, or obsoleted by other documents at any
31 time. It is inappropriate to use Internet-Drafts as reference
32 material or to cite them other than as "work in progress."
34 This Internet-Draft will expire on 13 March 2022.
36 Copyright Notice
38 Copyright (c) 2021 IETF Trust and the persons identified as the
39 document authors. All rights reserved.
41 This document is subject to BCP 78 and the IETF Trust's Legal
42 Provisions Relating to IETF Documents (https://trustee.ietf.org/
43 license-info) in effect on the date of publication of this document.
44 Please review these documents carefully, as they describe your rights
45 and restrictions with respect to this document. Code Components
46 extracted from this document must include Simplified BSD License text
47 as described in Section 4.e of the Trust Legal Provisions and are
48 provided without warranty as described in the Simplified BSD License.
50 Table of Contents
52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
53 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
54 1.2. Principles . . . . . . . . . . . . . . . . . . . . . . . 4
55 1.3. Delivery of Instance Data . . . . . . . . . . . . . . . . 4
56 1.4. Data Life cycle . . . . . . . . . . . . . . . . . . . . . 5
57 2. Instance Data File Format . . . . . . . . . . . . . . . . . . 5
58 2.1. Specifying the Content Schema . . . . . . . . . . . . . . 7
59 2.1.1. Inline Method . . . . . . . . . . . . . . . . . . . . 7
60 2.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 8
61 2.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 8
62 2.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8
63 2.2.1. Documentation of server capabilities . . . . . . . . 8
64 2.2.2. Preloading default configuration data . . . . . . . . 10
65 2.2.3. Storing diagnostics data . . . . . . . . . . . . . . 11
66 3. YANG Instance Data Model . . . . . . . . . . . . . . . . . . 12
67 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 12
68 3.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 13
69 4. Security Considerations . . . . . . . . . . . . . . . . . . . 20
70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
71 5.1. URI Registration . . . . . . . . . . . . . . . . . . . . 20
72 5.2. YANG Module Name Registration . . . . . . . . . . . . . . 21
73 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21
74 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
75 7.1. Normative References . . . . . . . . . . . . . . . . . . 21
76 7.2. Informative References . . . . . . . . . . . . . . . . . 22
77 Appendix A. Changes between revisions . . . . . . . . . . . . . 23
78 Appendix B. Backwards Compatibility . . . . . . . . . . . . . . 26
79 Appendix C. Detailed Use Cases . . . . . . . . . . . . . . . . . 26
80 C.1. Use Case 1: Early Documentation of Server Capabilities . 27
81 C.2. Use Case 2: Preloading Data . . . . . . . . . . . . . . . 28
82 C.3. Use Case 3: Documenting Factory Default Settings . . . . 28
83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28
85 1. Introduction
87 There is a need to document data defined in YANG models when a live
88 server is unavailable. Data is often needed at design,
89 implementation time or when a live running server is unavailable. To
90 facilitate this offline delivery of data, this document specifies a
91 standard format for YANG instance data sets and YANG instance data
92 files. The format of the instance data set is defined by the "ietf-
93 yang-instance-data" YANG module, see Section 3. The YANG data model
94 in this document conforms to the Network Management Datastore
95 Architecture (NMDA) defined in [RFC8342]
96 The following is a list of already implemented and potential use
97 cases.
99 UC1 Documentation of server capabilities
101 UC2 Preloading default configuration data
103 UC3 Documenting Factory Default Settings
105 UC4 Storing the configuration of a device, e.g., for backup, archive
106 or audit purposes
108 UC5 Storing diagnostics data
110 UC6 Allowing YANG instance data to potentially be carried within
111 other IPC message formats
113 UC7 Default instance data used as part of a templating solution
115 UC8 Providing data examples in RFCs or internet drafts
117 In Appendix C describes the first three use cases in detail.
119 There are many and varied use cases where YANG instance data could be
120 used. This document does not limit future uses of instance data
121 sets, so specifying how and when to use YANG instance data is out of
122 scope for this document. It is anticipated that other documents will
123 define specific use cases. Use cases are listed only as examples.
125 1.1. Terminology
127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
128 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
129 "OPTIONAL" in this document are to be interpreted as described in BCP
130 14 [RFC2119] [RFC8174] when, and only when, they appear in all
131 capitals, as shown here.
133 Instance Data: A collection of instantiated data nodes.
135 Instance Data Set: A named set of data items annotated with metadata
136 that can be used as instance data in a YANG data tree.
138 Instance Data File: A file containing an instance data set formatted
139 according to the rules described in this document.
141 Content-schema: A set of YANG modules with their revision, supported
142 features, and deviations for which the instance data set contains
143 instance data.
145 Content defining YANG module: an individual YANG module that is part
146 of the content-schema.
148 The term "server" is used as defined in [RFC8342].
150 1.2. Principles
152 The following is a list of the basic principles of the instance data
153 format:
155 P1 Two standard formats shall be defined based on the XML and JSON
156 encodings.
158 P2 Instance data shall reuse existing encoding rules for YANG
159 defined data.
161 P3 Metadata about the instance data set (Section 2, Paragraph 12)
162 shall be defined.
164 P4 A YANG instance data set shall be allowed to contain data for
165 multiple YANG modules.
167 P5 Instance data shall be allowed to contain configuration data,
168 state data, or a mix of the two.
170 P6 Partial data sets shall be allowed.
172 P7 The YANG instance data format shall be usable for any data for
173 which YANG module(s) are defined and available to the reader,
174 independent of whether the module is implemented by a server.
176 P8 It shall be possible to report the identity of the datastore with
177 which the instance data set is associated.
179 1.3. Delivery of Instance Data
181 Instance data sets that are produced as a result of some sort of
182 specification or design effort may be available without the need for
183 a live server e.g., via download from the vendor's website, or in any
184 other way that product documentation is distributed.
186 Other instance data sets may be read from or produced by the YANG
187 server itself e.g., UC5 documenting diagnostic data.
189 1.4. Data Life cycle
191 A YANG instance data set is created at a specific point of time. If
192 the data changes afterwards, this is not represented in the instance
193 data set anymore. The current values may be retrieved at run-time
194 via NETCONF/RESTCONF or received e.g., in YANG-Push notifications.
196 Whether the instance data changes and if so, when and how, should be
197 described either in the instance data set's description statement or
198 in some other implementation specific manner.
200 2. Instance Data File Format
202 A YANG instance data file MUST contain a single instance data set and
203 no additional data.
205 The format of the instance data set is defined by the "ietf-yang-
206 instance-data" YANG module. It is made up of a header part and
207 content-data. The header part carries metadata for the instance data
208 set. The content-data, defined as an anydata data node, carries the
209 instance data that the user wants to document/provide. The syntax
210 and semantics of content-data is defined by the content-schema.
212 Two formats are specified based on the XML and JSON YANG encodings.
213 Later, as other YANG encodings (e.g., CBOR) are defined, further
214 instance data formats may be specified.
216 The content-data part MUST conform to the content-schema, while
217 allowing for the exceptions listed below. The content-data part
218 SHALL follow the encoding rules defined in [RFC7950] for XML and
219 [RFC7951] for JSON and MUST use UTF-8 character encoding. Content-
220 data MAY include:
222 * metadata, as defined by [RFC7952].
224 * origin metadata, as specified in [RFC8526] and [RFC8527]
226 * implementation specific metadata relevant to individual data
227 nodes. Unknown metadata MUST be ignored by users of instance
228 data, allowing it to be used later for other purposes.
230 An instance data set MAY contain data for any number of YANG modules;
231 if needed it MAY carry the complete configuration and state data for
232 a server. Default values should be excluded where they do not
233 provide additional useful data.
235 Configuration ("config true") and operational state data ("config
236 false") MAY be mixed in the instance data file.
238 Instance data files MAY contain partial data sets. This means
239 "mandatory", "min-elements", "require-instance true", "must" and
240 "when" constrains MAY be violated.
242 The name of the instance data file SHOULD be of the form:
244 instance-data-set-name ['@' ( revision-date / timestamp ) ]
245 ( '.xml' / '.json' )
247 E.g., acme-router-modules.xml
248 E.g., acme-router-modules@2018-01-25.xml
249 E.g., acme-router-modules@2018-01-25T15_06_34_3+01_00.json
251 If the leaf "name" is present in the instance data header, its value
252 SHOULD be used for the "instance-data-set-name". If the "revision-
253 date" is present in the filename it MUST conform to the format of the
254 revision-date leaf in the YANG model. If the "revision-date" is
255 present in both the filename and in the instance data header, the
256 revision date in the file name MUST be set to the latest revision
257 date inside the instance data set. If the "timestamp" is present in
258 the filename it MUST conform to the format of the timestamp leaf in
259 the YANG model except for replacing colons as described below. If
260 the "timestamp" is present both in the filename and in the instance
261 data header, the timestamp in the file name SHOULD be set to the
262 timestamp inside the instance data set; any colons, if present, shall
263 be replaced by underscores.
265 Metadata, information about the data set itself SHOULD be included in
266 the instance data set. Some metadata items are defined in the YANG
267 module "ietf-yang-instance-data", but other items MAY be used.
269 Metadata MUST include:
271 - Version of the YANG Instance Data format
273 Metadata SHOULD include:
275 - Name of the data set
277 - Content schema specification (i.e., the "content-schema" node)
279 - Description of the instance data set. The description SHOULD
280 contain information whether and how the data can change during
281 the lifetime of the server
283 - An indication whether default values are included. The default
284 handling uses the concepts defined in [RFC6243], however as
285 only concepts are re-used, users of instance data sets, do not
286 need to support RFC 6243.
288 2.1. Specifying the Content Schema
290 To properly understand and use an instance data set, the user needs
291 to know the content-schema. One of the following methods SHOULD be
292 used:
294 Simplified-Inline method: Include the needed information as part
295 of the instance data set; short specification.
297 Inline method: Include the needed information as part of the
298 instance data set.
300 URI method: Include a URI that references another YANG instance
301 data file. This instance data file will use the same content-
302 schema as the referenced YANG instance data file. (if you don't
303 want to repeat the info again and again)
305 External Method: Do not include the "content-schema" node; the
306 user needs to obtain the information through external documents.
308 Additional methods e.g., a YANG-package based solution may be added
309 later.
311 Note, the specified content-schema only indicates the set of modules
312 that were used to define this YANG instance data set. Sometimes
313 instance data may be used for a server supporting a different YANG
314 module set (e.g., for the "Preloading default configuration data"
315 use-case, UC2 in Section 1, the instance data set may not be updated
316 every time the YANG modules on the server are updated). Whether an
317 instance data set originally defined using a specific content-schema
318 is usable with a different other schema depends on many factors
319 including the amount of differences and the compatibility between the
320 original and the other schema, considering modules, revisions,
321 features, deviations, the scope of the instance data, etc.
323 2.1.1. Inline Method
325 The inline-yang-library anydata data node carries instance data
326 (conforming to ietf-yang-library@2019-01-04) that specifies the
327 content defining YANG modules including revision, supported features,
328 deviations and any relevant additional data. An example of the
329 "inline" method is provided in Figure 1.
331 2.1.2. Simplified-Inline Method
333 The instance data set contains a list of content defining YANG
334 modules including the revision date for each. Usage of this method
335 implies that the modules are used without any deviations and with all
336 features supported. YANG modules that are only required to satisfy
337 import-only dependencies MAY be excluded from the leaf-list. If they
338 are excluded then the consumer of the instance data set has to apply
339 the YANG language rules to resolve the imports. An example of the
340 "simplified-inline" method is provided in Figure 2.
342 2.1.3. URI Method
344 The "same-schema-as-file" leaf SHALL contain a URI that references
345 another YANG instance data file. The current instance data file will
346 use the same content schema as the referenced file.
348 The referenced instance data file MAY have no content-data if it is
349 used solely for specifying the content-schema.
351 If a referenced instance data file is unavailable, content-schema is
352 unknown.
354 The URI method is advantageous when the user wants to avoid the
355 overhead of specifying the content-schema in each instance data file:
356 E.g., In UC6, when the system creates a diagnostic file every minute
357 to document the state of the server.
359 An example of the "URI" method is provided in Figure 3.
361 2.2. Examples
363 2.2.1. Documentation of server capabilities
365 The example file acme-router-modules@2021-07-29.xml reflects UC1 in
366 Section 1. It provides a list of supported YANG modules and NETCONF
367 capabilities for a server. It uses the "inline" method to specify
368 the content-schema.
370 The example uses artwork folding [RFC8792].
372 ========== NOTE: '\' line wrapping per RFC 8792 ===========
374
375
377 acme-router-modules
378
379
380
382
383 ietf-yang-library
384 2019-01-04
385
386
387 ietf-netconf-monitoring
388 2010-10-04
389
390
391
392
393
394 1956-10-23
395 Initial version
396
397 Defines the minimal set of modules that any \
398 acme-router will contain.
399 info@acme.com
400
401
403
404 ietf-yang-library
405 2019-01-04
406 \
407 urn:ietf:params:xml:ns:yang:ietf-yang-library\
408
409 implement
410
411
412 ietf-system
413 2014-08-06
414 urn:ietf:params:xml:ns:yang:ietf-system
415 sys:authentication
416 sys:local-users
417
418 acme-system-ext
419 2018-08-06
420
421 implement
422
423
424 ietf-netconf-monitoring
425 2010-10-04
426 \
427 urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring\
428
429 implement
430
431
432 ietf-yang-types
433 2013-07-15
434 urn:ietf:params:xml:ns:yang:ietf-yang-types\
435
436 import
437
438
439 acme-system-ext
440 2018-08-06
441 urn:rdns:acme.com:oammodel:acme-system-ext\
442
443 implement
444
445
446
448
449 \
450 urn:ietf:params:netconf:capability:validate:1.1\
451
452
453
454
455
457 Figure 1
459 2.2.2. Preloading default configuration data
461 The example file read-only-acm-rules@2021-07-29.xml reflects UC2 in
462 Section 1. It provides a default rule set for a read-only operator
463 role. It uses the "simplified-inline" method for specifying the
464 content-schema.
466
467
469 read-only-acm-rules
470
471 ietf-netconf-acm@2018-02-14
472
473
474 1776-07-04
475 Initial version
476
477 Access control rules for a read-only role.
478
479
480 true
481 deny
482 deny
483
484 read-only-role
485 read-only-group
486
487 read-all
488 *
489 read
490 permit
491
492
493
494
495
497 Figure 2
499 2.2.3. Storing diagnostics data
501 The example file acme-router-netconf-
502 diagnostics@2018-01-25T17_00_38Z.json reflects UC5 in Section 1. An
503 instance data set is produced by the server every 15 minutes that
504 contains statistics about the NETCONF server. As a new set is
505 produced periodically many times a day a revision-date would be
506 useless; instead a timestamp is included.
508 {
509 "ietf-yang-instance-data:instance-data-set": {
510 "name": "acme-router-netconf-diagnostics",
511 "content-schema": {
512 "same-schema-as-file": "file:///acme-diagnostics-schema.json"
513 },
514 "timestamp": "2018-01-25T17:00:38Z",
515 "description": ["NETCONF statistics"],
516 "content-data": {
517 "ietf-netconf-monitoring:netconf-state": {
518 "statistics": {
519 "netconf-start-time ": "2018-12-05T17:45:00Z",
520 "in-bad-hellos ": "32",
521 "in-sessions ": "397",
522 "dropped-sessions ": "87",
523 "in-rpcs ": "8711",
524 "in-bad-rpcs ": "408",
525 "out-rpc-errors ": "408",
526 "out-notifications": "39007"
527 }
528 }
529 }
530 }
531 }
533 Figure 3
535 3. YANG Instance Data Model
537 3.1. Tree Diagram
539 The following tree diagram [RFC8340] provides an overview of the data
540 model.
542 module: ietf-yang-instance-data
544 structure instance-data-set:
545 +-- name? string
546 +-- format-version? string
547 +-- includes-defaults? enumeration
548 +-- content-schema
549 | +-- (content-schema-spec)?
550 | +--:(simplified-inline)
551 | | +-- module* module-with-revision-date
552 | +--:(inline)
553 | | +-- inline-yang-library
554 | +--:(uri)
555 | +-- same-schema-as-file? inet:uri
556 +-- description* string
557 +-- contact? string
558 +-- organization? string
559 +-- datastore? ds:datastore-ref
560 +-- revision* [date]
561 | +-- date string
562 | +-- description? string
563 +-- timestamp? yang:date-and-time
564 +-- content-data?
566 3.2. YANG Model
568 This YANG module imports typedefs from [RFC6991], identities from
569 [RFC8342] and the "structure" extension from [RFC8791]. It also
570 references [RFC8525] and [RFC6243].
572 file "ietf-yang-instance-data@2021-07-29.yang"
573 // RFC Ed.: replace the date above if the module gets changed in
574 //anyway during reviews or RFC editor process and remove this note
575 module ietf-yang-instance-data {
576 yang-version 1.1;
577 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data";
578 prefix yid;
580 import ietf-yang-structure-ext {
581 prefix sx;
582 reference
583 "YANG Data Structure Extensions:
584 draft-ietf-netmod-yang-data-ext-05";
585 }
586 import ietf-datastores {
587 prefix ds;
588 reference
589 "RFC 8342: Network Management Datastore Architecture (NMDA)";
591 }
592 import ietf-inet-types {
593 prefix inet;
594 reference
595 "RFC 6991: Common YANG Data Types";
596 }
597 import ietf-yang-types {
598 prefix yang;
599 reference
600 "RFC 6991: Common YANG Data Types";
601 }
603 organization
604 "IETF NETMOD Working Group";
605 contact
606 "WG Web:
607 WG List:
609 Author: Balazs Lengyel
610
612 Author: Benoit Claise
613 ";
614 description
615 "The module defines the structure and content of YANG
616 instance data sets.
618 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
619 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
620 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
621 are to be interpreted as described in BCP 14 (RFC 2119)
622 (RFC 8174) when, and only when, they appear in all
623 capitals, as shown here.
625 Copyright (c) 2021 IETF Trust and the persons identified as
626 authors of the code. All rights reserved.
628 Redistribution and use in source and binary forms, with or
629 without modification, is permitted pursuant to, and subject
630 to the license terms contained in, the Simplified BSD License
631 set forth in Section 4.c of the IETF Trust's Legal Provisions
632 Relating to IETF Documents
633 (http://trustee.ietf.org/license-info).
635 This version of this YANG module is part of RFC XXXX; see
636 the RFC itself for full legal notices.";
637 // RFC Ed.: replace XXXX with RFC number and remove this note
638 revision 2021-07-29 {
639 // RFC Ed.: replace the date above if the module gets changed in
640 // anyway during reviews or RFC editor process and remove
641 //this note
642 description
643 "Initial revision.";
644 reference
645 "RFC XXXX: YANG Instance Data Format";
646 // RFC Ed.: replace XXXX with RFC number and remove this note
647 }
649 typedef module-with-revision-date {
650 type string {
651 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'
652 + '(@\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1]))?';
653 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*';
654 }
655 description
656 "A type defining a module name and an optional revision
657 date, e.g. ietf-yang-library@2019-01-04";
658 }
660 sx:structure "instance-data-set" {
661 description
662 "A data structure to define a format for YANG instance
663 data. The majority of the YANG nodes provide meta-data
664 about the instance data; the instance data itself is
665 is contained only in the 'content-data' node.";
666 leaf name {
667 type string;
668 description
669 "An arbitrary name for the YANG instance data set. This
670 value is primarily used for descriptive purposes. However,
671 when the instance data set is saved to a file, then the
672 filename MUST encode the name's value, per Section 3
673 of RFC XXXX.";
674 // RFC Ed.: replace XXXX with RFC number and remove this note
675 }
676 leaf format-version {
677 type string {
678 pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
679 }
680 default "2021-07-29";
681 // RFC Ed.: replace the date above if the module gets changed
682 // in anyway during reviews or RFC editor process and remove
683 // this note
684 description
685 "The 'revision' of the 'ietf-yang-instance-data' module
686 used to encode this 'instance-data-set'.";
687 }
688 leaf includes-defaults {
689 type enumeration {
690 enum report-all {
691 value 1;
692 description
693 "All data nodes SHALL be included independent of
694 any default values, if the data node
695 is covered by the instance-data-set.";
696 }
697 enum report-all-tagged {
698 value 2;
699 description
700 "All data nodes SHALL be included independent of
701 any default values if the data node
702 is covered by the instance-data-set.
703 Any nodes considered to be default data SHALL
704 contain a 'default' attribute set to 'true'";
705 }
706 enum trim {
707 value 3;
708 description
709 "Data nodes that have a default defined and where
710 the actual value is equal to the schema default
711 value SHALL NOT be included.";
712 }
713 enum explicit {
714 value 4;
715 description
716 "Data nodes where the actual value is equal to the
717 schema default value SHALL NOT be included.
718 However, if the actual value was set by a NETCONF
719 client or other management application by the way
720 of an explicit management operation, the data node
721 SHALL be included if the data node is covered by
722 the instance-data-set.";
723 }
724 }
725 description
726 "An instance-data-set may contain or exclude default
727 data. This leaf indicates whether default data is
728 included.
730 Instance-data-sets MAY contain incomplete data
731 sets: it may not cover all data nodes. A leaf or
732 leaf-list MAY be absent because the instance-data-set
733 does not intend to include the data node independent
734 of default handling.";
735 reference
736 "RFC 6243: With-defaults Capability for NETCONF
737 RFC 8040: RESTCONF Protocol";
738 }
739 container content-schema {
740 description
741 "The content schema (i.e., YANG modules) used to create
742 the instance data set.
743 If not present the user needs to obtain the information
744 through external documents.";
745 choice content-schema-spec {
746 description
747 "Specification of the content-schema.";
748 case simplified-inline {
749 leaf-list module {
750 type module-with-revision-date;
751 min-elements 1;
752 description
753 "The list of content defining YANG modules.
755 The value SHALL start with the module name.
756 If the module contains a revision statement the
757 revision date SHALL be included in the leaf-list
758 entry.
760 E.g., ietf-yang-library@2019-01-04
762 Usage of this leaf-list implies the modules are
763 used without any deviations and with all features
764 supported. Multiple revisions of the same module
765 MUST NOT be specified.";
766 }
767 }
768 case inline {
769 anydata inline-yang-library {
770 mandatory true;
771 description
772 "Instance data corresponding to the
773 ietf-yang-library@2019-01-04 defining
774 the set of content defining YANG modules for
775 this instance-data-set.";
776 }
777 }
778 case uri {
779 leaf same-schema-as-file {
780 type inet:uri;
781 description
782 "A reference to another YANG instance data file.
783 This instance data file uses the same
784 content schema as the referenced file.
786 Referenced files using the 'inline' or the
787 'simplified-inline' methods MUST be supported.
788 Referenced files using the 'URI Method' MAY be
789 supported.
791 The URL schemes 'file://' and 'https://' MUST
792 be supported, other schemes MAY also be
793 supported.";
794 }
795 }
796 }
797 }
798 leaf-list description {
799 type string;
800 description
801 "Description of the instance data set.";
802 }
803 leaf contact {
804 type string;
805 description
806 "Contact information for the person or
807 organization to whom queries concerning this
808 instance data set should be sent.";
809 }
810 leaf organization {
811 type string;
812 description
813 "Organization responsible for the instance
814 data set.";
815 }
816 leaf datastore {
817 type ds:datastore-ref;
818 description
819 "The identity of the datastore with which the
820 instance data set is associated, e.g., the datastore from
821 where the data was read or the datastore into which the data
822 may be loaded or the datastore which is being documented.
823 If a single specific datastore cannot be specified, the
824 leaf MUST be absent.
826 If this leaf is absent, then the datastore to which the
827 instance data belongs is unspecified.";
828 }
829 list revision {
830 key "date";
831 description
832 "Instance data sets that are produced as
833 a result of some sort of specification or design effort
834 SHOULD have at least one revision entry. For every
835 published editorial change, a new unique revision SHOULD
836 be added in front of the revisions sequence so that all
837 revisions are in reverse chronological order.
839 In case of instance data sets that are read from
840 or produced by a server or otherwise subject to
841 frequent updates or changes, revision
842 SHOULD NOT be present";
843 leaf date {
844 type string {
845 pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
846 }
847 description
848 "Specifies the date the instance data set
849 was last modified. Formatted as YYYY-MM-DD";
850 }
851 leaf description {
852 type string;
853 description
854 "Description of this revision of the instance data set.";
855 }
856 }
857 leaf timestamp {
858 type yang:date-and-time;
859 description
860 "The date and time when the instance data set
861 was last modified.
863 In case of instance data sets that are read from or
864 produced by a server or otherwise subject to frequent
865 updates or changes, timestamp SHOULD be present.
867 If both a revision list entry and timestamp are present
868 the timestamp SHOULD contain the same date as the
869 latest revision statement.";
870 }
871 anydata content-data {
872 description
873 "Contains the real instance data.
874 The data MUST conform to the relevant YANG modules
875 specified either in the content-schema or in some other
876 implementation specific manner.";
877 }
879 }
880 }
881
883 4. Security Considerations
885 The YANG module defined in this document only defines a wrapper
886 structure specifying a format and a metadata header for YANG instance
887 data defined by the content-schema. Because of this the security
888 considerations template for YANG models in section 3.7.1 in [RFC8407]
889 is not followed. The instance data is designed to be accessed as a
890 stored file or over any file access method or protocol.
892 The document does not specify any method to influence the behavior of
893 a server.
895 Instance data files may contain sensitive data.
897 The header part is not security sensitive with one possible
898 exception. If the URI method is used for specification of the
899 content schema and the URI includes a username and/or a password, the
900 instance data file needs to be handled in a secure way as mentioned
901 below.
903 The security sensitivity of the instance data in the content part is
904 completely dependent on the content schema. Depending on the nature
905 of the instance data, instance data files MAY need to be handled
906 securely. The same kind of handling should be applied, that would be
907 needed for the result of a read operation returning the same data.
909 Instance data files should be protected against modification or
910 unauthorized access using normal file handling mechanisms. Care
911 should be taken, when copying the original files or providing file
912 access for additional users, not to reveal information
913 unintentionally.
915 5. IANA Considerations
917 This document registers one URI and one YANG module.
919 5.1. URI Registration
921 This document registers one URI in the IETF XML registry [RFC3688].
922 Following the format in RFC 3688, the following registration is
923 requested to be made:
925 URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data
926 Registrant Contact: The IESG.
927 XML: N/A, the requested URI is an XML namespace.
929 5.2. YANG Module Name Registration
931 This document registers one YANG module in the YANG Module Names
932 registry [RFC6020]. Following the format in [RFC6020], the following
933 registrations are requested:
935 name: ietf-yang-instance-data
936 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data
937 prefix: yid
938 reference: RFC XXXX
939 // RFC Ed.: replace XXXX with RFC number and remove this note
941 6. Acknowledgments
943 For their valuable comments, discussions, and feedback, we wish to
944 acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe
945 Clarke, Kent Watsen Martin Bjorklund, Ladislav Lhotka, Qin Wu and
946 other members of the Netmod WG.
948 7. References
950 7.1. Normative References
952 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
953 Requirement Levels", BCP 14, RFC 2119,
954 DOI 10.17487/RFC2119, March 1997,
955 .
957 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
958 the Network Configuration Protocol (NETCONF)", RFC 6020,
959 DOI 10.17487/RFC6020, October 2010,
960 .
962 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for
963 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011,
964 .
966 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
967 RFC 6991, DOI 10.17487/RFC6991, July 2013,
968 .
970 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
971 RFC 7950, DOI 10.17487/RFC7950, August 2016,
972 .
974 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
975 RFC 7951, DOI 10.17487/RFC7951, August 2016,
976 .
978 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG",
979 RFC 7952, DOI 10.17487/RFC7952, August 2016,
980 .
982 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
983 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
984 May 2017, .
986 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
987 and R. Wilton, "Network Management Datastore Architecture
988 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
989 .
991 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
992 and R. Wilton, "YANG Library", RFC 8525,
993 DOI 10.17487/RFC8525, March 2019,
994 .
996 [RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
997 and R. Wilton, "NETCONF Extensions to Support the Network
998 Management Datastore Architecture", RFC 8526,
999 DOI 10.17487/RFC8526, March 2019,
1000 .
1002 [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
1003 and R. Wilton, "RESTCONF Extensions to Support the Network
1004 Management Datastore Architecture", RFC 8527,
1005 DOI 10.17487/RFC8527, March 2019,
1006 .
1008 [RFC8791] Bierman, A., Björklund, M., and K. Watsen, "YANG Data
1009 Structure Extensions", RFC 8791, DOI 10.17487/RFC8791,
1010 June 2020, .
1012 7.2. Informative References
1014 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
1015 DOI 10.17487/RFC3688, January 2004,
1016 .
1018 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
1019 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
1020 .
1022 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of
1023 Documents Containing YANG Data Models", BCP 216, RFC 8407,
1024 DOI 10.17487/RFC8407, October 2018,
1025 .
1027 [RFC8632] Vallin, S. and M. Bjorklund, "A YANG Data Model for Alarm
1028 Management", RFC 8632, DOI 10.17487/RFC8632, September
1029 2019, .
1031 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications
1032 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641,
1033 September 2019, .
1035 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
1036 "Handling Long Lines in Content of Internet-Drafts and
1037 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
1038 .
1040 [RFC8808] Wu, Q., Lengyel, B., and Y. Niu, "A YANG Data Model for
1041 Factory Default Settings", RFC 8808, DOI 10.17487/RFC8808,
1042 August 2020, .
1044 Appendix A. Changes between revisions
1046 RFC Ed.: Remove section "Changes between revisions"
1048 v17 - v18
1050 * Added the report-all-tagged mode to the leaf includes-defaults
1052 v16 - v17
1054 * Removed default statement from includes-default
1056 v15 - v16
1058 * Editorial changes
1060 v14 - v15
1062 * Removed reference to revision-label
1064 * For the inline method made the usage of ietf-yang-
1065 library@2019-01-04 mandatory. Simplified the case "inline" in the
1066 YANG module.
1068 * Removed the "inline-module" leaf as it does not carry useful
1069 information anymore.
1071 * Removed YANG feature
1073 v13 - v14
1075 * Added leaf includes-defaults
1077 * Many small changes based on AD review
1079 v09 - v13
1081 * Editorial updates
1083 v08 - v09
1085 * Removed reference to similar to get reply
1087 * Introduced artwork folding in the examples
1089 v07 - v08
1091 * Moved compatibility into appendix
1093 * Renamed yid-version to format-version. Changed format to date of
1094 the YANG module
1096 * Made support of ietf-yang-library mandatory if inline-content-
1097 schema is supported
1099 * Many small changes based on WGLC
1101 v06 - v07
1103 * Updated terminology, use-cases
1105 * Many small changes based on WGLC
1107 v05 - v06
1109 * Modified module name format, removed .yin or .yang extension
1111 * Removed pattern for module and inline-module. The usage of
1112 revision-label should also be allowed.
1114 v04 - v05
1116 * Updated according to YANG-Doctor review
1118 * Updated security considerations
1119 * Added a wrapping container for the schema, and renamed the data
1120 nodes in the inline and uri cases.
1122 * Allowed .yin for simplified-inline schema naming. Made date
1123 optional if it is unavailable in the YANG module.
1125 * Added a mandatory yid-version to the header metadata to allow
1126 later updates of the module.
1128 v03 - v04
1130 * removed entity-tag and last-modified timestamp
1132 * Added simplified-inline method of content-schema specification
1134 v02 - v03
1136 * target renamed to "content-schema" and "content defining YANG
1137 module(s)"
1139 * Made name of instance data set optional
1141 * Updated according to draft-ietf-netmod-yang-data-ext-03
1143 * Clarified that entity-tag and last-modified timestamp are encoded
1144 as metadata. While they contain useful data, the HTTP-header
1145 based encoding from Restconf is not suitable.
1147 v01 - v02
1149 * Removed design time from terminology
1151 * Defined the format of the content-data part by referencing various
1152 RFCs and drafts instead of the result of the get-data and get
1153 operations.
1155 * Changed target-ptr to a choice
1157 * Inline target-ptr may include augmenting modules and alternatives
1158 to ietf-yang-library
1160 * Moved list of target modules into a separate
1161 element.
1163 * Added backwards compatibility considerations
1165 v00 - v01
1166 * Added the target-ptr metadata with 3 methods
1168 * Added timestamp metadata
1170 * Removed usage of dedicated .yid file extension
1172 * Added list of use cases
1174 * Added list of principles
1176 * Updated examples
1178 * Moved detailed use case descriptions to appendix
1180 Appendix B. Backwards Compatibility
1182 The concept of backwards compatibility and what changes are backwards
1183 compatible are not defined for "instance data sets" as it is highly
1184 dependent on the specific use case and the content-schema.
1186 In case of "instance data sets" that are the result of design or
1187 specification activity, some changes that may be good to avoid are
1188 listed below.
1190 YANG uses the concept of managed entities identified by key values;
1191 if the connection between the represented entity and the key value is
1192 not preserved during an update, this may lead to the following
1193 problems.
1195 * If the key value of a list entry that represents the same managed
1196 entity as before is changed, the user may mistakenly identify the
1197 list entry as new.
1199 * If the meaning of a list entry is changed, but the key values are
1200 not (e.g., redefining an alarm-type but not changing its alarm-
1201 type-id) the change may not be noticed.
1203 * If the key value of a previously removed list entry is reused for
1204 a different entity, the change may be misinterpreted as
1205 reintroducing the previous entity.
1207 Appendix C. Detailed Use Cases
1209 This section is non-normative.
1211 C.1. Use Case 1: Early Documentation of Server Capabilities
1213 A server has a number of server-capabilities that are defined in YANG
1214 modules and can be retrieved from the server using protocols like
1215 NETCONF or RESTCONF. Server capabilities include:
1217 * data defined in "ietf-yang-library": YANG modules, submodules,
1218 features, deviations, schema-mounts, and datastores supported
1219 ([RFC8525])
1221 * alarms supported ([RFC8632])
1223 * data nodes and subtrees that support or do not support on-change
1224 notifications ([RFC8641])
1226 * netconf-capabilities in ietf-netconf-monitoring.
1228 While it is good practice to allow a client to query these
1229 capabilities from the live server, that is often not possible.
1231 Often when a network node is released, an associated NMS (network
1232 management system) is also released with it. The NMS depends on the
1233 capabilities of the server. During NMS implementation, information
1234 about server capabilities is needed. If the information is
1235 unavailable early in some offline document, but only as instance data
1236 from the live network node, the NMS implementation will be delayed,
1237 because it has to wait until the network node is ready. Also
1238 assuming that all NMS implementors will have a correctly configured
1239 network nodes from which data can be retrieved, is a very expensive
1240 proposition. (An NMS may handle dozens of node types.)
1242 Network operators often build their own home-grown NMS systems that
1243 need to be integrated with a vendor's network node. The operator
1244 needs to know the network node's server capabilities in order to do
1245 this. Moreover, the network operator's decision to buy a vendor's
1246 product may even be influenced by the network node's OAM feature set
1247 documented as the server's capabilities.
1249 Beside NMS implementors, system integrators and many others also need
1250 the same information early. Examples could be model driven testing,
1251 generating documentation, etc.
1253 Most server-capabilities are relatively stable and change only during
1254 upgrade or due to licensing or the addition or removal of hardware.
1255 They are usually defined by a vendor at design time, before the
1256 product is released. It is feasible and advantageous to define/
1257 document them early e.g., in a YANG instance data File.
1259 It is anticipated that a separate IETF document will define in detail
1260 how and which set of server capabilities should be documented.
1262 C.2. Use Case 2: Preloading Data
1264 There are parts of the configuration that must be fully configurable
1265 by the operator. However, often a simple default configuration will
1266 be sufficient.
1268 One example is access control groups/roles and related rules. While
1269 a sophisticated operator may define dozens of different groups, often
1270 a basic (read-only operator, read-write system administrator,
1271 security-administrator) triplet will be enough. Vendors will often
1272 provide such default configuration data to make device configuration
1273 easier for an operator.
1275 Defining access control data is a complex task. To help, the device
1276 vendor predefines a set of default groups (/nacm:nacm/groups) and
1277 rules for these groups to access specific parts of common models
1278 (/nacm:nacm/rule-list/rule).
1280 YANG instance data files are used to document and/or preload the
1281 default configuration.
1283 C.3. Use Case 3: Documenting Factory Default Settings
1285 Nearly every server has a factory default configuration. If the
1286 system is really badly misconfigured or if the current configuration
1287 is to be abandoned, the system can be reset the default factory
1288 configuration.
1290 The operator currently needs to know what the default configuration
1291 actually contains. YANG instance data can be used to document the
1292 factory default configuration. See [RFC8808].
1294 Authors' Addresses
1296 Balazs Lengyel
1297 Ericsson
1299 Email: balazs.lengyel@ericsson.com
1301 Benoit Claise
1302 Huawei
1304 Email: benoit.claise@huawei.com