idnits 2.17.1 draft-ietf-netmod-yang-instance-file-format-20.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 (5 October 2021) is 933 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: 8 April 2022 Huawei 6 5 October 2021 8 YANG Instance Data File Format 9 draft-ietf-netmod-yang-instance-file-format-20 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 8 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 . . . . . . . . . . . . . . . . . . . . 7 60 2.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 8 61 2.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 8 62 2.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 63 2.2.1. Documentation of server capabilities . . . . . . . . 8 64 2.2.2. Preloading default configuration data . . . . . . . . 10 65 2.2.3. Storing diagnostics data . . . . . . . . . . . . . . 11 66 3. YANG Instance Data Model . . . . . . . . . . . . . . . . . . 12 67 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 12 68 3.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 13 69 4. Security Considerations . . . . . . . . . . . . . . . . . . . 19 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 71 5.1. URI Registration . . . . . . . . . . . . . . . . . . . . 20 72 5.2. YANG Module Name Registration . . . . . . . . . . . . . . 20 73 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20 74 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 75 7.1. Normative References . . . . . . . . . . . . . . . . . . 20 76 7.2. Informative References . . . . . . . . . . . . . . . . . 22 77 Appendix A. Changes between revisions . . . . . . . . . . . . . 22 78 Appendix B. Backwards Compatibility . . . . . . . . . . . . . . 26 79 Appendix C. Detailed Use Cases . . . . . . . . . . . . . . . . . 26 80 C.1. Use Case 1: Early Documentation of Server Capabilities . 26 81 C.2. Use Case 2: Preloading Data . . . . . . . . . . . . . . . 27 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 In Appendix C describes the first three use cases in detail. 119 There are many and varied use cases where YANG instance data could be 120 used. This document does not limit future uses of instance data 121 sets, so specifying how and when to use YANG instance data is out of 122 scope for this document. It is anticipated that other documents will 123 define specific use cases. Use cases are listed only as examples. 125 1.1. Terminology 127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 128 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 129 "OPTIONAL" in this document are to be interpreted as described in BCP 130 14 [RFC2119] [RFC8174] when, and only when, they appear in all 131 capitals, as shown here. 133 Instance Data: A collection of instantiated data nodes. 135 Instance Data Set: A named set of data items annotated with metadata 136 that can be used as instance data in a YANG data tree. 138 Instance Data File: A file containing an instance data set formatted 139 according to the rules described in this document. 141 Content-schema: A set of YANG modules with their revision, supported 142 features, and deviations for which the instance data set contains 143 instance data. 145 Content defining YANG module: an individual YANG module that is part 146 of the content-schema. 148 The term "server" is used as defined in [RFC8342]. 150 1.2. Principles 152 The following is a list of the basic principles of the instance data 153 format: 155 P1 Two standard formats shall be defined based on the XML and JSON 156 encodings. 158 P2 Instance data shall reuse existing encoding rules for YANG 159 defined data. 161 P3 Metadata about the instance data set (Section 2, Paragraph 12) 162 shall be defined. 164 P4 A YANG instance data set shall be allowed to contain data for 165 multiple YANG modules. 167 P5 Instance data shall be allowed to contain configuration data, 168 state data, or a mix of the two. 170 P6 Partial data sets shall be allowed. 172 P7 The YANG instance data format shall be usable for any data for 173 which YANG module(s) are defined and available to the reader, 174 independent of whether the module is implemented by a server. 176 P8 It shall be possible to report the identity of the datastore with 177 which the instance data set is associated. 179 1.3. Delivery of Instance Data 181 Instance data sets that are produced as a result of some sort of 182 specification or design effort may be available without the need for 183 a live server e.g., via download from the vendor's website, or in any 184 other way that product documentation is distributed. 186 Other instance data sets may be read from or produced by the YANG 187 server itself e.g., UC5 documenting diagnostic data. 189 1.4. Data Life cycle 191 A YANG instance data set is created at a specific point of time. If 192 the data changes afterwards, this is not represented in the instance 193 data set anymore. The current values may be retrieved at run-time 194 via NETCONF/RESTCONF or received e.g., in YANG-Push notifications. 196 Whether the instance data changes and if so, when and how, should be 197 described either in the instance data set's description statement or 198 in some other implementation specific manner. 200 2. Instance Data File Format 202 A YANG instance data file MUST contain a single instance data set and 203 no additional data. 205 The format of the instance data set is defined by the "ietf-yang- 206 instance-data" YANG module. It is made up of a header part and 207 content-data. The header part carries metadata for the instance data 208 set. The content-data, defined as an anydata data node, carries the 209 instance data that the user wants to document/provide. The syntax 210 and semantics of content-data is defined by the content-schema. 212 Two formats are specified based on the XML and JSON YANG encodings. 213 Later, as other YANG encodings (e.g., CBOR) are defined, further 214 instance data formats may be specified. 216 The content-data part MUST conform to the content-schema, while 217 allowing for the exceptions listed below. The content-data part 218 SHALL follow the encoding rules defined in [RFC7950] for XML and 219 [RFC7951] for JSON and MUST use UTF-8 character encoding. Content- 220 data MAY include: 222 * metadata, as defined by [RFC7952]. 224 * origin metadata, as specified in [RFC8526] and [RFC8527] 226 * implementation specific metadata relevant to individual data 227 nodes. Unknown metadata MUST be ignored by users of instance 228 data, allowing it to be used later for other purposes. 230 An instance data set MAY contain data for any number of YANG modules; 231 if needed it MAY carry the complete configuration and state data for 232 a server. Default values should be excluded where they do not 233 provide additional useful data. 235 Configuration ("config true") and operational state data ("config 236 false") MAY be mixed in the instance data file. 238 Instance data files MAY contain partial data sets. This means 239 "mandatory", "min-elements", "require-instance true", "must" and 240 "when" constrains MAY be violated. 242 The name of the instance data file SHOULD be of the form: 244 instance-data-set-name ['@' ( revision-date / timestamp ) ] 245 ( '.xml' / '.json' ) 247 E.g., acme-router-modules.xml 248 E.g., acme-router-modules@2018-01-25.xml 249 E.g., acme-router-modules@2018-01-25T15_06_34_3+01_00.json 251 If the leaf "name" is present in the instance data header, its value 252 SHOULD be used for the "instance-data-set-name". If the "revision- 253 date" is present in the filename it MUST conform to the format of the 254 revision-date leaf in the YANG model. If the "revision-date" is 255 present in both the filename and in the instance data header, the 256 revision date in the file name MUST be set to the latest revision 257 date inside the instance data set. If the "timestamp" is present in 258 the filename it MUST conform to the format of the timestamp leaf in 259 the YANG model except for replacing colons as described below. If 260 the "timestamp" is present both in the filename and in the instance 261 data header, the timestamp in the file name SHOULD be set to the 262 timestamp inside the instance data set; any colons, if present, shall 263 be replaced by underscores. 265 Metadata, information about the data set itself SHOULD be included in 266 the instance data set. Some metadata items are defined in the YANG 267 module "ietf-yang-instance-data", but other items MAY be used. 269 Metadata MUST include: 271 - Version of the YANG Instance Data format 273 Metadata SHOULD include: 275 - Name of the data set 277 - Content schema specification (i.e., the "content-schema" node) 279 - Description of the instance data set. The description SHOULD 280 contain information whether and how the data can change during 281 the lifetime of the server 283 - An indication whether default values are included. The default 284 handling uses the concepts defined in [RFC6243], however as 285 only concepts are re-used, users of instance data sets, do not 286 need to support RFC 6243. 288 2.1. Specifying the Content Schema 290 To properly understand and use an instance data set, the user needs 291 to know the content-schema. One of the following methods MUST be 292 used: 294 Inline method: Include the needed information as part of the 295 instance data set. 297 Simplified-Inline method: Include the needed information as part 298 of the instance data set; short specification, only the module 299 name and revision-date is used. 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 Section 2.2.1. 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 Section 2.2.2. 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 Section 2.2.3. 362 2.2. Examples 364 2.2.1. Documentation of server capabilities 366 The example file acme-router-modules@2021-09-16.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 421 422 implement 423 424 425 ietf-netconf-monitoring 426 2010-10-04 427 \ 428 urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring\ 429 430 implement 431 432 433 ietf-yang-types 434 2013-07-15 435 urn:ietf:params:xml:ns:yang:ietf-yang-types\ 436 437 import 438 439 440 acme-system-ext 441 2018-08-06 442 urn:rdns:acme.com:oammodel:acme-system-ext\ 443 444 implement 445 446 447 449 450 \ 451 urn:ietf:params:netconf:capability:validate:1.1\ 452 453 454 455 456 458 Figure 1 460 2.2.2. Preloading default configuration data 462 The example file read-only-acm-rules@2021-09-16.xml reflects UC2 in 463 Section 1. It provides a default rule set for a read-only operator 464 role. It uses the "simplified-inline" method for specifying the 465 content-schema. 467 468 470 read-only-acm-rules 471 472 ietf-netconf-acm@2018-02-14 473 474 475 1776-07-04 476 Initial version 477 478 Access control rules for a read-only role. 479 480 481 true 482 deny 483 deny 484 485 read-only-role 486 read-only-group 487 488 read-all 489 * 490 read 491 permit 492 493 494 495 496 498 Figure 2 500 2.2.3. Storing diagnostics data 502 The example file acme-router-netconf- 503 diagnostics@2018-01-25T17_00_38Z.json reflects UC5 in Section 1. An 504 instance data set is produced by the server every 15 minutes that 505 contains statistics about the NETCONF server. As a new set is 506 produced periodically many times a day a revision-date would be 507 useless; instead a timestamp is included. 509 { 510 "ietf-yang-instance-data:instance-data-set": { 511 "name": "acme-router-netconf-diagnostics", 512 "content-schema": { 513 "same-schema-as-file": "file:///acme-diagnostics-schema.json" 514 }, 515 "timestamp": "2018-01-25T17:00:38Z", 516 "description": ["NETCONF statistics"], 517 "content-data": { 518 "ietf-netconf-monitoring:netconf-state": { 519 "statistics": { 520 "netconf-start-time ": "2018-12-05T17:45:00Z", 521 "in-bad-hellos ": "32", 522 "in-sessions ": "397", 523 "dropped-sessions ": "87", 524 "in-rpcs ": "8711", 525 "in-bad-rpcs ": "408", 526 "out-rpc-errors ": "408", 527 "out-notifications": "39007" 528 } 529 } 530 } 531 } 532 } 534 Figure 3 536 3. YANG Instance Data Model 538 3.1. Tree Diagram 540 The following tree diagram [RFC8340] provides an overview of the data 541 model. 543 module: ietf-yang-instance-data 545 structure instance-data-set: 546 +-- name? string 547 +-- format-version? string 548 +-- includes-defaults? enumeration 549 +-- content-schema 550 | +-- (content-schema-spec)? 551 | +--:(simplified-inline) 552 | | +-- module* module-with-revision-date 553 | +--:(inline) 554 | | +-- inline-yang-library 555 | +--:(uri) 556 | +-- same-schema-as-file? inet:uri 557 +-- description* string 558 +-- contact? string 559 +-- organization? string 560 +-- datastore? ds:datastore-ref 561 +-- revision* [date] 562 | +-- date string 563 | +-- description? string 564 +-- timestamp? yang:date-and-time 565 +-- content-data? 567 3.2. YANG Model 569 This YANG module imports typedefs from [RFC6991], [RFC6243], 570 identities from [RFC8342] and the "structure" extension from 571 [RFC8791]. It also references [RFC8525]. 573 file "ietf-yang-instance-data@2021-09-16.yang" 574 // RFC Ed.: replace the date above if the module gets changed in 575 //any way during reviews or RFC editor process and remove this note 576 module ietf-yang-instance-data { 577 yang-version 1.1; 578 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"; 579 prefix yid; 581 import ietf-yang-structure-ext { 582 prefix sx; 583 reference 584 "YANG Data Structure Extensions: 585 draft-ietf-netmod-yang-data-ext-05"; 586 } 587 import ietf-datastores { 588 prefix ds; 589 reference 590 "RFC 8342: Network Management Datastore Architecture (NMDA)"; 592 } 593 import ietf-inet-types { 594 prefix inet; 595 reference 596 "RFC 6991: Common YANG Data Types"; 597 } 598 import ietf-yang-types { 599 prefix yang; 600 reference 601 "RFC 6991: Common YANG Data Types"; 602 } 604 import ietf-netconf-with-defaults { 605 prefix ncwd; 606 reference 607 "RFC 6243: With-defaults Capability for NETCONF"; 608 } 610 organization 611 "IETF NETMOD Working Group"; 612 contact 613 "WG Web: 614 WG List: 616 Author: Balazs Lengyel 617 619 Author: Benoit Claise 620 "; 621 description 622 "The module defines the structure and content of YANG 623 instance data sets. 625 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 626 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 627 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 628 are to be interpreted as described in BCP 14 (RFC 2119) 629 (RFC 8174) when, and only when, they appear in all 630 capitals, as shown here. 632 Copyright (c) 2021 IETF Trust and the persons identified as 633 authors of the code. All rights reserved. 635 Redistribution and use in source and binary forms, with or 636 without modification, is permitted pursuant to, and subject 637 to the license terms contained in, the Simplified BSD License 638 set forth in Section 4.c of the IETF Trust's Legal Provisions 639 Relating to IETF Documents 640 (http://trustee.ietf.org/license-info). 642 This version of this YANG module is part of RFC XXXX; see 643 the RFC itself for full legal notices."; 644 // RFC Ed.: replace XXXX with RFC number and remove this note 646 revision 2021-09-16 { 647 // RFC Ed.: replace the date above if the module gets changed in 648 // anyway during reviews or RFC editor process and remove 649 //this note 650 description 651 "Initial revision."; 652 reference 653 "RFC XXXX: YANG Instance Data Format"; 654 // RFC Ed.: replace XXXX with RFC number and remove this note 655 } 657 typedef module-with-revision-date { 658 type string { 659 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*' 660 + '(@\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1]))?'; 661 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 662 } 663 description 664 "A type defining a module name and an optional revision 665 date, e.g. ietf-yang-library@2019-01-04"; 666 } 668 sx:structure "instance-data-set" { 669 description 670 "A data structure to define a format for YANG instance 671 data. The majority of the YANG nodes provide meta-data 672 about the instance data; the instance data itself is 673 contained only in the 'content-data' node."; 674 leaf name { 675 type string; 676 description 677 "An arbitrary name for the YANG instance data set. This 678 value is primarily used for descriptive purposes. However, 679 when the instance data set is saved to a file, then the 680 filename MUST encode the name's value, per Section 3 681 of RFC XXXX."; 682 // RFC Ed.: replace XXXX with RFC number and remove this note 683 } 684 leaf format-version { 685 type string { 686 pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])'; 687 } 688 default "2021-09-16"; 689 // RFC Ed.: replace the date above if the module gets changed 690 // in anyway during reviews or RFC editor process and remove 691 // this note 692 description 693 "The 'revision' of the 'ietf-yang-instance-data' module 694 used to encode this 'instance-data-set'."; 695 } 696 leaf includes-defaults { 697 type ncwd:with-defaults-mode; 698 default report-all; 699 description " 700 Indicates how data nodes with default values are 701 represented for all data nodes contained in the 702 instance-data-set. 704 It uses the same definitions as per section 3 of RFC 6243, 705 but applied in the context of an instance data file rather 706 than a NETCONF request using the 707 parameter. 709 For JSON files, the encoding of the 'report-all-tagged' 710 option is as defined in section 4.8.9 of RFC 8040."; 711 reference "With-defaults Capability for NETCONF, RFC 6243."; 712 } 713 container content-schema { 714 description 715 "The content schema (i.e., YANG modules) used to create 716 the instance data set. 717 If not present the user needs to obtain the information 718 through external documents."; 719 choice content-schema-spec { 720 description 721 "Specification of the content-schema."; 722 case simplified-inline { 723 leaf-list module { 724 type module-with-revision-date; 725 min-elements 1; 726 description 727 "The list of content defining YANG modules. 729 The value SHALL start with the module name. 730 If the module contains a revision statement the 731 revision date SHALL be included in the leaf-list 732 entry. 734 E.g., ietf-yang-library@2019-01-04 735 Usage of this leaf-list implies the modules are 736 used without any deviations and with all features 737 supported. Multiple revisions of the same module 738 MUST NOT be specified."; 739 } 740 } 741 case inline { 742 anydata inline-yang-library { 743 mandatory true; 744 description 745 "Instance data corresponding to the 746 ietf-yang-library@2019-01-04 defining 747 the set of content defining YANG modules for 748 this instance-data-set."; 749 } 750 } 751 case uri { 752 leaf same-schema-as-file { 753 type inet:uri; 754 description 755 "A reference to another YANG instance data file. 756 This instance data file uses the same 757 content schema as the referenced file. 759 Referenced files using the 'inline' or the 760 'simplified-inline' methods MUST be supported. 761 Referenced files using the 'URI Method' MAY be 762 supported. 764 The URL schemes 'file://' and 'https://' MUST 765 be supported, other schemes MAY also be 766 supported."; 767 } 768 } 769 } 770 } 771 leaf-list description { 772 type string; 773 description 774 "Description of the instance data set."; 775 } 776 leaf contact { 777 type string; 778 description 779 "Contact information for the person or 780 organization to whom queries concerning this 781 instance data set should be sent."; 782 } 783 leaf organization { 784 type string; 785 description 786 "Organization responsible for the instance 787 data set."; 788 } 789 leaf datastore { 790 type ds:datastore-ref; 791 description 792 "The identity of the datastore with which the 793 instance data set is associated, e.g., the datastore from 794 where the data was read or the datastore into which the data 795 may be loaded or the datastore which is being documented. 796 If a single specific datastore cannot be specified, the 797 leaf MUST be absent. 799 If this leaf is absent, then the datastore to which the 800 instance data belongs is unspecified."; 801 } 802 list revision { 803 key "date"; 804 description 805 "Instance data sets that are produced as 806 a result of some sort of specification or design effort 807 SHOULD have at least one revision entry. For every 808 published editorial change, a new unique revision SHOULD 809 be added in front of the revisions sequence so that all 810 revisions are in reverse chronological order. 812 In case of instance data sets that are read from 813 or produced by a server or otherwise subject to 814 frequent updates or changes, revision 815 SHOULD NOT be present"; 816 leaf date { 817 type string { 818 pattern '\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1])'; 819 } 820 description 821 "Specifies the date the instance data set 822 was last modified. Formatted as YYYY-MM-DD"; 823 } 824 leaf description { 825 type string; 826 description 827 "Description of this revision of the instance data set."; 828 } 829 } 830 leaf timestamp { 831 type yang:date-and-time; 832 description 833 "The date and time when the instance data set 834 was last modified. 836 In case of instance data sets that are read from or 837 produced by a server or otherwise subject to frequent 838 updates or changes, timestamp SHOULD be present. 840 If both a revision list entry and timestamp are present 841 the timestamp SHOULD contain the same date as the 842 latest revision statement."; 843 } 844 anydata content-data { 845 description 846 "Contains the real instance data. 847 The data MUST conform to the relevant YANG modules 848 specified either in the content-schema or in some other 849 implementation specific manner."; 850 } 851 } 852 } 853 855 4. Security Considerations 857 The YANG module defined in this document only defines a wrapper 858 structure specifying a format and a metadata header for YANG instance 859 data defined by the content-schema. Because of this the security 860 considerations template for YANG models in section 3.7.1 in [RFC8407] 861 is not followed. The instance data is designed to be accessed as a 862 stored file or over any file access method or protocol. 864 The document does not specify any method to influence the behavior of 865 a server. 867 Instance data files may contain sensitive data. 869 The header part is not security sensitive with one possible 870 exception. If the URI method is used for specification of the 871 content schema and the URI includes a username and/or a password, the 872 instance data file needs to be handled securely as mentioned below. 874 The security sensitivity of the instance data in the content part is 875 completely dependent on the content schema. Depending on the nature 876 of the instance data, instance data files MAY need to be handled 877 securely. The same kind of handling should be applied, that would be 878 needed for the result of a read operation returning the same data. 880 Instance data files should be protected against modification or 881 unauthorized access using normal file handling mechanisms. Care 882 should be taken, when copying the original files or providing file 883 access for additional users, not to reveal information 884 unintentionally. 886 5. IANA Considerations 888 This document registers one URI and one YANG module. 890 5.1. URI Registration 892 This document registers one URI in the IETF XML registry [RFC3688]. 893 Following the format in RFC 3688, the following registration is 894 requested to be made: 896 URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 897 Registrant Contact: The IESG. 898 XML: N/A, the requested URI is an XML namespace. 900 5.2. YANG Module Name Registration 902 This document registers one YANG module in the YANG Module Names 903 registry [RFC6020]. Following the format in [RFC6020], the following 904 registrations are requested: 906 name: ietf-yang-instance-data 907 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 908 prefix: yid 909 reference: RFC XXXX 910 // RFC Ed.: replace XXXX with RFC number and remove this note 912 6. Acknowledgments 914 For their valuable comments, discussions, and feedback, we wish to 915 acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe 916 Clarke, Kent Watsen, Martin Bjorklund, Ladislav Lhotka, Qin Wu and 917 other members of the Netmod WG. 919 7. References 921 7.1. Normative References 923 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 924 Requirement Levels", BCP 14, RFC 2119, 925 DOI 10.17487/RFC2119, March 1997, 926 . 928 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 929 the Network Configuration Protocol (NETCONF)", RFC 6020, 930 DOI 10.17487/RFC6020, October 2010, 931 . 933 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 934 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 935 . 937 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 938 RFC 6991, DOI 10.17487/RFC6991, July 2013, 939 . 941 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 942 RFC 7950, DOI 10.17487/RFC7950, August 2016, 943 . 945 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 946 RFC 7951, DOI 10.17487/RFC7951, August 2016, 947 . 949 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 950 RFC 7952, DOI 10.17487/RFC7952, August 2016, 951 . 953 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 954 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 955 May 2017, . 957 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 958 and R. Wilton, "Network Management Datastore Architecture 959 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 960 . 962 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 963 and R. Wilton, "YANG Library", RFC 8525, 964 DOI 10.17487/RFC8525, March 2019, 965 . 967 [RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 968 and R. Wilton, "NETCONF Extensions to Support the Network 969 Management Datastore Architecture", RFC 8526, 970 DOI 10.17487/RFC8526, March 2019, 971 . 973 [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 974 and R. Wilton, "RESTCONF Extensions to Support the Network 975 Management Datastore Architecture", RFC 8527, 976 DOI 10.17487/RFC8527, March 2019, 977 . 979 [RFC8791] Bierman, A., Björklund, M., and K. Watsen, "YANG Data 980 Structure Extensions", RFC 8791, DOI 10.17487/RFC8791, 981 June 2020, . 983 7.2. Informative References 985 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 986 DOI 10.17487/RFC3688, January 2004, 987 . 989 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 990 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 991 . 993 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 994 Documents Containing YANG Data Models", BCP 216, RFC 8407, 995 DOI 10.17487/RFC8407, October 2018, 996 . 998 [RFC8632] Vallin, S. and M. Bjorklund, "A YANG Data Model for Alarm 999 Management", RFC 8632, DOI 10.17487/RFC8632, September 1000 2019, . 1002 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications 1003 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, 1004 September 2019, . 1006 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 1007 "Handling Long Lines in Content of Internet-Drafts and 1008 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 1009 . 1011 [RFC8808] Wu, Q., Lengyel, B., and Y. Niu, "A YANG Data Model for 1012 Factory Default Settings", RFC 8808, DOI 10.17487/RFC8808, 1013 August 2020, . 1015 Appendix A. Changes between revisions 1017 RFC Ed.: Remove section "Changes between revisions" 1019 v19 - v20 1020 * Minor updates for IESG comments 1022 v18 - v19 1024 * Updated leaf includes-defaults 1026 v17 - v18 1028 * Added the report-all-tagged mode to the leaf includes-defaults 1030 v16 - v17 1032 * Removed default statement from includes-default 1034 v15 - v16 1036 * Editorial changes 1038 v14 - v15 1040 * Removed reference to revision-label 1042 * For the inline method made the usage of ietf-yang- 1043 library@2019-01-04 mandatory. Simplified the case "inline" in the 1044 YANG module. 1046 * Removed the "inline-module" leaf as it does not carry useful 1047 information anymore. 1049 * Removed YANG feature 1051 v13 - v14 1053 * Added leaf includes-defaults 1055 * Many small changes based on AD review 1057 v09 - v13 1059 * Editorial updates 1061 v08 - v09 1063 * Removed statement "the format will be similar to the response of a 1064 NETCONF get operation" 1066 * Introduced artwork folding in the examples 1067 v07 - v08 1069 * Moved compatibility into appendix 1071 * Renamed yid-version to format-version. Changed format to date of 1072 the YANG module 1074 * Made support of ietf-yang-library mandatory if inline-content- 1075 schema is supported 1077 * Many small changes based on WGLC 1079 v06 - v07 1081 * Updated terminology, use-cases 1083 * Many small changes based on WGLC 1085 v05 - v06 1087 * Modified module name format, removed .yin or .yang extension 1089 * Removed pattern for module and inline-module. The usage of 1090 revision-label should also be allowed. 1092 v04 - v05 1094 * Updated according to YANG-Doctor review 1096 * Updated security considerations 1098 * Added a wrapping container for the schema, and renamed the data 1099 nodes in the inline and uri cases. 1101 * Allowed .yin for simplified-inline schema naming. Made date 1102 optional if it is unavailable in the YANG module. 1104 * Added a mandatory yid-version to the header metadata to allow 1105 later updates of the module. 1107 v03 - v04 1109 * removed entity-tag and last-modified timestamp 1111 * Added simplified-inline method of content-schema specification 1113 v02 - v03 1114 * target renamed to "content-schema" and "content defining YANG 1115 module(s)" 1117 * Made name of instance data set optional 1119 * Updated according to draft-ietf-netmod-yang-data-ext-03 1121 * Clarified that entity-tag and last-modified timestamp are encoded 1122 as metadata. While they contain useful data, the HTTP-header 1123 based encoding from Restconf is not suitable. 1125 v01 - v02 1127 * Removed design time from terminology 1129 * Defined the format of the content-data part by referencing various 1130 RFCs and drafts instead of the result of the get-data and get 1131 operations. 1133 * Changed target-ptr to a choice 1135 * Inline target-ptr may include augmenting modules and alternatives 1136 to ietf-yang-library 1138 * Moved list of target modules into a separate 1139 element. 1141 * Added backwards compatibility considerations 1143 v00 - v01 1145 * Added the target-ptr metadata with 3 methods 1147 * Added timestamp metadata 1149 * Removed usage of dedicated .yid file extension 1151 * Added list of use cases 1153 * Added list of principles 1155 * Updated examples 1157 * Moved detailed use case descriptions to appendix 1159 Appendix B. Backwards Compatibility 1161 The concept of backwards compatibility and what changes are backwards 1162 compatible are not defined for "instance data sets" as it is highly 1163 dependent on the specific use case and the content-schema. 1165 In case of "instance data sets" that are the result of design or 1166 specification activity, some changes that may be good to avoid are 1167 listed below. 1169 YANG uses the concept of managed entities identified by key values; 1170 if the connection between the represented entity and the key value is 1171 not preserved during an update, this may lead to the following 1172 problems. 1174 * If the key value of a list entry that represents the same managed 1175 entity as before is changed, the user may mistakenly identify the 1176 list entry as new. 1178 * If the meaning of a list entry is changed, but the key values are 1179 not (e.g., redefining an alarm-type but not changing its alarm- 1180 type-id) the change may not be noticed. 1182 * If the key value of a previously removed list entry is reused for 1183 a different entity, the change may be misinterpreted as 1184 reintroducing the previous entity. 1186 Appendix C. Detailed Use Cases 1188 This section is non-normative. 1190 C.1. Use Case 1: Early Documentation of Server Capabilities 1192 A server has a number of server-capabilities that are defined in YANG 1193 modules and can be retrieved from the server using protocols like 1194 NETCONF or RESTCONF. Server capabilities include: 1196 * data defined in "ietf-yang-library": YANG modules, submodules, 1197 features, deviations, schema-mounts, and datastores supported 1198 ([RFC8525]) 1200 * alarms supported ([RFC8632]) 1202 * data nodes and subtrees that support or do not support on-change 1203 notifications ([RFC8641]) 1205 * netconf-capabilities in ietf-netconf-monitoring. 1207 While it is good practice to allow a client to query these 1208 capabilities from the live server, that is often not possible. 1210 Often when a network node is released, an associated NMS (network 1211 management system) is also released with it. The NMS depends on the 1212 capabilities of the server. During NMS implementation, information 1213 about server capabilities is needed. If the information is 1214 unavailable early in some offline document, but only as instance data 1215 from the live network node, the NMS implementation will be delayed, 1216 because it has to wait until the network node is ready. Also 1217 assuming that all NMS implementors will have a correctly configured 1218 network nodes from which data can be retrieved, is a very expensive 1219 proposition. (An NMS may handle dozens of node types.) 1221 Network operators often build their own home-grown NMS systems that 1222 need to be integrated with a vendor's network node. The operator 1223 needs to know the network node's server capabilities in order to do 1224 this. Moreover, the network operator's decision to buy a vendor's 1225 product may even be influenced by the network node's OAM feature set 1226 documented as the server's capabilities. 1228 Beside NMS implementors, system integrators and many others also need 1229 the same information early. Examples could be model driven testing, 1230 generating documentation, etc. 1232 Most server-capabilities are relatively stable and change only during 1233 upgrade or due to licensing or the addition or removal of hardware. 1234 They are usually defined by a vendor at design time, before the 1235 product is released. It is feasible and advantageous to define/ 1236 document them early e.g., in a YANG instance data File. 1238 It is anticipated that a separate IETF document will define in detail 1239 how and which set of server capabilities should be documented. 1241 C.2. Use Case 2: Preloading Data 1243 There are parts of the configuration that must be fully configurable 1244 by the operator. However, often a simple default configuration will 1245 be sufficient. 1247 One example is access control groups/roles and related rules. While 1248 a sophisticated operator may define dozens of different groups, often 1249 a basic (read-only operator, read-write system administrator, 1250 security-administrator) triplet will be enough. Vendors will often 1251 provide such default configuration data to make device configuration 1252 easier for an operator. 1254 Defining access control data is a complex task. To help, the device 1255 vendor predefines a set of default groups (/nacm:nacm/groups) and 1256 rules for these groups to access specific parts of common models 1257 (/nacm:nacm/rule-list/rule). 1259 YANG instance data files are used to document and/or preload the 1260 default configuration. 1262 C.3. Use Case 3: Documenting Factory Default Settings 1264 Nearly every server has a factory default configuration. If the 1265 system is really badly misconfigured or if the current configuration 1266 is to be abandoned, the system can be reset the default factory 1267 configuration. 1269 The operator currently needs to know what the default configuration 1270 actually contains. YANG instance data can be used to document the 1271 factory default configuration. See [RFC8808]. 1273 Authors' Addresses 1275 Balazs Lengyel 1276 Ericsson 1278 Email: balazs.lengyel@ericsson.com 1280 Benoit Claise 1281 Huawei 1283 Email: benoit.claise@huawei.com