idnits 2.17.1 draft-ietf-netmod-yang-instance-file-format-07.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (February 13, 2020) is 1533 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) == Unused Reference: 'I-D.ietf-netmod-yang-data-ext' is defined on line 912, but no explicit reference was found in the text == Unused Reference: 'I-D.verdt-netmod-yang-module-versioning' is defined on line 974, but no explicit reference was found in the text == Outdated reference: A later version (-15) exists of draft-ietf-netmod-factory-default-10 Summary: 0 errors (**), 0 flaws (~~), 5 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: August 16, 2020 Cisco Systems, Inc. 6 February 13, 2020 8 YANG Instance Data File Format 9 draft-ietf-netmod-yang-instance-file-format-07 11 Abstract 13 There is a need to document data defined in YANG models when a live 14 server is not available. Data is often needed already at design or 15 implementation time or needed by groups that do not have a live 16 running server available. This document specifies a standard file 17 format for YANG instance data, which follows the syntax and semantics 18 of existing YANG models, and annotates it with metadata. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on August 16, 2020. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 4 57 2.2. Delivery of Instance Data . . . . . . . . . . . . . . . . 4 58 2.3. Data Life cycle . . . . . . . . . . . . . . . . . . . . . 5 59 3. Instance Data File Format . . . . . . . . . . . . . . . . . . 5 60 3.1. Specifying the Content Schema . . . . . . . . . . . . . . 7 61 3.1.1. Inline Method . . . . . . . . . . . . . . . . . . . . 8 62 3.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 8 63 3.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 8 64 3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 65 4. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 12 66 5. YANG Instance Data Model . . . . . . . . . . . . . . . . . . 13 67 5.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 13 68 5.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 13 69 6. Security Considerations . . . . . . . . . . . . . . . . . . . 19 70 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 71 7.1. URI Registration . . . . . . . . . . . . . . . . . . . . 19 72 7.2. YANG Module Name Registration . . . . . . . . . . . . . . 19 73 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20 74 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 75 9.1. Normative References . . . . . . . . . . . . . . . . . . 20 76 9.2. Informative References . . . . . . . . . . . . . . . . . 21 77 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 22 78 Appendix B. Changes between revisions . . . . . . . . . . . . . 22 79 Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 24 80 C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 24 81 C.1.1. Use Case 1: Early Documentation of Server 82 Capabilities . . . . . . . . . . . . . . . . . . . . 24 83 C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 25 84 C.1.3. Use Case 3: Documenting Factory Default Settings . . 25 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 87 1. Terminology 89 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 90 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 91 "OPTIONAL" in this document are to be interpreted as described in BCP 92 14 RFC 2119 [RFC2119] RFC 8174 [RFC8174] when, and only when, they 93 appear in all capitals, as shown here. 95 Instance Data: A collection of instantiated data nodes. 97 Instance Data Set: A named set of data items annotated with metadata 98 that can be used as instance data in a YANG data tree. 100 Instance Data File: A file containing an instance data set formatted 101 according to the rules described in this document. 103 Content-schema: A set of YANG modules with their revision, supported 104 features, and deviations for which the instance data set contains 105 instance data. 107 Content defining YANG module: an individual YANG module that is part 108 of the content-schema. 110 The term Server is used as defined in [RFC8342]. 112 2. Introduction 114 There is a need to document data defined in YANG models when a live 115 server is not available. Data is often needed already at design or 116 implementation time or needed by groups that do not have a live 117 running server available. To facilitate this offline delivery of 118 data, this document specifies a standard format for YANG instance 119 data sets and YANG instance data files. 121 The following is a list of already implemented and potential use 122 cases. 124 UC1 Documentation of server capabilities 126 UC2 Preloading default configuration data 128 UC3 Documenting Factory Default Settings 130 UC4 Storing the configuration of a device, e.g., for backup, archive 131 or audit purposes 133 UC5 Storing diagnostics data 135 UC6 Allowing YANG instance data to potentially be carried within 136 other IPC message formats 138 UC7 Default instance data used as part of a templating solution 140 UC8 Providing data examples in RFCs or internet drafts 142 In Appendix C we describe the first three use cases in detail. 144 There are many and varied use cases where YANG instance data could be 145 used. We do not want to limit future uses of instance data sets, so 146 specifying how and when to use YANG instance data is out of scope for 147 this document. It is anticipated that other documents will define 148 specific use cases. Use cases are listed here only to indicate the 149 need for this work. 151 2.1. Principles 153 The following is a list of the basic principles of the instance data 154 format: 156 P1 Two standard formats shall be defined based on the XML and JSON 157 encodings. 159 P2 Instance data shall reuse existing encoding rules for YANG 160 defined data. Its format will be similar to the response of a 161 NETCONF operation or the RESTCONF response to a GET method 162 invocation on the (unified) datastore resource. 164 P3 Metadata about the instance data set (Section 3, Paragraph 9) 165 shall be defined. 167 P4 A YANG instance data set shall be allowed to contain data for 168 multiple YANG modules. 170 P5 Instance data shall be allowed to contain configuration data, 171 state data, or a mix of the two. 173 P6 Partial data sets shall be allowed. 175 P7 The YANG instance data format shall be usable for any data for 176 which YANG module(s) are defined and available to the reader, 177 independent of whether the module is actually implemented by a 178 server. 180 2.2. Delivery of Instance Data 182 Instance data sets that are produced as a result of some sort of 183 specification or design effort may be available without the need for 184 a live server e.g., via download from the vendor's website, or in any 185 other way that product documentation is distributed. 187 Other instance data sets may be read from or produced by the YANG 188 server itself e.g., UC5 documenting diagnostic data. 190 2.3. Data Life cycle 192 YANG instance data is always a snapshot of information at a specific 193 point of time. If the data changes afterwards, this is not 194 represented in the instance data set anymore. The current values may 195 be retrieved at run-time via NETCONF/RESTCONF or received e.g., in 196 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 3. 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 we want to document/provide. The syntax and 212 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 metadata as defined by [RFC7952]. 226 a default attribute as defined in [RFC6243] section 6. and in 227 [RFC8040] section 4.8.9. 229 origin metadata as specified in [RFC8526] and [RFC8527] 231 implementation specific metadata relevant to individual data 232 nodes. Unknown metadata MUST be ignored by users of instance 233 data, allowing it to be used later for other purposes. 235 in the XML format implementation specific XML attributes, unknown 236 attributes MUST be ignored by users of instance data, allowing 237 them to be used later for other purposes. 239 An instance data set MAY contain data for any number of YANG modules; 240 if needed it MAY carry the complete configuration and state data set 241 for a server. Default values SHOULD NOT be included. 243 Config=true and config=false data MAY be mixed in the instance data 244 file. 246 Instance data files MAY contain partial data sets. This means 247 mandatory, min-elements, require-instance=true, must and when 248 constrains MAY be violated. 250 The name of the instance data file SHOULD take one of the following 251 two forms: 253 If revision information inside the data set is present 255 * instance-data-set-name ['@' revision-date] '.filetype' 257 * E.g., acme-router-modules@2018-01-25.xml 259 If the leaf "name" is present in the instance data header, this 260 MUST be used. If the "revision-date" is present in both the 261 filename and in the instance data header, the revision date in the 262 file name MUST be set to the latest revision date inside the 263 instance data set. 265 If timestamp information inside the data set is present 267 * instance-data-set-name ['@' timestamp] '.filetype' 269 * E.g., acme-router-modules@2018-01-25T15_06_34_3+01_00.json 271 If the leaf "name" is present in the instance data header, this 272 MUST be used. If the "timestamp" is present both in the filename 273 and in the instance data header, the timestamp in the file name 274 MUST be set to the timestamp inside the instance data set; the 275 semicolons and the decimal point, if present, shall be replaced by 276 underscores. 278 The revision date or timestamp is optional. ".filetype" SHALL be 279 ".json" or ".xml" according to the format used. 281 Metadata, information about the data set itself SHOULD be included in 282 the instance data set. Some metadata items are defined in the YANG 283 module ietf-yang-instance-data, but other items MAY also be used. 284 Metadata MUST include: 286 Version of the YANG Instance Data format 288 Metadata SHOULD include: 290 o Name of the data set 292 o Content schema specification 294 o Description of the instance data set. The description SHOULD 295 contain information whether and how the data can change during the 296 lifetime of the server. 298 3.1. Specifying the Content Schema 300 To properly understand and use an instance data set, the user needs 301 to know the content-schema. One of the following methods SHOULD be 302 used: 304 Inline method: Include the needed information as part of the 305 instance data set. 307 Simplified-Inline method: Include the needed information as part 308 of the instance data set; short specification. 310 URI method: Include a URI that references another YANG instance 311 data file. This instance data file will use the same content- 312 schema as the referenced YANG instance data file. (if you don't 313 want to repeat the info again and again) 315 External Method: Do not include the content-schema, the user needs 316 to obtain the information through external documents. 318 Additional methods e.g., a YANG-package based solution may be added 319 later. 321 Note, the specified content-schema only indicates the set of modules 322 that were used to define this YANG instance data set. Sometimes 323 instance data may be used for a server supporting a different YANG 324 module set. (e.g., for "UC2 Preloading Data" the instance data set 325 may not be updated every time the YANG modules on the server are 326 updated) Whether an instance data set originally defined using a 327 specific content-schema is usable with a different other schema 328 depends on many factors including the amount of differences and the 329 compatibility between the original and the other schema, considering 330 modules, revisions, features, deviations, the scope of the instance 331 data, etc. 333 3.1.1. Inline Method 335 One or more inline-module elements define YANG module(s) used to 336 specify the content defining YANG modules. 338 E.g., ietf-yang-library@2016-06-21 340 The anydata inline-schema carries instance data (conforming to the 341 inline-modules) that actually specifies the content defining YANG 342 modules including revision, supported features, deviations and any 343 relevant additional data (e.g., revision labels). See Section 3.2. 345 3.1.2. Simplified-Inline Method 347 The instance data set contains a list of content defining YANG 348 modules including the revision date for each. Usage of this method 349 implies that the modules are used without any deviations and with all 350 features supported. 352 3.1.3. URI Method 354 The same-schema-as-file leaf SHALL contain a URI that references 355 another YANG instance data file. The current instance data file will 356 use the same content schema as the referenced file. 358 The referenced instance data file MAY have no content-data if it is 359 used solely for specifying the content-schema. 361 If a referenced instance data file is not available, content-schema 362 is unknown. 364 The URI method is advantageous when the user wants to avoid the 365 overhead of specifying the content-schema in each instance data file: 366 E.g., In Use Case 6, when the system creates a diagnostic file every 367 minute to document the state of the server. 369 3.2. Examples 371 The following example is based on "UC1, Documenting Server 372 Capabilities". It provides (a shortened) list of supported YANG 373 modules and NETCONF capabilities for a server. It uses the inline 374 method to specify the content-schema. 376 377 379 acme-router-modules 380 1 381 382 383 ietf-yang-library@2016-06-21 384 385 386 388 389 ietf-yang-library 390 2016-06-21 391 392 393 ietf-netconf-monitoring 394 2010-10-04 395 396 397 398 399 400 1956-10-23 401 Initial version 402 403 Defines the minimal set of modules that any acme-router 404 will contain. 405 info@acme.com 406 407 410 412 413 ietf-yang-library 414 2016-06-21 415 416 urn:ietf:params:xml:ns:yang:ietf-yang-library 417 418 implement 419 420 421 ietf-system 422 2014-08-06 423 urn:ietf:params:xml:ns:yang:ietf-system 424 sys:authentication 425 sys:local-users 426 427 acme-system-ext 428 2018-08-06 430 431 implement 432 433 434 ietf-yang-types 435 2013-07-15 436 urn:ietf:params:xml:ns:yang:ietf-yang-types 437 438 import 439 440 441 acme-system-ext 442 2018-08-06 443 urn:rdns:acme.com:oammodel:acme-system-ext 444 445 implement 446 447 448 450 451 452 urn:ietf:params:netconf:capability:validate:1.1 453 454 455 456 457 459 Figure 1: XML Instance Data Set - Use case 1, Documenting server 460 capabilities 462 The following example is based on "UC2, Preloading Default 463 Configuration". It provides a (shortened) default rule set for a 464 read-only operator role. It uses the inline method for specifying 465 the content-schema. 467 468 470 read-only-acm-rules 471 1 472 473 ietf-yang-library@2019-01-04 474 475 477 478 all 479 480 ietf-netconf-acm 481 2012-02-22 482 483 484 485 486 487 488 1776-07-04 489 Initial version 490 491 Access control rules for a read-only role. 492 493 494 true 495 deny 496 deny 497 498 read-only-role 499 read-only-group 500 501 read-all 502 * 503 read 504 permit 505 506 507 508 509 511 Figure 2: XML Instance Data Set - Use case 2, Preloading access 512 control data 514 The following example is based on UC5 Storing diagnostics data. An 515 instance data set is produced by the server every 15 minutes that 516 contains statistics about NETCONF. As a new set is produced 517 periodically many times a day a revision-date would be useless; 518 instead a timestamp is included. 520 { 521 "ietf-yang-instance-data:instance-data-set": { 522 "name": "acme-router-netconf-diagnostics", 523 "yid-version": "1", 524 "content-schema": { 525 "same-schema-as-file": "file:///acme-diagnostics-schema.json", 526 }, 527 "timestamp": "2018-01-25T17:00:38Z", 528 "description": 529 "NETCONF statistics", 530 "content-data": { 531 "ietf-netconf-monitoring:netconf-state": { 532 "statistics": { 533 "netconf-start-time ": "2018-12-05T17:45:00Z", 534 "in-bad-hellos ": "32", 535 "in-sessions ": "397", 536 "dropped-sessions ": "87", 537 "in-rpcs ": "8711", 538 "in-bad-rpcs ": "408", 539 "out-rpc-errors ": "408", 540 "out-notifications": "39007" 541 } 542 } 543 } 544 } 545 } 547 Figure 3: JSON Instance Data File example - UC5 Storing diagnostics 548 data 550 4. Backwards Compatibility 552 The concept of backwards compatibility and what changes are backwards 553 compatible are not defined for instance data sets as it is highly 554 dependent on the specific use case and the content-schema. 556 For instance data that is the result of a design or specification 557 activity, some changes that may be good to avoid are listed. YANG 558 uses the concept of managed entities identified by key values; if the 559 connection between the represented entity and the key value is not 560 preserved during an update, this may lead to problems. 562 o If the key value of a list entry that represents the same managed 563 entity as before is changed, the user may mistakenly identify the 564 list entry as new. 566 o If the meaning of a list entry is changed, but the key values are 567 not (e.g., redefining an alarm-type but not changing its alarm- 568 type-id) the change may not be noticed. 570 o If the key value of a previously removed list entry is reused for 571 a different entity, the change may be misinterpreted as 572 reintroducing the previous entity. 574 5. YANG Instance Data Model 576 5.1. Tree Diagram 578 The following tree diagram [RFC8340] provides an overview of the data 579 model. 581 module: ietf-yang-instance-data 582 structure instance-data-set: 583 +--rw name? string 584 +--rw yid-version uint8 585 +--rw content-schema 586 | +--rw (content-schema-spec)? 587 | +--:(simplified-inline) 588 | | +--rw module* string 589 | +--:(inline) {inline-content-schema}? 590 | | +--rw inline-module* string 591 | | +--rw inline-schema 592 | +--:(uri) 593 | +--rw same-schema-as-file? inet:uri 594 +--rw description? string 595 +--rw contact? string 596 +--rw organization? string 597 +--rw datastore? ds:datastore-ref 598 +--rw revision* [date] 599 | +--rw date string 600 | +--rw description? string 601 +--rw timestamp? yang:date-and-time 602 +--rw content-data? 604 5.2. YANG Model 606 file "ietf-yang-instance-data@2019-11-17.yang" 607 module ietf-yang-instance-data { 608 yang-version 1.1; 609 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"; 610 prefix yid; 612 import ietf-yang-structure-ext { 613 prefix sx; 614 } 615 import ietf-datastores { 616 prefix ds; 617 } 618 import ietf-inet-types { 619 prefix inet; 620 } 621 import ietf-yang-types { 622 prefix yang; 623 } 625 organization 626 "IETF NETMOD Working Group"; 627 contact 628 "WG Web: 629 WG List: 631 Author: Balazs Lengyel 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) 2019 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."; 657 revision 2019-11-17 { 658 description 659 "Initial revision."; 660 reference 661 "RFC XXXX: YANG Instance Data Format"; 662 } 664 feature inline-content-schema { 665 description 666 "This feature indicates that inline content-schema 667 option is supported."; 668 } 670 sx:structure "instance-data-set" { 671 description 672 "A data structure to define a format for 673 YANG instance data sets. Consists of meta-data about 674 the instance data set and the real content-data."; 675 leaf name { 676 type string; 677 description 678 "Name of the YANG instance data set."; 679 } 680 leaf yid-version { 681 type uint8; 682 mandatory true; 683 description 684 "Version number of the 'YANG Instance Data format'. 685 It MUST contain the value '1' for instance data 686 based on this specification."; 687 } 688 container content-schema { 689 description 690 "The content schema used to create the instance data set"; 691 choice content-schema-spec { 692 description 693 "Specification of the content-schema"; 694 case simplified-inline { 695 leaf-list module { 696 type string ; 697 description 698 "The list of content defining YANG modules. 699 The value SHALL start with the module name. 700 If the module contains a revision statement the 701 revision date SHALL be included in the leaf-list 702 entry. 703 If other methods (e.g., revision-label) are 704 defined to identify individual module revisions 705 those MAY be used instead of using a revision date. 707 E.g., ietf-yang-library@2016-06-21 709 Usage of this leaf-list implies the modules are 710 used without any deviations and with all features 711 supported. Multiple revisions of the same module 712 MUST NOT be specified."; 713 } 714 } 715 case inline { 716 if-feature inline-content-schema; 717 leaf-list inline-module { 718 type string ; 719 min-elements 1; 720 ordered-by user; 721 description 722 "Indicates that content defining YANG modules 723 are specified inline. 724 The value SHALL start with the module name. 725 If the module contains a revision statement the 726 revision date SHALL be included in the leaf-list 727 entry. 728 If other methods (e.g., revision-label) are 729 defined to identify individual module revisions 730 those MAY be used instead of using a revision date. 732 E.g., ietf-yang-library@2016-06-21 734 The first item is either ietf-yang-library or some other 735 YANG module that contains a list of YANG modules with 736 their name, revision-date, supported-features, and 737 deviations. 738 As some versions of ietf-yang-library MAY contain 739 different module-sets for different datastores, if 740 multiple module-sets are included, the instance data 741 set's meta-data MUST contain the datastore information 742 and instance data for the ietf-yang-library MUST also 743 contain information specifying the module-set for the 744 relevant datastore. 746 Subsequent items MAY specify YANG modules augmenting the 747 first module with useful data (e.g., revision label)."; 748 } 749 anydata inline-schema { 750 mandatory true; 751 description 752 "Instance data corresponding to the YANG modules 753 specified in the inline-module nodes defining the set 754 of content defining YANG modules for this 755 instance-data-set."; 756 } 757 } 758 case uri { 759 leaf same-schema-as-file { 760 type inet:uri; 761 description 762 "A reference to another YANG instance data file. 763 This instance data file uses the same 764 content schema as the referenced file."; 765 } 766 } 767 } 768 } 769 leaf-list description { 770 type string; 771 description 772 "Description of the instance data set."; 773 } 774 leaf contact { 775 type string; 776 description 777 "Contact information for the person or 778 organization to whom queries concerning this 779 instance data set should be sent."; 780 } 781 leaf organization { 782 type string; 783 description 784 "Organization responsible for the instance 785 data set."; 786 } 787 leaf datastore { 788 type ds:datastore-ref; 789 description 790 "The identity of the datastore with which the 791 instance data set is associated, e.g., the datastore from 792 where the data was read or the datastore into which the data 793 may be loaded or the datastore which is being documented. 794 If a single specific datastore cannot be specified, the 795 leaf MUST be absent. 797 If this leaf is absent, then the datastore to which the 798 instance data belongs is undefined."; 799 } 800 list revision { 801 key "date"; 802 description 803 "Instance data sets that are produced as 804 a result of some sort of specification or design effort 805 SHOULD have at least one revision entry. For every 806 published editorial change, a new one SHOULD be added 807 in front of the revisions sequence so that all 808 revisions are in reverse chronological order. 810 For instance data sets that are read from 811 or produced by a server or otherwise 812 subject to frequent updates or changes, revision 813 SHOULD NOT be present"; 814 leaf date { 815 type string { 816 pattern '\d{4}-\d{2}-\d{2}'; 817 } 818 description 819 "Specifies the date the instance data set 820 was last modified. Formatted as YYYY-MM-DD"; 821 } 822 leaf description { 823 type string; 824 description 825 "Description of this revision of the instance data set."; 826 } 827 } 828 leaf timestamp { 829 type yang:date-and-time; 830 description 831 "The date and time when the instance data set 832 was last modified. 834 For instance data sets that are read from or produced 835 by a server or otherwise subject to frequent 836 updates or changes, timestamp SHOULD be present"; 837 } 838 anydata content-data { 839 description 840 "Contains the real instance data. 841 The data MUST conform to the relevant YANG Modules specified 842 either in the content-schema-spec or in some other 843 implementation specific manner."; 844 } 845 } 846 } 847 849 6. Security Considerations 851 The YANG module defined in this document is designed as a wrapper 852 specifying a format and a metadata header for YANG instance data 853 defined by the content-schema. The data is designed to be accessed 854 as a stored file or over any file access method or protocol. 856 The document does not specify any method to influence the behavior of 857 a server. 859 Instance data files may contain sensitive data. 861 The header part is not security sensitive. 863 The security sensitivity of the instance data in the content part is 864 completely dependent on the content schema. Depending on the nature 865 of the instance data, instance data files MAY need to be handled in a 866 secure way. The same kind of handling should be applied, that would 867 be needed for the result of a read operation returning the same data. 869 Instance data files should be protected against modification or 870 unauthorized access using normal file handling mechanisms. Care 871 should be taken, when copying the original files or providing file 872 access for additional users, not to reveal information 873 unintentionally. 875 7. IANA Considerations 877 This document registers one URI and one YANG module. 879 7.1. URI Registration 881 This document registers one URI in the IETF XML registry [RFC3688]. 882 Following the format in RFC 3688, the following registration is 883 requested to be made: 885 URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 887 Registrant Contact: The IESG. 889 XML: N/A, the requested URI is an XML namespace. 891 7.2. YANG Module Name Registration 893 This document registers one YANG module in the YANG Module Names 894 registry [RFC6020]. 896 name: ietf-yang-instance-data 897 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 898 prefix: yid 899 reference: RFC XXXX 901 8. Acknowledgments 903 For their valuable comments, discussions, and feedback, we wish to 904 acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe 905 Clarke, Kent Watsen Martin Bjorklund, Ladislav Lhotka, Qin Wu and 906 other members of the Netmod WG. 908 9. References 910 9.1. Normative References 912 [I-D.ietf-netmod-yang-data-ext] 913 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 914 Structure Extensions", draft-ietf-netmod-yang-data-ext-05 915 (work in progress), December 2019. 917 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 918 DOI 10.17487/RFC3688, January 2004, 919 . 921 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 922 the Network Configuration Protocol (NETCONF)", RFC 6020, 923 DOI 10.17487/RFC6020, October 2010, 924 . 926 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 927 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 928 . 930 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 931 RFC 7950, DOI 10.17487/RFC7950, August 2016, 932 . 934 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 935 RFC 7951, DOI 10.17487/RFC7951, August 2016, 936 . 938 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 939 RFC 7952, DOI 10.17487/RFC7952, August 2016, 940 . 942 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 943 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 944 . 946 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 947 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 948 . 950 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 951 and R. Wilton, "Network Management Datastore Architecture 952 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 953 . 955 [RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 956 and R. Wilton, "NETCONF Extensions to Support the Network 957 Management Datastore Architecture", RFC 8526, 958 DOI 10.17487/RFC8526, March 2019, 959 . 961 [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 962 and R. Wilton, "RESTCONF Extensions to Support the Network 963 Management Datastore Architecture", RFC 8527, 964 DOI 10.17487/RFC8527, March 2019, 965 . 967 9.2. Informative References 969 [I-D.ietf-netmod-factory-default] 970 WU, Q., Lengyel, B., and Y. Niu, "Factory Default 971 Setting", draft-ietf-netmod-factory-default-10 (work in 972 progress), February 2020. 974 [I-D.verdt-netmod-yang-module-versioning] 975 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 976 B., Sterne, J., and K. D'Souza, "Updated YANG Module 977 Revision Handling", draft-verdt-netmod-yang-module- 978 versioning-01 (work in progress), October 2019. 980 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 981 Requirement Levels", BCP 14, RFC 2119, 982 DOI 10.17487/RFC2119, March 1997, 983 . 985 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 986 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 987 May 2017, . 989 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 990 and R. Wilton, "YANG Library", RFC 8525, 991 DOI 10.17487/RFC8525, March 2019, 992 . 994 [RFC8632] Vallin, S. and M. Bjorklund, "A YANG Data Model for Alarm 995 Management", RFC 8632, DOI 10.17487/RFC8632, September 996 2019, . 998 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications 999 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, 1000 September 2019, . 1002 Appendix A. Open Issues 1004 o - 1006 Appendix B. Changes between revisions 1008 v06 - v07 1010 o Updated terminology, use-cases 1012 o Many small changes based on WGLC 1014 v05 - v06 1016 o Modified module name format, removed .yin or .yang extension 1018 o Removed pattern for module and inline-module. We want to allow 1019 the usage of revision-label later 1021 v04 - v05 1023 o Updated according to YANG-Doctor review 1025 o Updated security considerations 1027 o Added a wrapping container for the schema, and renamed the data 1028 nodes in the inline and uri cases. 1030 o Allowed .yin for simplified-inline schema naming. Made date 1031 optional if it is not available in the YANG module. 1033 o Added a mandatory yid-version to the header metadata to allow 1034 later updates of the module. 1036 v03 - v04 1037 o removed entity-tag and last-modified timestamp 1039 o Added simplified-inline method of content-schema specification 1041 v02 - v03 1043 o target renamed to "content-schema" and "content defining YANG 1044 module(s)" 1046 o Made name of instance data set optional 1048 o Updated according to draft-ietf-netmod-yang-data-ext-03 1050 o Clarified that entity-tag and last-modified timestamp are encoded 1051 as metadata. While they contain useful data, the HTTP-header 1052 based encoding from Restconf is not suitable. 1054 v01 - v02 1056 o Removed design time from terminology 1058 o Defined the format of the content-data part by referencing various 1059 RFCs and drafts instead of the result of the get-data and get 1060 operations. 1062 o Changed target-ptr to a choice 1064 o Inline target-ptr may include augmenting modules and alternatives 1065 to ietf-yang-library 1067 o Moved list of target modules into a separate 1068 element. 1070 o Added backwards compatibility considerations 1072 v00 - v01 1074 o Added the target-ptr metadata with 3 methods 1076 o Added timestamp metadata 1078 o Removed usage of dedicated .yid file extension 1080 o Added list of use cases 1082 o Added list of principles 1084 o Updated examples 1085 o Moved detailed use case descriptions to appendix 1087 Appendix C. Detailed Use Cases - Non-Normative 1089 C.1. Use Cases 1091 We present a number of use cases were YANG instance data is needed. 1093 C.1.1. Use Case 1: Early Documentation of Server Capabilities 1095 A server has a number of server-capabilities that are defined in YANG 1096 modules and can be retrieved from the server using protocols like 1097 NETCONF or RESTCONF. Server capabilities include: 1099 o data defined in ietf-yang-library: YANG modules, submodules, 1100 features, deviations, schema-mounts, and datastores supported 1101 ([RFC8525]) 1103 o alarms supported ([RFC8632]) 1105 o data nodes and subtrees that support or do not support on-change 1106 notifications ([RFC8641]) 1108 o netconf-capabilities in ietf-netconf-monitoring 1110 While it is good practice to allow a client to query these 1111 capabilities from the live server, that is often not possible. 1113 Often when a network node is released, an associated NMS (network 1114 management system) is also released with it. The NMS depends on the 1115 capabilities of the server. During NMS implementation, information 1116 about server capabilities is needed. If the information is not 1117 available early in some offline document, but only as instance data 1118 from the live network node, the NMS implementation will be delayed, 1119 because it has to wait until the network node is ready. Also 1120 assuming that all NMS implementors will have a correctly configured 1121 network nodes from which data can be retrieved, is a very expensive 1122 proposition. (An NMS may handle dozens of node types.) 1124 Network operators often build their own home-grown NMS systems that 1125 need to be integrated with a vendor's network node. The operator 1126 needs to know the network node's server capabilities in order to do 1127 this. Moreover, the network operator's decision to buy a vendor's 1128 product may even be influenced by the network node's OAM feature set 1129 documented as the server's capabilities. 1131 Beside NMS implementors, system integrators and many others also need 1132 the same information early. Examples could be model driven testing, 1133 generating documentation, etc. 1135 Most server-capabilities are relatively stable and change only during 1136 upgrade or due to licensing or the addition or removal of hardware. 1137 They are usually defined by a vendor at design time, before the 1138 product is released. It is feasible and advantageous to define/ 1139 document them early e.g., in a YANG instance data File. 1141 It is anticipated that a separate IETF document will define in detail 1142 how and which set of server capabilities should be documented. 1144 C.1.2. Use Case 2: Preloading Data 1146 There are parts of the configuration that must be fully configurable 1147 by the operator. However, often a simple default configuration will 1148 be sufficient. 1150 One example is access control groups/roles and related rules. While 1151 a sophisticated operator may define dozens of different groups, often 1152 a basic (read-only operator, read-write system administrator, 1153 security-administrator) triplet will be enough. Vendors will often 1154 provide such default configuration data to make device configuration 1155 easier for an operator. 1157 Defining access control data is a complex task. To help, the device 1158 vendor predefines a set of default groups (/nacm:nacm/groups) and 1159 rules for these groups to access specific parts of common models 1160 (/nacm:nacm/rule-list/rule). 1162 YANG instance data files are used to document and/or preload the 1163 default configuration. 1165 C.1.3. Use Case 3: Documenting Factory Default Settings 1167 Nearly every server has a factory default configuration. If the 1168 system is really badly misconfigured or if the current configuration 1169 is to be abandoned, the system can be reset the default factory 1170 configuration. 1172 In NETCONF, the operation can already be used to 1173 reset the startup datastore. There are ongoing efforts to introduce 1174 a new, more generic factory-reset operation for the same purpose 1175 [I-D.ietf-netmod-factory-default] 1176 The operator currently has no way to know what the default 1177 configuration actually contains. YANG instance data can also be used 1178 to document the factory default configuration. 1180 Authors' Addresses 1182 Balazs Lengyel 1183 Ericsson 1184 Magyar Tudosok korutja 11 1185 1117 Budapest 1186 Hungary 1188 Phone: +36-70-330-7909 1189 Email: balazs.lengyel@ericsson.com 1191 Benoit Claise 1192 Cisco Systems, Inc. 1193 De Kleetlaan 6a b1 1194 1831 Diegem 1195 Belgium 1197 Phone: +32 2 704 5622 1198 Email: bclaise@cisco.com