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