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