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