idnits 2.17.1
draft-ietf-netmod-yang-instance-file-format-10.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 (March 20, 2020) is 1497 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)
== Outdated reference: A later version (-15) exists of
draft-ietf-netmod-factory-default-14
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: September 21, 2020 Cisco Systems, Inc.
6 March 20, 2020
8 YANG Instance Data File Format
9 draft-ietf-netmod-yang-instance-file-format-10
11 Abstract
13 There is a need to document data defined in YANG models when a live
14 server is not available. Data is often needed already at design or
15 implementation time or needed by groups that do not have a live
16 running server available. This document specifies a standard file
17 format for YANG instance data, which follows the syntax and semantics
18 of existing YANG models, and annotates it with metadata.
20 Status of This Memo
22 This Internet-Draft is submitted in full conformance with the
23 provisions of BCP 78 and BCP 79.
25 Internet-Drafts are working documents of the Internet Engineering
26 Task Force (IETF). Note that other groups may also distribute
27 working documents as Internet-Drafts. The list of current Internet-
28 Drafts is at https://datatracker.ietf.org/drafts/current/.
30 Internet-Drafts are draft documents valid for a maximum of six months
31 and may be updated, replaced, or obsoleted by other documents at any
32 time. It is inappropriate to use Internet-Drafts as reference
33 material or to cite them other than as "work in progress."
35 This Internet-Draft will expire on September 21, 2020.
37 Copyright Notice
39 Copyright (c) 2020 IETF Trust and the persons identified as the
40 document authors. All rights reserved.
42 This document is subject to BCP 78 and the IETF Trust's Legal
43 Provisions Relating to IETF Documents
44 (https://trustee.ietf.org/license-info) in effect on the date of
45 publication of this document. Please review these documents
46 carefully, as they describe your rights and restrictions with respect
47 to this document. Code Components extracted from this document must
48 include Simplified BSD License text as described in Section 4.e of
49 the Trust Legal Provisions and are provided without warranty as
50 described in the Simplified BSD License.
52 Table of Contents
54 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2
55 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
56 2.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 4
57 2.2. Delivery of Instance Data . . . . . . . . . . . . . . . . 4
58 2.3. Data Life cycle . . . . . . . . . . . . . . . . . . . . . 5
59 3. Instance Data File Format . . . . . . . . . . . . . . . . . . 5
60 3.1. Specifying the Content Schema . . . . . . . . . . . . . . 7
61 3.1.1. Inline Method . . . . . . . . . . . . . . . . . . . . 7
62 3.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 8
63 3.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 8
64 3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8
65 4. YANG Instance Data Model . . . . . . . . . . . . . . . . . . 12
66 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 12
67 4.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 13
68 5. Security Considerations . . . . . . . . . . . . . . . . . . . 19
69 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
70 6.1. URI Registration . . . . . . . . . . . . . . . . . . . . 19
71 6.2. YANG Module Name Registration . . . . . . . . . . . . . . 20
72 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20
73 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
74 8.1. Normative References . . . . . . . . . . . . . . . . . . 20
75 8.2. Informative References . . . . . . . . . . . . . . . . . 21
76 Appendix A. Changes between revisions . . . . . . . . . . . . . 22
77 Appendix B. Backwards Compatibility . . . . . . . . . . . . . . 24
78 Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 25
79 C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 25
80 C.1.1. Use Case 1: Early Documentation of Server
81 Capabilities . . . . . . . . . . . . . . . . . . . . 25
82 C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 26
83 C.1.3. Use Case 3: Documenting Factory Default Settings . . 27
84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27
86 1. Terminology
88 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
89 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
90 "OPTIONAL" in this document are to be interpreted as described in BCP
91 14 [RFC2119] [RFC8174] when, and only when, they appear in all
92 capitals, as shown here.
94 Instance Data: A collection of instantiated data nodes.
96 Instance Data Set: A named set of data items annotated with metadata
97 that can be used as instance data in a YANG data tree.
99 Instance Data File: A file containing an instance data set formatted
100 according to the rules described in this document.
102 Content-schema: A set of YANG modules with their revision, supported
103 features, and deviations for which the instance data set contains
104 instance data.
106 Content defining YANG module: an individual YANG module that is part
107 of the content-schema.
109 The term Server is used as defined in [RFC8342].
111 2. Introduction
113 There is a need to document data defined in YANG models when a live
114 server is not available. Data is often needed already at design or
115 implementation time or needed by groups that do not have a live
116 running server available. To facilitate this offline delivery of
117 data, this document specifies a standard format for YANG instance
118 data sets and YANG instance data files. The format of the instance
119 data set is defined by the ietf-yang- instance-data YANG module, see
120 Section 4. The YANG data model in this document conforms to the
121 Network Management Datastore Architecture (NMDA) defined in [RFC8342]
123 The following is a list of already implemented and potential use
124 cases.
126 UC1 Documentation of server capabilities
128 UC2 Preloading default configuration data
130 UC3 Documenting Factory Default Settings
132 UC4 Storing the configuration of a device, e.g., for backup, archive
133 or audit purposes
135 UC5 Storing diagnostics data
137 UC6 Allowing YANG instance data to potentially be carried within
138 other IPC message formats
140 UC7 Default instance data used as part of a templating solution
142 UC8 Providing data examples in RFCs or internet drafts
143 In Appendix C we describe the first three use cases in detail.
145 There are many and varied use cases where YANG instance data could be
146 used. We do not want to limit future uses of instance data sets, so
147 specifying how and when to use YANG instance data is out of scope for
148 this document. It is anticipated that other documents will define
149 specific use cases. Use cases are listed here only to indicate the
150 need for this work.
152 2.1. 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 3, 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 actually implemented by a
177 server.
179 P8 It shall be possible to report the identity of the datastore with
180 which the instance data set is associated.
182 2.2. Delivery of Instance Data
184 Instance data sets that are produced as a result of some sort of
185 specification or design effort may be available without the need for
186 a live server e.g., via download from the vendor's website, or in any
187 other way that product documentation is distributed.
189 Other instance data sets may be read from or produced by the YANG
190 server itself e.g., UC5 documenting diagnostic data.
192 2.3. Data Life cycle
194 A YANG instance data set is created at a specific point of time. If
195 the data changes afterwards, this is not represented in the instance
196 data set anymore. The current values may be retrieved at run-time
197 via NETCONF/RESTCONF or received e.g., in YANG-Push notifications.
199 Whether the instance data changes and if so, when and how, should be
200 described either in the instance data set's description statement or
201 in some other implementation specific manner.
203 3. Instance Data File Format
205 A YANG instance data file MUST contain a single instance data set and
206 no additional data.
208 The format of the instance data set is defined by the ietf-yang-
209 instance-data YANG module. It is made up of a header part and
210 content-data. The header part carries metadata for the instance data
211 set. The content-data, defined as an anydata data node, carries the
212 instance data that we want to document/provide. The syntax and
213 semantics of content-data is defined by the content-schema.
215 Two formats are specified based on the XML and JSON YANG encodings.
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 a default attribute as defined in [RFC6243] section 6. and in
228 [RFC8040] section 4.8.9.
230 origin metadata as specified in [RFC8526] and [RFC8527]
232 implementation specific metadata relevant to individual data
233 nodes. Unknown metadata MUST be ignored by users of instance
234 data, allowing it to be used later for other purposes.
236 An instance data set MAY contain data for any number of YANG modules;
237 if needed it MAY carry the complete configuration and state data set
238 for a server. Default values SHOULD NOT be included.
240 Config=true and config=false data MAY be mixed in the instance data
241 file.
243 Instance data files MAY contain partial data sets. This means
244 mandatory, min-elements, require-instance=true, must and when
245 constrains MAY be violated.
247 The name of the instance data file SHOULD take one of the following
248 two forms:
250 If revision information inside the data set is present
252 * instance-data-set-name ['@' revision-date] '.filetype'
254 * E.g., acme-router-modules@2018-01-25.xml
256 If the leaf "name" is present in the instance data header, this
257 MUST be used. If the "revision-date" is present in both the
258 filename and in the instance data header, the revision date in the
259 file name MUST be set to the latest revision date inside the
260 instance data set.
262 If timestamp information inside the data set is present
264 * instance-data-set-name ['@' timestamp] '.filetype'
266 * E.g., acme-router-modules@2018-01-25T15_06_34_3+01_00.json
268 If the leaf "name" is present in the instance data header, this
269 MUST be used. If the "timestamp" is present both in the filename
270 and in the instance data header, the timestamp in the file name
271 MUST be set to the timestamp inside the instance data set; the
272 semicolons and the decimal point, if present, shall be replaced by
273 underscores.
275 The revision date or timestamp is optional. ".filetype" SHALL be
276 ".json" or ".xml" according to the format used.
278 Metadata, information about the data set itself SHOULD be included in
279 the instance data set. Some metadata items are defined in the YANG
280 module ietf-yang-instance-data, but other items MAY also be used.
281 Metadata MUST include:
283 Version of the YANG Instance Data format
285 Metadata SHOULD include:
287 o Name of the data set
288 o Content schema specification
290 o Description of the instance data set. The description SHOULD
291 contain information whether and how the data can change during the
292 lifetime of the server.
294 3.1. Specifying the Content Schema
296 To properly understand and use an instance data set, the user needs
297 to know the content-schema. One of the following methods SHOULD be
298 used:
300 Inline method: Include the needed information as part of the
301 instance data set.
303 Simplified-Inline method: Include the needed information as part
304 of the instance data set; short specification.
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 External Method: Do not include the content-schema, the user needs
312 to obtain the information through external documents.
314 Additional methods e.g., a YANG-package based solution may be added
315 later.
317 Note, the specified content-schema only indicates the set of modules
318 that were used to define this YANG instance data set. Sometimes
319 instance data may be used for a server supporting a different YANG
320 module set. (e.g., for "UC2 Preloading Data" the instance data set
321 may not be updated every time the YANG modules on the server are
322 updated) Whether an instance data set originally defined using a
323 specific content-schema is usable with a different other schema
324 depends on many factors including the amount of differences and the
325 compatibility between the original and the other schema, considering
326 modules, revisions, features, deviations, the scope of the instance
327 data, etc.
329 3.1.1. Inline Method
331 One or more inline-module elements define YANG module(s) used to
332 specify the content defining YANG modules.
334 E.g., ietf-yang-library@2016-06-21
336 The anydata inline-schema carries instance data (conforming to the
337 inline-modules) that actually specifies the content defining YANG
338 modules including revision, supported features, deviations and any
339 relevant additional data (e.g., revision labels
340 [I-D.verdt-netmod-yang-module-versioning]). See Section 3.2.
342 3.1.2. Simplified-Inline Method
344 The instance data set contains a list of content defining YANG
345 modules including the revision date for each. Usage of this method
346 implies that the modules are used without any deviations and with all
347 features supported.
349 3.1.3. URI Method
351 The same-schema-as-file leaf SHALL contain a URI that references
352 another YANG instance data file. The current instance data file will
353 use the same content schema as the referenced file.
355 The referenced instance data file MAY have no content-data if it is
356 used solely for specifying the content-schema.
358 If a referenced instance data file is not available, content-schema
359 is unknown.
361 The URI method is advantageous when the user wants to avoid the
362 overhead of specifying the content-schema in each instance data file:
363 E.g., In Use Case 6, when the system creates a diagnostic file every
364 minute to document the state of the server.
366 3.2. Examples
368 The following examples use artwork folding
369 [I-D.ietf-netmod-artwork-folding] for better formatting.
371 The following example is based on "UC1, Documenting Server
372 Capabilities". It provides (a shortened) list of supported YANG
373 modules and NETCONF capabilities for a server. It uses the inline
374 method to specify the content-schema.
376 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) ===========
378
379
381 acme-router-modules
382
383 ietf-yang-library@2016-06-21
384
385
387
388 ietf-yang-library
389 2016-06-21
390
391
392 ietf-netconf-monitoring
393 2010-10-04
394
395
396
397
398
399 1956-10-23
400 Initial version
401
402 Defines the minimal set of modules that any \
403 acme-router will contain.
404 info@acme.com
405
406
409
411
412 ietf-yang-library
413 2016-06-21
414 \
415 urn:ietf:params:xml:ns:yang:ietf-yang-library\
416
417 implement
418
419
420 ietf-system
421 2014-08-06
422 urn:ietf:params:xml:ns:yang:ietf-system
423 sys:authentication
424 sys:local-users
425
426 acme-system-ext
427 2018-08-06
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: XML Instance Data Set - Use case 1, Documenting server
458 capabilities
460 The following example is based on "UC2, Preloading Default
461 Configuration". It provides a (shortened) default rule set for a
462 read-only operator role. It uses the inline method for specifying
463 the content-schema.
465
466
468 read-only-acm-rules
469
470 ietf-netconf-acm@2018-02-14
471
472
473 1776-07-04
474 Initial version
475
476 Access control rules for a read-only role.
477
478
479 true
480 deny
481 deny
482
483 read-only-role
484 read-only-group
485
486 read-all
487 *
488 read
489 permit
490
491
492
493
494
496 Figure 2: XML Instance Data Set - Use case 2, Preloading access
497 control data
499 The following example is based on UC5 Storing diagnostics data. An
500 instance data set is produced by the server every 15 minutes that
501 contains statistics about NETCONF. As a new set is produced
502 periodically many times a day a revision-date would be useless;
503 instead a timestamp is included.
505 {
506 "ietf-yang-instance-data:instance-data-set": {
507 "name": "acme-router-netconf-diagnostics",
508 "content-schema": {
509 "same-schema-as-file": "file:///acme-diagnostics-schema.json"
510 },
511 "timestamp": "2018-01-25T17:00:38Z",
512 "description": ["NETCONF statistics"],
513 "content-data": {
514 "ietf-netconf-monitoring:netconf-state": {
515 "statistics": {
516 "netconf-start-time ": "2018-12-05T17:45:00Z",
517 "in-bad-hellos ": "32",
518 "in-sessions ": "397",
519 "dropped-sessions ": "87",
520 "in-rpcs ": "8711",
521 "in-bad-rpcs ": "408",
522 "out-rpc-errors ": "408",
523 "out-notifications": "39007"
524 }
525 }
526 }
527 }
528 }
530 Figure 3: JSON Instance Data File example - UC5 Storing diagnostics
531 data
533 4. YANG Instance Data Model
535 4.1. Tree Diagram
537 The following tree diagram [RFC8340] provides an overview of the data
538 model.
540 module: ietf-yang-instance-data
541 structure instance-data-set:
542 +-- name? string
543 +-- format-version? string
544 +-- content-schema
545 | +-- (content-schema-spec)?
546 | +--:(simplified-inline)
547 | | +-- module* string
548 | +--:(inline) {inline-content-schema}?
549 | | +-- inline-module* string
550 | | +-- inline-schema
551 | +--:(uri)
552 | +-- same-schema-as-file? inet:uri
553 +-- description* string
554 +-- contact? string
555 +-- organization? string
556 +-- datastore? ds:datastore-ref
557 +-- revision* [date]
558 | +-- date string
559 | +-- description? string
560 +-- timestamp? yang:date-and-time
561 +-- content-data?
563 4.2. YANG Model
565 This YANG module imports typedefs from [RFC6991], identities from
566 [RFC8342] and the "structure" extension from
567 [I-D.ietf-netmod-yang-data-ext].
569 file "ietf-yang-instance-data@2020-03-19.yang"
570 module ietf-yang-instance-data {
571 yang-version 1.1;
572 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data";
573 prefix yid;
575 import ietf-yang-structure-ext {
576 prefix sx;
577 reference
578 "YANG Data Structure Extensions:
579 draft-ietf-netmod-yang-data-ext-05";
580 }
581 import ietf-datastores {
582 prefix ds;
583 reference
584 "RFC 8342: Network Management Datastore Architecture (NMDA)";
585 }
586 import ietf-inet-types {
587 prefix inet;
588 reference
589 "RFC 6991: Common YANG Data Types";
590 }
591 import ietf-yang-types {
592 prefix yang;
593 reference
594 "RFC 6991: Common YANG Data Types";
595 }
597 organization
598 "IETF NETMOD Working Group";
599 contact
600 "WG Web:
601 WG List:
603 Author: Balazs Lengyel
604 ";
605 description
606 "The module defines the structure and content of YANG
607 instance data sets.
609 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
610 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
611 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
612 are to be interpreted as described in BCP 14 (RFC 2119)
613 (RFC 8174) when, and only when, they appear in all
614 capitals, as shown here.
616 Copyright (c) 2020 IETF Trust and the persons identified as
617 authors of the code. All rights reserved.
619 Redistribution and use in source and binary forms, with or
620 without modification, is permitted pursuant to, and subject
621 to the license terms contained in, the Simplified BSD License
622 set forth in Section 4.c of the IETF Trust's Legal Provisions
623 Relating to IETF Documents
624 (http://trustee.ietf.org/license-info).
626 This version of this YANG module is part of RFC XXXX; see
627 the RFC itself for full legal notices.";
629 revision 2020-03-19 {
630 description
631 "Initial revision.";
632 reference
633 "RFC XXXX: YANG Instance Data Format";
634 }
635 feature inline-content-schema {
636 description
637 "This feature indicates that inline content-schema
638 option is supported.";
639 }
641 sx:structure "instance-data-set" {
642 description
643 "A data structure to define a format for
644 YANG instance data sets. Consists of meta-data about
645 the instance data set and the real content-data.";
646 leaf name {
647 type string;
648 description
649 "An arbitrary name for the YANG instance data set. This
650 value is primarily used for descriptive purposes. However,
651 when the instance data set is saved to a file, then the
652 filename MUST encode the name's value, per Section 3
653 of RFC XXXX.";
654 }
655 leaf format-version {
656 type string {
657 pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
658 }
659 default "2020-03-19";
660 description
661 "Version of the 'YANG Instance Data format'.
663 It SHALL contain the revision date of the
664 ietf-yang-instance-data module used when creating the
665 instance data set in a YYYY-MM-DD format";
666 }
667 container content-schema {
668 description
669 "The content schema used to create the instance data set.
670 If not present the user needs to obtain the information
671 through external documents.";
672 choice content-schema-spec {
673 description
674 "Specification of the content-schema.";
675 case simplified-inline {
676 leaf-list module {
677 type string;
678 description
679 "The list of content defining YANG modules.
681 The value SHALL start with the module name.
682 If the module contains a revision statement the
683 revision date SHALL be included in the leaf-list
684 entry. If other methods (e.g., revision-label) are
685 defined to identify individual module revisions
686 those MAY be used instead of using a revision date.
688 E.g., ietf-yang-library@2016-06-21
690 Usage of this leaf-list implies the modules are
691 used without any deviations and with all features
692 supported. Multiple revisions of the same module
693 MUST NOT be specified.";
694 }
695 }
696 case inline {
697 if-feature "inline-content-schema";
698 leaf-list inline-module {
699 type string;
700 min-elements 1;
701 ordered-by user;
702 description
703 "Indicates that content defining YANG modules
704 are specified inline.
706 The value SHALL start with the module name.
707 If the module contains a revision statement the
708 revision date SHALL be included in the leaf-list
709 entry. If other methods (e.g., revision-label) are
710 defined to identify individual module revisions
711 those MAY be used instead of using a revision date.
713 E.g., ietf-yang-library@2016-06-21
715 The first item is either ietf-yang-library or some
716 other YANG module that contains a list of YANG modules
717 with their name, revision-date, supported-features,
718 and deviations. The usage of
719 ietf-yang-library@2019-01-04 MUST be supported.
720 Using other modules, module versions MAY also be
721 supported.
723 As some versions of ietf-yang-library MAY contain
724 different module-sets for different datastores, if
725 multiple module-sets are included, the instance data
726 set's meta-data MUST contain the datastore information
727 and instance data for the ietf-yang-library MUST also
728 contain information specifying the module-set for the
729 relevant datastore.
731 Subsequent items MAY specify YANG modules augmenting
732 the first module with useful data
733 (e.g., revision label).";
734 }
735 anydata inline-schema {
736 mandatory true;
737 description
738 "Instance data corresponding to the YANG modules
739 specified in the inline-module nodes defining the set
740 of content defining YANG modules for this
741 instance-data-set.";
742 }
743 }
744 case uri {
745 leaf same-schema-as-file {
746 type inet:uri;
747 description
748 "A reference to another YANG instance data file.
749 This instance data file uses the same
750 content schema as the referenced file.";
751 }
752 }
753 }
754 }
755 leaf-list description {
756 type string;
757 description
758 "Description of the instance data set.";
759 }
760 leaf contact {
761 type string;
762 description
763 "Contact information for the person or
764 organization to whom queries concerning this
765 instance data set should be sent.";
766 }
767 leaf organization {
768 type string;
769 description
770 "Organization responsible for the instance
771 data set.";
772 }
773 leaf datastore {
774 type ds:datastore-ref;
775 description
776 "The identity of the datastore with which the
777 instance data set is associated, e.g., the datastore from
778 where the data was read or the datastore into which the data
779 may be loaded or the datastore which is being documented.
780 If a single specific datastore cannot be specified, the
781 leaf MUST be absent.
783 If this leaf is absent, then the datastore to which the
784 instance data belongs is undefined.";
785 }
786 list revision {
787 key "date";
788 description
789 "Instance data sets that are produced as
790 a result of some sort of specification or design effort
791 SHOULD have at least one revision entry. For every
792 published editorial change, a new one SHOULD be added
793 in front of the revisions sequence so that all
794 revisions are in reverse chronological order.
796 For instance data sets that are read from
797 or produced by a server or otherwise
798 subject to frequent updates or changes, revision
799 SHOULD NOT be present";
800 leaf date {
801 type string {
802 pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])';
803 }
804 description
805 "Specifies the date the instance data set
806 was last modified. Formatted as YYYY-MM-DD";
807 }
808 leaf description {
809 type string;
810 description
811 "Description of this revision of the instance data set.";
812 }
813 }
814 leaf timestamp {
815 type yang:date-and-time;
816 description
817 "The date and time when the instance data set
818 was last modified.
820 For instance data sets that are read from or produced
821 by a server or otherwise subject to frequent
822 updates or changes, timestamp SHOULD be present";
823 }
824 anydata content-data {
825 description
826 "Contains the real instance data.
828 The data MUST conform to the relevant YANG Modules specified
829 either in the content-schema-spec or in some other
830 implementation specific manner.";
831 }
832 }
833 }
834
836 5. Security Considerations
838 The YANG module defined in this document is designed as a wrapper
839 specifying a format and a metadata header for YANG instance data
840 defined by the content-schema. The data is designed to be accessed
841 as a stored file or over any file access method or protocol.
843 The document does not specify any method to influence the behavior of
844 a server.
846 Instance data files may contain sensitive data.
848 The header part is not security sensitive.
850 The security sensitivity of the instance data in the content part is
851 completely dependent on the content schema. Depending on the nature
852 of the instance data, instance data files MAY need to be handled in a
853 secure way. The same kind of handling should be applied, that would
854 be needed for the result of a read operation returning the same data.
856 Instance data files should be protected against modification or
857 unauthorized access using normal file handling mechanisms. Care
858 should be taken, when copying the original files or providing file
859 access for additional users, not to reveal information
860 unintentionally.
862 6. IANA Considerations
864 This document registers one URI and one YANG module.
866 6.1. URI Registration
868 This document registers one URI in the IETF XML registry [RFC3688].
869 Following the format in RFC 3688, the following registration is
870 requested to be made:
872 URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data
874 Registrant Contact: The IESG.
876 XML: N/A, the requested URI is an XML namespace.
878 6.2. YANG Module Name Registration
880 This document registers one YANG module in the YANG Module Names
881 registry [RFC6020].
883 name: ietf-yang-instance-data
884 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data
885 prefix: yid
886 reference: RFC XXXX
888 7. Acknowledgments
890 For their valuable comments, discussions, and feedback, we wish to
891 acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe
892 Clarke, Kent Watsen Martin Bjorklund, Ladislav Lhotka, Qin Wu and
893 other members of the Netmod WG.
895 8. References
897 8.1. Normative References
899 [I-D.ietf-netmod-yang-data-ext]
900 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data
901 Structure Extensions", draft-ietf-netmod-yang-data-ext-05
902 (work in progress), December 2019.
904 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
905 Requirement Levels", BCP 14, RFC 2119,
906 DOI 10.17487/RFC2119, March 1997,
907 .
909 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for
910 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011,
911 .
913 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
914 RFC 6991, DOI 10.17487/RFC6991, July 2013,
915 .
917 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
918 RFC 7950, DOI 10.17487/RFC7950, August 2016,
919 .
921 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
922 RFC 7951, DOI 10.17487/RFC7951, August 2016,
923 .
925 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG",
926 RFC 7952, DOI 10.17487/RFC7952, August 2016,
927 .
929 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
930 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
931 .
933 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
934 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
935 May 2017, .
937 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
938 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
939 .
941 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
942 and R. Wilton, "Network Management Datastore Architecture
943 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
944 .
946 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
947 and R. Wilton, "YANG Library", RFC 8525,
948 DOI 10.17487/RFC8525, March 2019,
949 .
951 [RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
952 and R. Wilton, "NETCONF Extensions to Support the Network
953 Management Datastore Architecture", RFC 8526,
954 DOI 10.17487/RFC8526, March 2019,
955 .
957 [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
958 and R. Wilton, "RESTCONF Extensions to Support the Network
959 Management Datastore Architecture", RFC 8527,
960 DOI 10.17487/RFC8527, March 2019,
961 .
963 8.2. Informative References
965 [I-D.ietf-netmod-artwork-folding]
966 Watsen, K., Auerswald, E., Farrel, A., and Q. WU,
967 "Handling Long Lines in Inclusions in Internet-Drafts and
968 RFCs", draft-ietf-netmod-artwork-folding-12 (work in
969 progress), January 2020.
971 [I-D.ietf-netmod-factory-default]
972 WU, Q., Lengyel, B., and Y. Niu, "A YANG Data Model for
973 Factory Default Settings", draft-ietf-netmod-factory-
974 default-14 (work in progress), February 2020.
976 [I-D.verdt-netmod-yang-module-versioning]
977 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel,
978 B., Sterne, J., and K. D'Souza, "Updated YANG Module
979 Revision Handling", draft-verdt-netmod-yang-module-
980 versioning-01 (work in progress), October 2019.
982 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
983 DOI 10.17487/RFC3688, January 2004,
984 .
986 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
987 the Network Configuration Protocol (NETCONF)", RFC 6020,
988 DOI 10.17487/RFC6020, October 2010,
989 .
991 [RFC8632] Vallin, S. and M. Bjorklund, "A YANG Data Model for Alarm
992 Management", RFC 8632, DOI 10.17487/RFC8632, September
993 2019, .
995 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications
996 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641,
997 September 2019, .
999 Appendix A. Changes between revisions
1001 Note to RFC Editor (To be removed by RFC Editor)
1003 v09 - v10
1005 o Editorial updates
1007 v08 - v09
1009 o Removed reference to similar to get reply
1011 o Introduced artwork folding in the examples
1013 v07 - v08
1015 o Moved compatibility into appendix
1017 o Renamed yid-version to format-version. Changed format to date of
1018 the YANG module
1020 o Made support of ietf-yang-library mandatory if inline-content-
1021 schema is supported
1023 o Many small changes based on WGLC
1025 v06 - v07
1027 o Updated terminology, use-cases
1029 o Many small changes based on WGLC
1031 v05 - v06
1033 o Modified module name format, removed .yin or .yang extension
1035 o Removed pattern for module and inline-module. We want to allow
1036 the usage of revision-label later
1038 v04 - v05
1040 o Updated according to YANG-Doctor review
1042 o Updated security considerations
1044 o Added a wrapping container for the schema, and renamed the data
1045 nodes in the inline and uri cases.
1047 o Allowed .yin for simplified-inline schema naming. Made date
1048 optional if it is not available in the YANG module.
1050 o Added a mandatory yid-version to the header metadata to allow
1051 later updates of the module.
1053 v03 - v04
1055 o removed entity-tag and last-modified timestamp
1057 o Added simplified-inline method of content-schema specification
1059 v02 - v03
1061 o target renamed to "content-schema" and "content defining YANG
1062 module(s)"
1064 o Made name of instance data set optional
1066 o Updated according to draft-ietf-netmod-yang-data-ext-03
1067 o Clarified that entity-tag and last-modified timestamp are encoded
1068 as metadata. While they contain useful data, the HTTP-header
1069 based encoding from Restconf is not suitable.
1071 v01 - v02
1073 o Removed design time from terminology
1075 o Defined the format of the content-data part by referencing various
1076 RFCs and drafts instead of the result of the get-data and get
1077 operations.
1079 o Changed target-ptr to a choice
1081 o Inline target-ptr may include augmenting modules and alternatives
1082 to ietf-yang-library
1084 o Moved list of target modules into a separate
1085 element.
1087 o Added backwards compatibility considerations
1089 v00 - v01
1091 o Added the target-ptr metadata with 3 methods
1093 o Added timestamp metadata
1095 o Removed usage of dedicated .yid file extension
1097 o Added list of use cases
1099 o Added list of principles
1101 o Updated examples
1103 o Moved detailed use case descriptions to appendix
1105 Appendix B. Backwards Compatibility
1107 The concept of backwards compatibility and what changes are backwards
1108 compatible are not defined for instance data sets as it is highly
1109 dependent on the specific use case and the content-schema.
1111 For instance data that is the result of a design or specification
1112 activity, some changes that may be good to avoid are listed. YANG
1113 uses the concept of managed entities identified by key values; if the
1114 connection between the represented entity and the key value is not
1115 preserved during an update, this may lead to problems.
1117 o If the key value of a list entry that represents the same managed
1118 entity as before is changed, the user may mistakenly identify the
1119 list entry as new.
1121 o If the meaning of a list entry is changed, but the key values are
1122 not (e.g., redefining an alarm-type but not changing its alarm-
1123 type-id) the change may not be noticed.
1125 o If the key value of a previously removed list entry is reused for
1126 a different entity, the change may be misinterpreted as
1127 reintroducing the previous entity.
1129 Appendix C. Detailed Use Cases - Non-Normative
1131 C.1. Use Cases
1133 We present a number of use cases were YANG instance data is needed.
1135 C.1.1. Use Case 1: Early Documentation of Server Capabilities
1137 A server has a number of server-capabilities that are defined in YANG
1138 modules and can be retrieved from the server using protocols like
1139 NETCONF or RESTCONF. Server capabilities include:
1141 o data defined in ietf-yang-library: YANG modules, submodules,
1142 features, deviations, schema-mounts, and datastores supported
1143 ([RFC8525])
1145 o alarms supported ([RFC8632])
1147 o data nodes and subtrees that support or do not support on-change
1148 notifications ([RFC8641])
1150 o netconf-capabilities in ietf-netconf-monitoring
1152 While it is good practice to allow a client to query these
1153 capabilities from the live server, that is often not possible.
1155 Often when a network node is released, an associated NMS (network
1156 management system) is also released with it. The NMS depends on the
1157 capabilities of the server. During NMS implementation, information
1158 about server capabilities is needed. If the information is not
1159 available early in some offline document, but only as instance data
1160 from the live network node, the NMS implementation will be delayed,
1161 because it has to wait until the network node is ready. Also
1162 assuming that all NMS implementors will have a correctly configured
1163 network nodes from which data can be retrieved, is a very expensive
1164 proposition. (An NMS may handle dozens of node types.)
1166 Network operators often build their own home-grown NMS systems that
1167 need to be integrated with a vendor's network node. The operator
1168 needs to know the network node's server capabilities in order to do
1169 this. Moreover, the network operator's decision to buy a vendor's
1170 product may even be influenced by the network node's OAM feature set
1171 documented as the server's capabilities.
1173 Beside NMS implementors, system integrators and many others also need
1174 the same information early. Examples could be model driven testing,
1175 generating documentation, etc.
1177 Most server-capabilities are relatively stable and change only during
1178 upgrade or due to licensing or the addition or removal of hardware.
1179 They are usually defined by a vendor at design time, before the
1180 product is released. It is feasible and advantageous to define/
1181 document them early e.g., in a YANG instance data File.
1183 It is anticipated that a separate IETF document will define in detail
1184 how and which set of server capabilities should be documented.
1186 C.1.2. Use Case 2: Preloading Data
1188 There are parts of the configuration that must be fully configurable
1189 by the operator. However, often a simple default configuration will
1190 be sufficient.
1192 One example is access control groups/roles and related rules. While
1193 a sophisticated operator may define dozens of different groups, often
1194 a basic (read-only operator, read-write system administrator,
1195 security-administrator) triplet will be enough. Vendors will often
1196 provide such default configuration data to make device configuration
1197 easier for an operator.
1199 Defining access control data is a complex task. To help, the device
1200 vendor predefines a set of default groups (/nacm:nacm/groups) and
1201 rules for these groups to access specific parts of common models
1202 (/nacm:nacm/rule-list/rule).
1204 YANG instance data files are used to document and/or preload the
1205 default configuration.
1207 C.1.3. Use Case 3: Documenting Factory Default Settings
1209 Nearly every server has a factory default configuration. If the
1210 system is really badly misconfigured or if the current configuration
1211 is to be abandoned, the system can be reset the default factory
1212 configuration.
1214 In NETCONF, the operation can already be used to
1215 reset the startup datastore. There are ongoing efforts to introduce
1216 a new, more generic factory-reset operation for the same purpose
1217 [I-D.ietf-netmod-factory-default]
1219 The operator currently has no way to know what the default
1220 configuration actually contains. YANG instance data can also be used
1221 to document the factory default configuration.
1223 Authors' Addresses
1225 Balazs Lengyel
1226 Ericsson
1227 Magyar Tudosok korutja 11
1228 1117 Budapest
1229 Hungary
1231 Phone: +36-70-330-7909
1232 Email: balazs.lengyel@ericsson.com
1234 Benoit Claise
1235 Cisco Systems, Inc.
1236 De Kleetlaan 6a b1
1237 1831 Diegem
1238 Belgium
1240 Phone: +32 2 704 5622
1241 Email: bclaise@cisco.com