idnits 2.17.00 (12 Aug 2021)
/tmp/idnits52602/draft-ietf-netmod-yang-instance-file-format-21.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 (8 October 2021) is 218 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: 11 April 2022 Huawei
6 8 October 2021
8 YANG Instance Data File Format
9 draft-ietf-netmod-yang-instance-file-format-21
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 11 April 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 . . . . . . . . . . . . . . . . . . . . 8
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 . . . . . . . . . . . . . . . . . . . 19
70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
71 5.1. URI Registration . . . . . . . . . . . . . . . . . . . . 20
72 5.2. YANG Module Name Registration . . . . . . . . . . . . . . 20
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 . . . . . . . . . . . . . . . . . 27
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 even later when a live running server is
90 unavailable. To facilitate this offline delivery of data, this
91 document specifies a standard format for YANG instance data sets and
92 YANG instance data files. The format of the instance data set is
93 defined by the "ietf-yang-instance-data" YANG module, see Section 3.
94 The YANG data model in this document conforms to the Network
95 Management Datastore 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 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, the instance data set will no longer
193 represent the current data, unless it is updated. The current values
194 may be retrieved at run-time via NETCONF/RESTCONF or received e.g.,
195 in YANG-Push notifications.
197 Whether the instance data changes and if so, when and how, should be
198 described either in the instance data set's description statement or
199 in some other implementation specific manner.
201 2. Instance Data File Format
203 A YANG instance data file MUST contain a single instance data set and
204 no additional data.
206 The format of the instance data set is defined by the "ietf-yang-
207 instance-data" YANG module. It is made up of a header part and
208 content-data. The header part carries metadata for the instance data
209 set. The content-data, defined as an anydata data node, carries the
210 instance data that the user wants to document/provide. The syntax
211 and semantics of content-data is defined by the content-schema.
213 Two formats are specified based on the XML and JSON YANG encodings.
214 The file formats are achieved by applying the respective XML and JSON
215 encoding rules for the YANG structure included in this document.
216 Later, as other YANG encodings (e.g., CBOR) are defined, further
217 instance data formats may be specified.
219 The content-data part MUST conform to the content-schema, while
220 allowing for the exceptions listed below. The content-data part
221 SHALL follow the encoding rules defined in [RFC7950] for XML and
222 [RFC7951] for JSON and MUST use UTF-8 character encoding. Content-
223 data MAY include:
225 * metadata, as defined by [RFC7952].
227 * origin metadata, as specified in [RFC8526] and [RFC8527]
229 * implementation specific metadata relevant to individual data
230 nodes. Unknown metadata MUST be ignored by users of instance
231 data, allowing it to be used later for other purposes.
233 An instance data set MAY contain data for any number of YANG modules;
234 if needed it MAY carry the complete configuration and state data for
235 a server. Default values should be excluded where they do not
236 provide additional useful data.
238 Configuration ("config true") and operational state data ("config
239 false") MAY be mixed in the instance data file.
241 Instance data files MAY contain partial data sets. This means
242 "mandatory", "min-elements", "require-instance true", "must" and
243 "when" constraints MAY be violated.
245 The name of the instance data file SHOULD be of the form (using ABNF
246 notation [RFC5234]):
248 instance-data-set-name ["@" ( revision-date / timestamp ) ]
249 ( ".xml" / ".json" )
251 E.g., acme-router-modules.xml
252 E.g., acme-router-modules@2018-01-25.xml
253 E.g., acme-router-modules@2018-01-25T15_06_34_3+01_00.json
255 If the leaf "name" is present in the instance data header, its value
256 SHOULD be used for the "instance-data-set-name" in the filename. If
257 the "revision-date" is present in the filename it MUST conform to the
258 format of the revision-date leaf in the YANG model. If the
259 "revision-date" is present in both the filename and in the instance
260 data header, the revision date in the file name MUST be set to the
261 latest revision date inside the instance data set. If the
262 "timestamp" is present in the filename it MUST conform to the format
263 of the timestamp leaf in the YANG model except for replacing colons
264 as described below. If the "timestamp" is present both in the
265 filename and in the instance data header, the timestamp in the file
266 name SHOULD be set to the timestamp inside the instance data set; any
267 colons, if present, shall be replaced by underscores.
269 Metadata, information about the data set itself MUST be included.
270 Some metadata items are defined in the YANG module "ietf-yang-
271 instance-data", but other items MAY be used.
273 Metadata MUST include:
275 - Version of the YANG Instance Data format (if not explicitly
276 present the default value is used)
278 Metadata SHOULD include:
280 - Name of the data set
282 - Content-schema specification (i.e., the "content-schema" node)
283 - Description of the instance data set. The description SHOULD
284 contain information whether and how the data can change during
285 the lifetime of the server
287 - An indication whether default values are included. The default
288 handling uses the concepts defined in [RFC6243], however as
289 only concepts are re-used, users of instance data sets, do not
290 need to support RFC 6243.
292 2.1. Specifying the Content Schema
294 To properly understand and use an instance data set, the user needs
295 to know the content-schema. The content-schema can be either
296 specified in external documents or within the instance data set. In
297 the latter case one of the following methods MUST be used:
299 Inline method: Include the needed information as part of the
300 instance data set.
302 Simplified-Inline method: Include the needed information as part
303 of the instance data set; short specification, only the module
304 name and revision-date is used.
306 URI method: Include a URI that references another YANG instance
307 data file. This instance data file will use the same content-
308 schema as the referenced YANG instance data file. (if you don't
309 want to repeat the info again and again)
311 Additional methods e.g., a YANG-package based solution may be added
312 later.
314 Note, the specified content-schema only indicates the set of modules
315 that were used to define this YANG instance data set. Sometimes
316 instance data may be used for a server supporting a different YANG
317 module set (e.g., for the "Preloading default configuration data"
318 use-case, UC2 in Section 1, the instance data set may not be updated
319 every time the YANG modules on the server are updated). Whether an
320 instance data set originally defined using a specific content-schema
321 is usable with a different other schema depends on many factors
322 including the amount of differences and the compatibility between the
323 original and the other schema, considering modules, revisions,
324 features, deviations, the scope of the instance data, etc.
326 2.1.1. Inline Method
328 The inline-yang-library anydata data node carries instance data
329 (conforming to ietf-yang-library@2019-01-04) [RFC8525] that specifies
330 the content defining YANG modules including revision, supported
331 features, deviations and any relevant additional data. An example of
332 the "inline" method is provided in Section 2.2.1.
334 2.1.2. Simplified-Inline Method
336 The instance data set contains a list of content defining YANG
337 modules including the revision date for each. Usage of this method
338 implies that the modules are used without any deviations and with all
339 features supported. YANG modules that are only required to satisfy
340 import-only dependencies MAY be excluded from the leaf-list. If they
341 are excluded then the consumer of the instance data set has to apply
342 the YANG language rules to resolve the imports. An example of the
343 "simplified-inline" method is provided in Section 2.2.2.
345 2.1.3. URI Method
347 The "same-schema-as-file" leaf SHALL contain a URI that references
348 another YANG instance data file. The current instance data file will
349 use the same content-schema as the referenced file.
351 The referenced instance data file MAY have no content-data if it is
352 used solely for specifying the content-schema.
354 If a referenced instance data file is unavailable, content-schema is
355 unknown.
357 The URI method is advantageous when the user wants to avoid the
358 overhead of specifying the content-schema in each instance data file:
359 E.g., In UC6, when the system creates a diagnostic file every minute
360 to document the state of the server.
362 An example of the "URI" method is provided in Section 2.2.3.
364 2.2. Examples
366 2.2.1. Documentation of server capabilities
368 The example file acme-router-modules@2021-09-16.xml reflects UC1 in
369 Section 1. It provides a list of supported YANG modules and NETCONF
370 capabilities for a server. It uses the "inline" method to specify
371 the content-schema.
373 The example uses artwork folding [RFC8792].
375 ========== NOTE: '\' line wrapping per RFC 8792 ===========
377
378
380 acme-router-modules
381
382
383
385
386 ietf-yang-library
387 2019-01-04
388
389
390 ietf-netconf-monitoring
391 2010-10-04
392
393
394
395
396
397 2020-10-23
398 Initial version
399
400 Defines the minimal set of modules that any \
401 acme-router will contain. This minimal set will \
402 only change when a new SW release is \
403 introduced.
404 info@acme.example.com
405
406
408
409 ietf-yang-library
410 2019-01-04
411 \
412 urn:ietf:params:xml:ns:yang:ietf-yang-library\
413
414 implement
415
416
417 ietf-system
418 2014-08-06
419 urn:ietf:params:xml:ns:yang:ietf-system
420 sys:authentication
421 sys:local-users
422
423 acme-system-ext
424 2018-08-06
425
426 implement
427
428
429 ietf-netconf-monitoring
430 2010-10-04
431 \
432 urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring\
433
434 implement
435
436
437 ietf-yang-types
438 2013-07-15
439 urn:ietf:params:xml:ns:yang:ietf-yang-types\
440
441 import
442
443
444 acme-system-ext
445 2018-08-06
446 \
447 urn:rdns:acme.example.com:oammodel:acme-system-ext\
448
449 implement
450
451
452
454
455 \
456 urn:ietf:params:netconf:capability:validate:1.1\
457
458
459
460
461
463 Figure 1
465 2.2.2. Preloading default configuration data
467 The example file read-only-acm-rules@2021-09-16.xml reflects UC2 in
468 Section 1. It provides a default rule set for a read-only operator
469 role. It uses the "simplified-inline" method for specifying the
470 content-schema.
472 ========== NOTE: '\' line wrapping per RFC 8792 ===========
474
475
477 read-only-acm-rules
478
479 ietf-netconf-acm@2018-02-14
480
481
482 2018-07-04
483 Initial version
484
485 Default access control rules for a read-only \
486 role. This set of rules will only change when a new \
487 SW release is introduced.
488
489
490 true
491 deny
492 deny
493
494 read-only-role
495 read-only-group
496
497 read-all
498 *
499 read
500 permit
501
502
503
504
505
507 Figure 2
509 2.2.3. Storing diagnostics data
511 The example file acme-router-netconf-
512 diagnostics@2018-01-25T17_00_38Z.json reflects UC5 in Section 1. An
513 instance data set is produced by the server every 15 minutes that
514 contains statistics about the NETCONF server. As a new set is
515 produced periodically many times a day a revision-date would be
516 useless; instead a timestamp is included.
518 ========== NOTE: '\' line wrapping per RFC 8792 ===========
520 {
521 "ietf-yang-instance-data:instance-data-set": {
522 "name": "acme-router-netconf-diagnostics",
523 "content-schema": {
524 "same-schema-as-file": "file:///acme-diagnostics-schema.json"
525 },
526 "timestamp": "2018-01-25T17:00:38Z",
527 "description": ["NETCONF statistics, \
528 The data may change at any time."],
529 "content-data": {
530 "ietf-netconf-monitoring:netconf-state": {
531 "statistics": {
532 "netconf-start-time ": "2018-12-05T17:45:00Z",
533 "in-bad-hellos ": "32",
534 "in-sessions ": "397",
535 "dropped-sessions ": "87",
536 "in-rpcs ": "8711",
537 "in-bad-rpcs ": "408",
538 "out-rpc-errors ": "408",
539 "out-notifications": "39007"
540 }
541 }
542 }
543 }
544 }
546 Figure 3
548 3. YANG Instance Data Model
550 3.1. Tree Diagram
552 The following tree diagram [RFC8340] provides an overview of the data
553 model.
555 module: ietf-yang-instance-data
557 structure instance-data-set:
558 +-- name? string
559 +-- format-version? string
560 +-- includes-defaults? enumeration
561 +-- content-schema
562 | +-- (content-schema-spec)?
563 | +--:(simplified-inline)
564 | | +-- module* module-with-revision-date
565 | +--:(inline)
566 | | +-- inline-yang-library
567 | +--:(uri)
568 | +-- same-schema-as-file? inet:uri
569 +-- description* string
570 +-- contact? string
571 +-- organization? string
572 +-- datastore? ds:datastore-ref
573 +-- revision* [date]
574 | +-- date string
575 | +-- description? string
576 +-- timestamp? yang:date-and-time
577 +-- content-data?
579 3.2. YANG Model
581 This YANG module imports typedefs from [RFC6991], [RFC6243],
582 identities from [RFC8342] and the "structure" extension from
583 [RFC8791]. It also references [RFC8525].
585 file "ietf-yang-instance-data@2021-09-16.yang"
586 // RFC Ed.: replace the date above if the module gets changed in
587 //any way during reviews or RFC editor process and remove this note
588 module ietf-yang-instance-data {
589 yang-version 1.1;
590 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data";
591 prefix yid;
593 import ietf-yang-structure-ext {
594 prefix sx;
595 reference
596 "YANG Data Structure Extensions:
597 draft-ietf-netmod-yang-data-ext-05";
598 }
599 import ietf-datastores {
600 prefix ds;
601 reference
602 "RFC 8342: Network Management Datastore Architecture (NMDA)";
604 }
605 import ietf-inet-types {
606 prefix inet;
607 reference
608 "RFC 6991: Common YANG Data Types";
609 }
610 import ietf-yang-types {
611 prefix yang;
612 reference
613 "RFC 6991: Common YANG Data Types";
614 }
616 import ietf-netconf-with-defaults {
617 prefix ncwd;
618 reference
619 "RFC 6243: With-defaults Capability for NETCONF";
620 }
622 organization
623 "IETF NETMOD Working Group";
624 contact
625 "WG Web:
626 WG List:
628 Author: Balazs Lengyel
629
631 Author: Benoit Claise
632 ";
633 description
634 "The module defines the structure and content of YANG
635 instance data sets.
637 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
638 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
639 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
640 are to be interpreted as described in BCP 14 (RFC 2119)
641 (RFC 8174) when, and only when, they appear in all
642 capitals, as shown here.
644 Copyright (c) 2021 IETF Trust and the persons identified as
645 authors of the code. All rights reserved.
647 Redistribution and use in source and binary forms, with or
648 without modification, is permitted pursuant to, and subject
649 to the license terms contained in, the Simplified BSD License
650 set forth in Section 4.c of the IETF Trust's Legal Provisions
651 Relating to IETF Documents
652 (http://trustee.ietf.org/license-info).
654 This version of this YANG module is part of RFC XXXX; see
655 the RFC itself for full legal notices.";
656 // RFC Ed.: replace XXXX with RFC number and remove this note
658 revision 2021-09-16 {
659 // RFC Ed.: replace the date above if the module gets changed in
660 // anyway during reviews or RFC editor process and remove
661 //this note
662 description
663 "Initial revision.";
664 reference
665 "RFC XXXX: YANG Instance Data Format";
666 // RFC Ed.: replace XXXX with RFC number and remove this note
667 }
669 typedef module-with-revision-date {
670 type string {
671 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'
672 + '(@\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1]))?';
673 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*';
674 }
675 description
676 "A type defining a module name and an optional revision
677 date, e.g. ietf-yang-library@2019-01-04";
678 }
680 sx:structure "instance-data-set" {
681 description
682 "A data structure to define a format for YANG instance
683 data. The majority of the YANG nodes provide meta-data
684 about the instance data; the instance data itself is
685 contained only in the 'content-data' node.";
686 leaf name {
687 type string;
688 description
689 "An arbitrary name for the YANG instance data set. This
690 value is primarily used for descriptive purposes. However,
691 when the instance data set is saved to a file, then the
692 filename MUST encode the name's value, per Section 2
693 of RFC XXXX.";
694 // RFC Ed.: replace XXXX with RFC number and remove this note
695 }
696 leaf format-version {
697 type string {
698 pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
699 }
700 default "2021-09-16";
701 // RFC Ed.: replace the date above if the module gets changed
702 // in anyway during reviews or RFC editor process and remove
703 // this note
704 description
705 "The 'revision' of the 'ietf-yang-instance-data' module
706 used to encode this 'instance-data-set'.";
707 }
708 leaf includes-defaults {
709 type ncwd:with-defaults-mode;
710 default report-all;
711 description "
712 Indicates how data nodes with default values are
713 represented for all data nodes contained in the
714 instance-data-set.
716 It uses the same definitions as per section 3 of RFC 6243,
717 but applied in the context of an instance data file rather
718 than a NETCONF request using the
719 parameter.
721 For JSON files, the encoding of the 'report-all-tagged'
722 option is as defined in section 4.8.9 of RFC 8040.";
723 reference "With-defaults Capability for NETCONF, RFC 6243.";
724 }
725 container content-schema {
726 description
727 "The content schema (i.e., YANG modules) used to create
728 the instance data set.
729 If not present the user needs to obtain the information
730 through external documents.";
731 choice content-schema-spec {
732 description
733 "Specification of the content-schema.";
734 case simplified-inline {
735 leaf-list module {
736 type module-with-revision-date;
737 min-elements 1;
738 description
739 "The list of content defining YANG modules.
741 The value SHALL start with the module name.
742 If the module contains a revision statement the
743 revision date SHALL be included in the leaf-list
744 entry.
746 E.g., ietf-yang-library@2019-01-04
747 Usage of this leaf-list implies the modules are
748 used without any deviations and with all features
749 supported. Multiple revisions of the same module
750 MUST NOT be specified.";
751 }
752 }
753 case inline {
754 anydata inline-yang-library {
755 mandatory true;
756 description
757 "Instance data corresponding to the
758 ietf-yang-library@2019-01-04 defining
759 the set of content defining YANG modules for
760 this instance-data-set.";
761 }
762 }
763 case uri {
764 leaf same-schema-as-file {
765 type inet:uri;
766 description
767 "A reference to another YANG instance data file.
768 This instance data file uses the same
769 content schema as the referenced file.
771 Referenced files using the 'inline' or the
772 'simplified-inline' methods MUST be supported.
773 Referenced files using the 'URI Method' MAY be
774 supported.
776 The URL schemes 'file://' and 'https://' MUST
777 be supported, other schemes MAY also be
778 supported.";
779 }
780 }
781 }
782 }
783 leaf-list description {
784 type string;
785 description
786 "Description of the instance data set.";
787 }
788 leaf contact {
789 type string;
790 description
791 "Contact information for the person or
792 organization to whom queries concerning this
793 instance data set should be sent.";
794 }
795 leaf organization {
796 type string;
797 description
798 "Organization responsible for the instance
799 data set.";
800 }
801 leaf datastore {
802 type ds:datastore-ref;
803 description
804 "The identity of the datastore with which the
805 instance data set is associated, e.g., the datastore from
806 where the data was read or the datastore into which the data
807 may be loaded or the datastore which is being documented.
808 If a single specific datastore cannot be specified, the
809 leaf MUST be absent.
811 If this leaf is absent, then the datastore to which the
812 instance data belongs is unspecified.";
813 }
814 list revision {
815 key "date";
816 description
817 "Instance data sets that are produced as
818 a result of some sort of specification or design effort
819 SHOULD have at least one revision entry. For every
820 published editorial change, a new unique revision SHOULD
821 be added in front of the revisions sequence so that all
822 revisions are in reverse chronological order.
824 In case of instance data sets that are read from
825 or produced by a server or otherwise subject to
826 frequent updates or changes, revision
827 SHOULD NOT be present";
828 leaf date {
829 type string {
830 pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
831 }
832 description
833 "Specifies the date the instance data set
834 was last modified. Formatted as YYYY-MM-DD";
835 }
836 leaf description {
837 type string;
838 description
839 "Description of this revision of the instance data set.";
840 }
841 }
842 leaf timestamp {
843 type yang:date-and-time;
844 description
845 "The date and time when the instance data set
846 was last modified.
848 In case of instance data sets that are read from or
849 produced by a server or otherwise subject to frequent
850 updates or changes, timestamp SHOULD be present.
852 If both a revision list entry and timestamp are present
853 the timestamp SHOULD contain the same date as the
854 latest revision statement.";
855 }
856 anydata content-data {
857 description
858 "Contains the real instance data.
859 The data MUST conform to the relevant YANG modules
860 specified either in the content-schema or in some other
861 implementation specific manner.";
862 }
863 }
864 }
865
867 4. Security Considerations
869 The YANG module defined in this document only defines a wrapper
870 structure specifying a format and a metadata header for YANG instance
871 data defined by the content-schema. Because of this the security
872 considerations template for YANG models in section 3.7.1 in [RFC8407]
873 is not followed. The instance data is designed to be accessed as a
874 stored file or over any file access method or protocol.
876 The document does not specify any method to influence the behavior of
877 a server.
879 The header part is usually not security sensitive, however sensitive
880 information may be included, in which case it needs to be handled
881 securely as mentioned below. Information to consider includes:
883 * If the URI method is used for specification of the content-schema
884 and the URI includes a userinfo subcomponent
886 * Any description text
888 The content part may contain sensitive data. The security
889 sensitivity of this data is completely dependent on the content-
890 schema. Depending on the nature of the instance data, instance data
891 files MAY need to be handled securely. The same kind of handling
892 should be applied to this file at-rest and in-transit that would be
893 needed for the result of a read operation returning the same data.
894 These in-transit protection mechanisms will also mitigate integrity
895 issues when transporting the file.
897 Instance data files should be protected against modification or
898 unauthorized access using normal file handling mechanisms. Care
899 should be taken, when copying the original files or providing file
900 access for additional users, not to reveal information
901 unintentionally.
903 If the URI method is used for specification of the content-schema,
904 there is a risk that the config schema section in the referenced YANG
905 instance data file may be altered maliciously or even as part of its
906 normal handling. In this case the content-schema might differ from
907 the one expected. Protecting the integrity and stability of the
908 referenced file should be ensured.
910 5. IANA Considerations
912 This document registers one URI and one YANG module.
914 5.1. URI Registration
916 This document registers one URI in the IETF XML registry [RFC3688].
917 Following the format in RFC 3688, the following registration is
918 requested to be made:
920 URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data
921 Registrant Contact: The IESG.
922 XML: N/A, the requested URI is an XML namespace.
924 5.2. YANG Module Name Registration
926 This document registers one YANG module in the YANG Module Names
927 registry [RFC6020]. Following the format in [RFC6020], the following
928 registrations are requested:
930 name: ietf-yang-instance-data
931 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data
932 prefix: yid
933 reference: RFC XXXX
934 // RFC Ed.: replace XXXX with RFC number and remove this note
936 6. Acknowledgments
938 For their valuable comments, discussions, and feedback, we wish to
939 acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe
940 Clarke, Kent Watsen, Martin Bjorklund, Ladislav Lhotka, Qin Wu and
941 other members of the Netmod WG.
943 7. References
945 7.1. Normative References
947 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
948 Requirement Levels", BCP 14, RFC 2119,
949 DOI 10.17487/RFC2119, March 1997,
950 .
952 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
953 Specifications: ABNF", STD 68, RFC 5234,
954 DOI 10.17487/RFC5234, January 2008,
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 v20 - v21
1050 * Minor updates for IESG comments
1052 * Added ABNF as a normative reference for the filename's definition.
1054 * Enhanced security considerations
1056 * Added data change information to the description of the examples.
1058 v19 - v20
1060 * Minor updates for IESG comments
1062 v18 - v19
1064 * Updated leaf includes-defaults
1066 v17 - v18
1068 * Added the report-all-tagged mode to the leaf includes-defaults
1070 v16 - v17
1072 * Removed default statement from includes-default
1074 v15 - v16
1076 * Editorial changes
1078 v14 - v15
1079 * Removed reference to revision-label
1081 * For the inline method made the usage of ietf-yang-
1082 library@2019-01-04 mandatory. Simplified the case "inline" in the
1083 YANG module.
1085 * Removed the "inline-module" leaf as it does not carry useful
1086 information anymore.
1088 * Removed YANG feature
1090 v13 - v14
1092 * Added leaf includes-defaults
1094 * Many small changes based on AD review
1096 v09 - v13
1098 * Editorial updates
1100 v08 - v09
1102 * Removed statement "the format will be similar to the response of a
1103 NETCONF get operation"
1105 * Introduced artwork folding in the examples
1107 v07 - v08
1109 * Moved compatibility into appendix
1111 * Renamed yid-version to format-version. Changed format to date of
1112 the YANG module
1114 * Made support of ietf-yang-library mandatory if inline-content-
1115 schema is supported
1117 * Many small changes based on WGLC
1119 v06 - v07
1121 * Updated terminology, use-cases
1123 * Many small changes based on WGLC
1125 v05 - v06
1126 * Modified module name format, removed .yin or .yang extension
1128 * Removed pattern for module and inline-module. The usage of
1129 revision-label should also be allowed.
1131 v04 - v05
1133 * Updated according to YANG-Doctor review
1135 * Updated security considerations
1137 * Added a wrapping container for the schema, and renamed the data
1138 nodes in the inline and uri cases.
1140 * Allowed .yin for simplified-inline schema naming. Made date
1141 optional if it is unavailable in the YANG module.
1143 * Added a mandatory yid-version to the header metadata to allow
1144 later updates of the module.
1146 v03 - v04
1148 * removed entity-tag and last-modified timestamp
1150 * Added simplified-inline method of content-schema specification
1152 v02 - v03
1154 * target renamed to "content-schema" and "content defining YANG
1155 module(s)"
1157 * Made name of instance data set optional
1159 * Updated according to draft-ietf-netmod-yang-data-ext-03
1161 * Clarified that entity-tag and last-modified timestamp are encoded
1162 as metadata. While they contain useful data, the HTTP-header
1163 based encoding from Restconf is not suitable.
1165 v01 - v02
1167 * Removed design time from terminology
1169 * Defined the format of the content-data part by referencing various
1170 RFCs and drafts instead of the result of the get-data and get
1171 operations.
1173 * Changed target-ptr to a choice
1174 * Inline target-ptr may include augmenting modules and alternatives
1175 to ietf-yang-library
1177 * Moved list of target modules into a separate
1178 element.
1180 * Added backwards compatibility considerations
1182 v00 - v01
1184 * Added the target-ptr metadata with 3 methods
1186 * Added timestamp metadata
1188 * Removed usage of dedicated .yid file extension
1190 * Added list of use cases
1192 * Added list of principles
1194 * Updated examples
1196 * Moved detailed use case descriptions to appendix
1198 Appendix B. Backwards Compatibility
1200 The concept of backwards compatibility and what changes are backwards
1201 compatible are not defined for "instance data sets" as it is highly
1202 dependent on the specific use case and the content-schema.
1204 In case of "instance data sets" that are the result of design or
1205 specification activity, some changes that may be good to avoid are
1206 listed below.
1208 YANG uses the concept of managed entities identified by key values;
1209 if the connection between the represented entity and the key value is
1210 not preserved during an update, this may lead to the following
1211 problems.
1213 * If the key value of a list entry that represents the same managed
1214 entity as before is changed, the user may mistakenly identify the
1215 list entry as new.
1217 * If the meaning of a list entry is changed, but the key values are
1218 not (e.g., redefining an alarm-type but not changing its alarm-
1219 type-id) the change may not be noticed.
1221 * If the key value of a previously removed list entry is reused for
1222 a different entity, the change may be misinterpreted as
1223 reintroducing the previous entity.
1225 Appendix C. Detailed Use Cases
1227 This section is non-normative.
1229 C.1. Use Case 1: Early Documentation of Server Capabilities
1231 A server has a number of server-capabilities that are defined in YANG
1232 modules and can be retrieved from the server using protocols like
1233 NETCONF or RESTCONF. Server capabilities include:
1235 * data defined in "ietf-yang-library": YANG modules, submodules,
1236 features, deviations, schema-mounts, and datastores supported
1237 ([RFC8525])
1239 * alarms supported ([RFC8632])
1241 * data nodes and subtrees that support or do not support on-change
1242 notifications ([RFC8641])
1244 * netconf-capabilities in ietf-netconf-monitoring.
1246 While it is good practice to allow a client to query these
1247 capabilities from the live server, that is often not possible.
1249 Often when a network node is released, an associated NMS (network
1250 management system) is also released with it. The NMS depends on the
1251 capabilities of the server. During NMS implementation, information
1252 about server capabilities is needed. If the information is
1253 unavailable early in some offline document, but only as instance data
1254 from the live network node, the NMS implementation will be delayed,
1255 because it has to wait until the network node is ready. Also
1256 assuming that all NMS implementors will have a correctly configured
1257 network nodes from which data can be retrieved, is a very expensive
1258 proposition. (An NMS may handle dozens of node types.)
1260 Network operators often build their own home-grown NMS systems that
1261 need to be integrated with a vendor's network node. The operator
1262 needs to know the network node's server capabilities in order to do
1263 this. Moreover, the network operator's decision to buy a vendor's
1264 product may even be influenced by the network node's OAM feature set
1265 documented as the server's capabilities.
1267 Beside NMS implementors, system integrators and many others also need
1268 the same information early. Examples could be model driven testing,
1269 generating documentation, etc.
1271 Most server-capabilities are relatively stable and change only during
1272 upgrade or due to licensing or the addition or removal of hardware.
1273 They are usually defined by a vendor at design time, before the
1274 product is released. It is feasible and advantageous to define/
1275 document them early e.g., in a YANG instance data File.
1277 It is anticipated that a separate IETF document will define in detail
1278 how and which set of server capabilities should be documented.
1280 C.2. Use Case 2: Preloading Data
1282 There are parts of the configuration that must be fully configurable
1283 by the operator. However, often a simple default configuration will
1284 be sufficient.
1286 One example is access control groups/roles and related rules. While
1287 a sophisticated operator may define dozens of different groups, often
1288 a basic (read-only operator, read-write system administrator,
1289 security-administrator) triplet will be enough. Vendors will often
1290 provide such default configuration data to make device configuration
1291 easier for an operator.
1293 The device vendor may define a set of default groups (/nacm:nacm/
1294 groups) and rules for these groups to access specific parts of the
1295 common models (/nacm:nacm/rule-list/rule).
1297 YANG instance data files can be used to document and/or preload the
1298 default configuration.
1300 C.3. Use Case 3: Documenting Factory Default Settings
1302 Nearly every server has a factory default configuration. If the
1303 system is really badly misconfigured or if the current configuration
1304 is to be abandoned, the system can be reset to the default factory
1305 configuration.
1307 YANG instance data can be used to document the factory default
1308 configuration. See [RFC8808].
1310 Authors' Addresses
1312 Balazs Lengyel
1313 Ericsson
1314 Email: balazs.lengyel@ericsson.com
1316 Benoit Claise
1317 Huawei
1319 Email: benoit.claise@huawei.com