idnits 2.17.1 draft-ietf-netmod-yang-instance-file-format-03.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 (July 5, 2019) is 1757 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 832, but no explicit reference was found in the text == Outdated reference: A later version (-05) exists of draft-ietf-netmod-yang-data-ext-03 Summary: 0 errors (**), 0 flaws (~~), 4 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: January 6, 2020 Cisco Systems, Inc. 6 July 5, 2019 8 YANG Instance Data File Format 9 draft-ietf-netmod-yang-instance-file-format-03 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 semantic 18 from existing YANG models, re-using the same format as the reply to a 19 operation/request) and decorates it with metadata. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 6, 2020. 38 Copyright Notice 40 Copyright (c) 2019 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. Instance Data File Format . . . . . . . . . . . . . . . . . . 4 59 3.1. Specifying the Content Schema . . . . . . . . . . . . . . 6 60 3.1.1. INLINE Method . . . . . . . . . . . . . . . . . . . . 7 61 3.1.2. URI Method . . . . . . . . . . . . . . . . . . . . . 7 62 3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 63 4. Data Life cycle . . . . . . . . . . . . . . . . . . . . . . . 11 64 5. Delivery of Instance Data . . . . . . . . . . . . . . . . . . 12 65 6. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 12 66 7. Yang Instance Data Model . . . . . . . . . . . . . . . . . . 12 67 7.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 12 68 7.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 13 69 8. Security Considerations . . . . . . . . . . . . . . . . . . . 17 70 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 71 9.1. URI Registration . . . . . . . . . . . . . . . . . . . . 18 72 9.2. YANG Module Name Registration . . . . . . . . . . . . . . 18 73 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 74 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 75 11.1. Normative References . . . . . . . . . . . . . . . . . . 18 76 11.2. Informative References . . . . . . . . . . . . . . . . . 20 77 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 20 78 Appendix B. Changes between revisions . . . . . . . . . . . . . 20 79 Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 23 80 C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 23 81 C.1.1. Use Case 1: Early Documentation of Server 82 Capabilities . . . . . . . . . . . . . . . . . . . . 23 83 C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 24 84 C.1.3. Use Case 3: Documenting Factory Default Settings . . 24 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 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 Set: A named set of data items decorated with metadata 96 that can be used as instance data in a YANG data tree. 98 Instance Data File: A file containing an instance data set formatted 99 according to the rules described in this document. 101 Content-schema: A set of YANG modules with their revision,suupported 102 features and deviations for which the instance data set contains 103 instance data 105 Content defining Yang module(s): YANG module(s) that make up the 106 content-schema 108 YANG Instance Data, or just instance data for short, is data that 109 could be stored in a datastore and whose syntax and semantics is 110 defined by YANG models. 112 The term Server is used as defined in [RFC8342] 114 2. Introduction 116 There is a need to document data defined in YANG models when a live 117 server is not available. Data is often needed already at design or 118 implementation time or needed by groups that do not have a live 119 running server available. To facilitate this off-line delivery of 120 data this document specifies a standard format for YANG instance data 121 sets and YANG instance data files. 123 The following is a list of already implemented and potential use 124 cases. 126 UC1 Documentation of server capabilities 128 UC2 Preloading default configuration data 130 UC3 Documenting Factory Default Settings 132 UC4 Instance data used as backup 134 UC5 Storing the configuration of a device, e.g. for archive or audit 135 purposes 137 UC6 Storing diagnostics data 139 UC7 Allowing YANG instance data to potentially be carried within 140 other IPC message formats 142 UC8 Default instance data used as part of a templating solution 144 UC9 Providing data examples in RFCs or internet drafts 145 In Appendix C we describe the first three use cases in detail. 147 There are many and varied use cases where YANG instance data could be 148 used. We do not want to limit future uses of instance data sets, so 149 specifying how and when to use Yang instance data is out of scope for 150 this document. It is anticipated that other documents will define 151 specific use cases. Use cases are listed here only to indicate the 152 need for this work. 154 2.1. Principles 156 The following is a list of the basic principles of the instance data 157 format: 159 P1 Two standard formats are based on the XML and the JSON encoding 161 P2 Re-use existing formats similar to the response to a 162 operation/request 164 P3 Add metadata about the instance data set (Section 3, Paragraph 9) 166 P4 A YANG instance data set may contain data for many YANG modules 168 P5 Instance data may include configuration data, state data or a mix 169 of the two 171 P6 Partial data sets are allowed 173 P7 YANG instance data format may be used for any data for which YANG 174 module(s) are defined and available to the reader, independent of 175 whether the module is actually implemented by a server 177 3. Instance Data File Format 179 A YANG instance data file MUST contain a single instance data set and 180 no additional data. 182 The format of the instance data set is defined by the ietf-yang- 183 instance-data YANG module. It is made up of a header part and 184 content-data. The header part carries metadata for the instance data 185 set. The content-data, defined as an anydata data node, carries the 186 "real data" that we want to document/provide. The syntax and 187 semantics of content-data is defined by the content-schema. 189 Two formats are specified based on the XML and JSON YANG encodings. 190 Later as other YANG encodings (e.g. CBOR) are defined further 191 instance data formats may be specified. 193 The content-data part SHALL follow the encoding rules defined in 194 [RFC7950] for XML and [RFC7951] for JSON and MUST use UTF-8 character 195 encoding. Content-data MAY include: 197 metadata as defined by [RFC7952]. 199 entity-tags and timestamps as defined in [RFC8040] encoded 200 according to [RFC7952] 202 a default attribute as defined in [RFC6243] section 6. and in 203 [RFC8040] section 4.8.9. 205 origin metadata as specified in [RFC8526] and [RFC8527] 207 implementation specific metadata. Unknown metadata MUST be 208 ignored by users of YANG instance data, allowing it to be used 209 later for other purposes. 211 in the XML format implementation specific XML attributes. Unknown 212 attributes MUST be ignored by users of YANG instance data, 213 allowing them to be used later for other purposes. 215 The content-data part will be very similar to the result returned for 216 a NETCONF or for a RESTCONF get operation. 218 The content-data part MUST conform to the content-schema. An 219 instance data set MAY contain data for any number of YANG modules; if 220 needed it MAY carry the complete configuration and state data set for 221 a server. Default values SHOULD NOT be included. 223 Config=true and config=false data MAY be mixed in the instance data 224 file. 226 Instance data files MAY contain partial data sets. This means 227 mandatory, min-elements, require-instance=true, must and when 228 constrains MAY be violated. 230 The name of the instance data file SHOULD take one of the following 231 two forms: 233 If revision information inside the data set is present 235 * instance-data-set-name ['@' revision-date] '.filetype' 237 * E.g. acme-router-modules@2018-01-25.xml 238 If the leaf name is present in the instance data header this MUST 239 be used. Revision-date MUST be set to the latest revision date 240 inside the instance data set. 242 If timestamp information inside the data set is present 244 * instance-data-set-name ['@' timestamp] '.filetype' 246 * E.g. acme-router-modules@2018-01-25T15_06_34_3+01_00.json 248 If the leaf name is present in the instance data header this MUST 249 be used. If the leaf timestamp is present in the instance data 250 header this MUST be used; the semicolons and the decimal point if 251 present shall be replaced by underscores. 253 The revision date or timestamp is optional. ".filetype" SHALL be 254 ".json" or ".xml" according to the format used. 256 Metadata, information about the data set itself SHOULD be included in 257 the instance data set. Some metadata items are defined in the YANG 258 module ietf-yang-instance-data, but other items MAY also be used. 259 Metadata SHOULD include: 261 o Name of the data set 263 o Content schema specification 265 o Description of the instance data set. The description SHOULD 266 contain information whether and how the data can change during the 267 lifetime of the server. 269 3.1. Specifying the Content Schema 271 To properly understand and use an instance data set the user needs to 272 know the content-schema. One of the following methods SHOULD be 273 used: 275 INLINE method: Include the needed information as part of instance 276 data set. 278 URI method: Include a URI that references another YANG instance 279 data file. This instance data file will use the same content- 280 schema as the referenced YANG instance data file. (if you don't 281 want to repeat the info again and again) 283 EXTERNAL Method: Do not include the content-schema as it is 284 already known, or the information is available through external 285 documents. 287 Additional methods e.g. a YANG-package based solution may be added 288 later. 290 Note, the specified content-schema only indicates the set of modules 291 that were used to define this YANG instance data set. Sometimes 292 instance data may be used for a server supporting a different YANG 293 module set. (e.g. for "UC2 Preloading Data" the instance data set may 294 not be updated every time the YANG modules on the server are updated) 295 Whether the instance data set is usable for a possibly different 296 real-life YANG module set depends on many factors including the 297 compatibility between the specified and the real-life YANG module set 298 (considering modules, revisions, features, deviations), the scope of 299 the instance data, etc. 301 3.1.1. INLINE Method 303 One or more inline-target-spec elements define YANG module(s) used to 304 specify the content defining YANG modules. 306 E.g. ietf-yang-library@2016-06-21.yang 308 The anydata inline-content-schema carries instance data (conforming 309 to the inline-target-spec modules) that actually specifies the 310 content defining YANG modules including revision, supported features, 311 deviations and any relevant additional data (e.g. version labels) 313 3.1.2. URI Method 315 A schema-uri leaf SHALL contain a URI that references another YANG 316 instance data file. The current instance data file will use the same 317 content schema as the referenced file. 319 The referenced instance data file MAY have no content-data if it is 320 used solely for specifying the content-schema. The referenced YANG 321 instance data file might use the INLINE method or might use the URI 322 method to reference further instance data file(s). However at the 323 end of this reference chain there MUST be an instance data file using 324 the INLINE method. 326 If a referenced instance data file is not available the revision 327 data, supported features and deviations for the target YANG modules 328 are unknown. 330 The URI method is advantageous when the user wants to avoid the 331 overhead of specifying the content-schema in each instance data file: 332 E.g. In Use Case 6, when the system creates a diagnostic file every 333 minute to document the state of the server. 335 3.2. Examples 337 The following example is based on "UC1, Documenting Server 338 Capabilities". It provides (a shortened) list of supported YANG 339 modules and Netconf capabilities for a server. It uses the inline 340 method to specify the content-schema. 342 343 345 acme-router-modules 346 347 ietf-yang-library@2016-06-21.yang 348 349 350 351 352 ietf-yang-library 353 2016-06-21 354 355 356 ietf-netconf-monitoring 357 2010-10-04 358 359 360 361 362 1956-10-23 363 Initial version 364 365 Defines the minimal set of modules that any acme-router 366 will contain. 367 info@acme.com 368 369 372 373 374 ietf-yang-library 375 2016-06-21 376 377 urn:ietf:params:xml:ns:yang:ietf-yang-library 378 379 implement 380 381 382 ietf-system 383 2014-08-06 384 urn:ietf:params:xml:ns:yang:ietf-system 385 sys:authentication 386 sys:local-users 387 388 acme-system-ext 389 2018-08-06 390 391 implement 392 393 394 ietf-yang-types 395 2013-07-15 396 urn:ietf:params:xml:ns:yang:ietf-yang-types 397 398 import 399 400 401 acme-system-ext 402 2018-08-06 403 urn:rdns:acme.com:oammodel:acme-system-ext 404 405 implement 406 407 408 409 410 411 urn:ietf:params:netconf:capability:validate:1.1 412 413 414 415 416 418 Figure 1: XML Instance Data Set - Use case 1, Documenting server 419 capabilities 421 The following example is based on "UC2, Preloading Default 422 Configuration". It provides a (shortened) default rule set for a 423 read-only operator role. It uses the inline method for specifying 424 the content-schema. 426 427 429 read-only-acm-rules 430 ietf-yang-library@2019-01-04.yang 431 432 433 434 all 435 436 ietf-netconf-acm 437 2012-02-22 438 439 440 441 442 443 1776-07-04 444 Initial version 445 446 Access control rules for a read-only role. 447 448 449 true 450 deny 451 deny 452 453 read-only-role 454 read-only-group 455 456 read-all 457 * 458 read 459 permit 460 461 462 463 464 466 Figure 2: XML Instance Data Set - Use case 2, Preloading access 467 control data 469 The following example is based on UC6 Storing diagnostics data. An 470 instance data set is produced by the server every 15 minutes that 471 contains statistics about NETCONF. As a new set is produced 472 periodically many times a day a revision-date would be useless; 473 instead a timestamp is included. 475 { 476 "ietf-yang-instance-data:instance-data-set": { 477 "name": "acme-router-netconf-diagnostics", 478 "schema-uri": "file:///acme-netconf-diagnostics-yanglib.json", 479 "timestamp": "2018-01-25T17:00:38Z", 480 "description": 481 "Netconf statistics", 482 "content-data": { 483 "ietf-netconf-monitoring:netconf-state": { 484 "statistics": { 485 "netconf-start-time ": "2018-12-05T17:45:00Z", 486 "in-bad-hellos ": "32", 487 "in-sessions ": "397", 488 "dropped-sessions ": "87", 489 "in-rpcs ": "8711", 490 "in-bad-rpcs ": "408", 491 "out-rpc-errors ": "408", 492 "out-notifications": "39007" 493 } 494 } 495 } 496 } 497 } 499 Figure 3: JSON Instance Data File example - UC6 Storing diagnostics 500 data 502 4. Data Life cycle 504 In UC2 "Preloading default configuration data" the loaded data may be 505 changed later e.g. by management operations. In UC6 "Storing 506 Diagnostics data" the diagnostics values may change on device every 507 second. 509 YANG instance data is a snap-shot of information at a specific point 510 of time. If the data changes afterwards this is not represented in 511 the instance data set anymore. The valid values can be retrieved in 512 run-time via NETCONF/RESTCONF or received e.g. in Yang-Push 513 notifications. 515 Whether the instance data changes and if so, when and how, SHOULD be 516 described either in the instance data set's description statement or 517 in some other implementation specific manner. 519 5. Delivery of Instance Data 521 Instance data sets that are produced as a result of some sort of 522 specification or design effort SHOULD be available without the need 523 for a live server e.g. via download from the vendor's website, or in 524 any other way product documentation is distributed. 526 Other instance data sets may be read from or produced by the YANG 527 server itself e.g. UC6 documenting diagnostic data. 529 6. Backwards Compatibility 531 The concept of backwards compatibility and what changes are backwards 532 compatible are not defined for instance data sets as it is highly 533 dependent on the specific use case and the content-schema. 535 For instance data that is the result of a design or specification 536 activity some changes that may be good to avoid are listed. YANG 537 uses the concept of managed entities identified by key values; if the 538 connection between the represented entity and the key value is not 539 preserved during an update this may lead to problems. 541 o If the key value of a list entry that represents the same managed 542 entity as before is changed, the user may mistakenly identify the 543 list entry as new. 545 o If the meaning of a list entry is changed, but the key values are 546 not (e.g. redefining an alarm-type but not changing its alarm- 547 type-id) the change may not be noticed. 549 o If the key value of a previously removed list entry is reused for 550 a different entity, the change may be mis-interpreted as 551 reintroducing the previous entity. 553 7. Yang Instance Data Model 555 7.1. Tree Diagram 557 The following tree diagram [RFC8340] provides an overview of the data 558 model. 560 module: ietf-yang-instance-data 561 structure instance-data-set: 562 +--rw name? string 563 +--rw (content-schema-spec)? 564 | +--:(inline) 565 | | +--rw inline-spec* string 566 | | +--rw inline-content-schema 567 | +--:(uri) 568 | +--rw schema-uri? inet:uri 569 +--rw description? string 570 +--rw contact? string 571 +--rw organization? string 572 +--rw datastore? ds:datastore-ref 573 +--rw revision* [date] 574 | +--rw date string 575 | +--rw description? string 576 +--rw timestamp? yang:date-and-time 577 +--rw content-data? 579 7.2. YANG Model 581 file "ietf-yang-instance-data@2019-07-04.yang" 582 module ietf-yang-instance-data { 583 yang-version 1.1; 584 namespace 585 "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"; 586 prefix yid ; 588 import ietf-yang-structure-ext { prefix sx; } 589 import ietf-datastores { prefix ds; } 590 import ietf-inet-types { prefix inet; } 591 import ietf-yang-types { prefix yang; } 592 import ietf-yang-metadata { prefix "md"; } 594 organization "IETF NETMOD Working Group"; 595 contact 596 "WG Web: 597 WG List: 599 Author: Balazs Lengyel 600 "; 602 description "The module defines the structure and content of YANG 603 instance data sets. 605 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 606 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 607 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 608 are to be interpreted as described in BCP 14 (RFC 2119) 609 (RFC 8174) when, and only when, they appear in all 610 capitals, as shown here. 612 Copyright (c) 2019 IETF Trust and the persons identified as 613 authors of the code. All rights reserved. 615 Redistribution and use in source and binary forms, with or 616 without modification, is permitted pursuant to, and subject 617 to the license terms contained in, the Simplified BSD License 618 set forth in Section 4.c of the IETF Trust's Legal Provisions 619 Relating to IETF Documents 620 (http://trustee.ietf.org/license-info). 622 This version of this YANG module is part of RFC XXXX; see 623 the RFC itself for full legal notices."; 625 revision 2019-07-04 { 626 description "Initial revision."; 627 reference "RFC XXXX: YANG Instance Data Format"; 628 } 630 md:annotation entity-tag { 631 type string; 632 description "Used to encode the entity-tag defined in 633 RFC8040 for the annotated instance."; 634 reference "RESTCONF Protocol RFC8040"; 635 } 637 md:annotation last-modified { 638 type yang:date-and-time; 639 description "Contains the date and time when the annotated 640 instance was last modified (or created)."; 641 reference "RESTCONF Protocol RFC8040"; 642 } 644 sx:structure instance-data-set { 645 description "A data structure to define a format for a 646 YANG instance data set.Consists of meta-data about 647 the instance data set and the real content-data."; 649 leaf name { 650 type string; 651 description "Name of the YANG instance data set."; 652 } 654 choice content-schema-spec { 655 description "Specification of the content-schema"; 657 case inline { 658 leaf-list inline-spec { 659 type string { 660 pattern '.+@\d{4}-\d{2}-\d{2}\.yang'; 661 } 662 min-elements 1; 663 ordered-by user; 664 description 665 "Indicates that content defining Yang modules 666 are specified inline. 667 Each value MUST be a YANG Module name including the 668 revision-date as defined for YANG file names in RFC7950. 670 E.g. ietf-yang-library@2016-06-21.yang 672 The first item is either ietf-yang-library or some other 673 YANG module that contains a list of YANG modules with 674 their name, revision-date, supported-features and 675 deviations. 676 As some versions of ietf-yang-library MAY contain 677 different module-sets for different datastores, if 678 multiple module-sets are included, the instance data set's 679 meta-data MUST contain the datastore information and 680 instance data for the ietf-yang-library MUST also contain 681 information specifying the module-set for the relevant 682 datastore. 684 Subsequent items MAY specify YANG modules augmenting the 685 first module with useful data (e.g. a version label)."; 686 } 687 anydata inline-content-schema { 688 mandatory true; 689 description "Instance data corresponding to the YANG modules 690 specified in the inline-spec nodes defining the set 691 of content defining Yang YANG modules for this 692 instance-data-set."; 693 } 694 } 696 case uri { 697 leaf schema-uri { 698 type inet:uri; 699 description 700 "A reference to another YANG instance data file. 701 This instance data file will use the same set of target 702 YANG modules, revisions, supported features and deviations 703 as the referenced YANG instance data file."; 704 } 705 } 706 } 708 leaf-list description { 709 type string; 710 description "Description of the instance data set."; 711 } 713 leaf contact { 714 type string; 715 description "Contact information for the person or 716 organization to whom queries concerning this 717 instance data set should be sent."; 718 } 720 leaf organization { 721 type string; 722 description "Organization responsible for the instance 723 data set."; 724 } 726 leaf datastore { 727 type ds:datastore-ref; 728 description "The identity of the datastore with which the 729 instance data set is associated e.g. the datastore from 730 where the data was read or the datastore where the data 731 could be loaded or the datastore which is being documented. 732 If a single specific datastore can not be specified, the 733 leaf MUST be absent. 735 If this leaf is absent, then the datastore to which the 736 instance data belongs is undefined."; 737 } 739 list revision { 740 key date; 741 description "Instance data sets that are produced as 742 a result of some sort of specification or design effort 743 SHOULD have at least one revision entry. For every 744 published editorial change, a new one SHOULD be added 745 in front of the revisions sequence so that all 746 revisions are in reverse chronological order. 748 For instance data sets that are read from 749 or produced by a server or otherwise 750 subject to frequent updates or changes, revision 751 SHOULD NOT be present"; 753 leaf date { 754 type string { 755 pattern '\d{4}-\d{2}-\d{2}'; 756 } 757 description "Specifies the date the instance data set 758 was last modified. Formatted as YYYY-MM-DD"; 759 } 761 leaf description { 762 type string; 763 description 764 "Description of this revision of the instance data set."; 765 } 766 } 768 leaf timestamp { 769 type yang:date-and-time; 770 description "The date and time when the instance data set 771 was last modified. 773 For instance data sets that are read from or produced 774 by a server or otherwise subject to frequent 775 updates or changes, timestamp SHOULD be present"; 776 } 778 anydata content-data { 779 description "Contains the real instance data. 780 The data MUST conform to the relevant YANG Modules specified 781 either in the content-schema-spec or in some other 782 implementation specific manner."; 783 } 784 } 785 } 786 788 8. Security Considerations 790 Depending on the nature of the instance data, instance data files MAY 791 need to be handled in a secure way. The same type of handling should 792 be applied, that would be needed for the result of a operation 793 returning the same data. 795 9. IANA Considerations 797 This document registers one URI and one YANG module. 799 9.1. URI Registration 801 This document registers one URI in the IETF XML registry [RFC3688]. 802 Following the format in RFC 3688, the following registration is 803 requested to be made: 805 URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 807 Registrant Contact: The IESG. 809 XML: N/A, the requested URI is an XML namespace. 811 9.2. YANG Module Name Registration 813 This document registers one YANG module in the YANG Module Names 814 registry [RFC6020]. 816 name: ietf-yang-instance-data 817 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 818 prefix: yid 819 reference: RFC XXXX 821 10. Acknowledgments 823 For their valuable comments, discussions, and feedback, we wish to 824 acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe 825 Clarke, Kent Watsen Martin Bjorklund, Ladislav Lhotka, Qin Wu and 826 other members of the Netmod WG. 828 11. References 830 11.1. Normative References 832 [I-D.ietf-netmod-yang-data-ext] 833 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 834 Structure Extensions", draft-ietf-netmod-yang-data-ext-03 835 (work in progress), April 2019. 837 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 838 DOI 10.17487/RFC3688, January 2004, 839 . 841 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 842 the Network Configuration Protocol (NETCONF)", RFC 6020, 843 DOI 10.17487/RFC6020, October 2010, 844 . 846 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 847 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 848 . 850 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 851 RFC 7950, DOI 10.17487/RFC7950, August 2016, 852 . 854 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 855 RFC 7951, DOI 10.17487/RFC7951, August 2016, 856 . 858 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 859 RFC 7952, DOI 10.17487/RFC7952, August 2016, 860 . 862 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 863 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 864 . 866 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 867 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 868 . 870 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 871 and R. Wilton, "Network Management Datastore Architecture 872 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 873 . 875 [RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 876 and R. Wilton, "NETCONF Extensions to Support the Network 877 Management Datastore Architecture", RFC 8526, 878 DOI 10.17487/RFC8526, March 2019, 879 . 881 [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 882 and R. Wilton, "RESTCONF Extensions to Support the Network 883 Management Datastore Architecture", RFC 8527, 884 DOI 10.17487/RFC8527, March 2019, 885 . 887 11.2. Informative References 889 [I-D.ietf-ccamp-alarm-module] 890 Vallin, S. and M. Bjorklund, "YANG Alarm Module", draft- 891 ietf-ccamp-alarm-module-09 (work in progress), April 2019. 893 [I-D.ietf-netconf-rfc7895bis] 894 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 895 and R. Wilton, "YANG Library", draft-ietf-netconf- 896 rfc7895bis-07 (work in progress), October 2018. 898 [I-D.ietf-netconf-yang-push] 899 Clemm, A. and E. Voit, "Subscription to YANG Datastores", 900 draft-ietf-netconf-yang-push-25 (work in progress), May 901 2019. 903 [I-D.wu-netconf-restconf-factory-restore] 904 Wu, Q., Lengyel, B., and Y. Niu, "Factory default 905 Setting", draft-wu-netconf-restconf-factory-restore-03 906 (work in progress), October 2018. 908 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 909 Requirement Levels", BCP 14, RFC 2119, 910 DOI 10.17487/RFC2119, March 1997, 911 . 913 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 914 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 915 May 2017, . 917 Appendix A. Open Issues 919 o - 921 Appendix B. Changes between revisions 923 v02 - v03 925 o target renamed to "content-schema" and "content defining Yang 926 module(s)" 928 o Made name of instance data set optional 930 o Updated according to draft-ietf-netmod-tang-data-ext-02 932 o Clarified that entity-tag and last-modified timestamp are encoded 933 as metadata. While htey contain useful data, the HTTP-header 934 based encoding from Restconf is not suitable. 936 o 938 v01 - v02 940 o Removed design time from terminology 942 o Defined the format of the content-data part by referencing various 943 RFCs and drafts instead of the result of the get-data and get 944 operations. 946 o Changed target-ptr to a choice 948 o Inline target-ptr may include augmenting modules and alternatives 949 to ietf-yang-library 951 o Moved list of target modules into a separate 952 element. 954 o Added backwards compatibility considerations 956 v00 - v01 958 o Added the target-ptr metadata with 3 methods 960 o Added timestamp metadata 962 o Removed usage of dedicated .yid file extension 964 o Added list of use cases 966 o Added list of principles 968 o Updated examples 970 o Moved detailed use case descriptions to appendix 972 v05 - v00-netmod 974 o New name for the draft following Netmod workgroup adoption. No 975 other changes 977 v04 - v05 979 o Changed title and introduction to clarify that this draft is only 980 about the file format and documenting server capabilities is just 981 a use case. 983 o Added reference to draft-wu-netconf-restconf-factory-restore 984 o Added new open issues. 986 v03 - v04 988 o Updated changelog for v02-v03 990 v02 - v03 992 o Updated the document according to comments received at IETF102 994 o Added parameter to specify datastore 996 o Rearranged chapters 998 o Added new use case: Documenting Factory Default Settings 1000 o Added "Target YANG Module" to terminology 1002 o Clarified that instance data is a snapshot valid at the time of 1003 creation, so it does not contain any later changes. 1005 o Removed topics from Open Issues according to comments received at 1006 IETF102 1008 v01 - v02 1010 o The recommendation to document server capabilities was changed to 1011 be just the primary use-case. (Merged chapter 4 into the use case 1012 chapter.) 1014 o Stated that RFC7950/7951 encoding must be followed which also 1015 defines (dis)allowed whitespace rules. 1017 o Added UTF-8 encoding as it is not specified in t950 for instance 1018 data 1020 o added XML declaration 1022 v00 - v01 1024 o Redefined using yang-data-ext 1026 o Moved metadata into ordinary leafs/leaf-lists 1028 Appendix C. Detailed Use Cases - Non-Normative 1030 C.1. Use Cases 1032 We present a number of use cases were YANG instance data is needed. 1034 C.1.1. Use Case 1: Early Documentation of Server Capabilities 1036 A server has a number of server-capabilities that are defined in YANG 1037 modules and can be retrieved from the server using protocols like 1038 NETCONF or RESTCONF. server capabilities include 1040 o data defined in ietf-yang-library: YANG modules, submodules, 1041 features, deviations, schema-mounts, datastores supported 1042 ([I-D.ietf-netconf-rfc7895bis]) 1044 o alarms supported ([I-D.ietf-ccamp-alarm-module]) 1046 o data nodes, subtrees that support or do not support on-change 1047 notifications ([I-D.ietf-netconf-yang-push]) 1049 o netconf-capabilities in ietf-netconf-monitoring 1051 While it is good practice to allow a client to query these 1052 capabilities from the live server, that is often not possible. 1054 Often when a network node is released an associated NMS (network 1055 management system) is also released with it. The NMS depends on the 1056 capabilities of the server. During NMS implementation information 1057 about server capabilities is needed. If the information is not 1058 available early in some off-line document, but only as instance data 1059 from the live network node, the NMS implementation will be delayed, 1060 because it has to wait for the network node to be ready. Also 1061 assuming that all NMS implementors will have a correctly configured 1062 network node available to retrieve data from, is a very expensive 1063 proposition. (An NMS may handle dozens of node types.) 1065 Network operators often build their own home-grown NMS systems that 1066 needs to be integrated with a vendor's network node. The operator 1067 needs to know the network node's server capabilities in order to do 1068 this. Moreover the network operator's decision to buy a vendor's 1069 product may even be influenced by the network node's OAM feature set 1070 documented as the Server's capabilities. 1072 Beside NMS implementors, system integrators and many others also need 1073 the same information early. Examples could be model driven testing, 1074 generating documentation, etc. 1076 Most server-capabilities are relatively stable and change only during 1077 upgrade or due to licensing or addition or removal of HW. They are 1078 usually defined by a vendor at design time, before the product is 1079 released. It feasible and advantageous to define/document them early 1080 e.g. in a YANG instance data File. 1082 It is anticipated that a separate IETF document will define in detail 1083 how and which set of server capabilities should be documented. 1085 C.1.2. Use Case 2: Preloading Data 1087 There are parts of the configuration that must be fully configurable 1088 by the operator, however for which often a simple default 1089 configuration will be sufficient. 1091 One example is access control groups/roles and related rules. While 1092 a sophisticated operator may define dozens of different groups often 1093 a basic (read-only operator, read-write system administrator, 1094 security-administrator) triplet will be enough. Vendors will often 1095 provide such default configuration data to make device configuration 1096 easier for an operator. 1098 Defining Access control data is a complex task. To help the device 1099 vendor pre-defines a set of default groups (/nacm:nacm/groups) and 1100 rules for these groups to access specific parts of common models 1101 (/nacm:nacm/rule-list/rule). 1103 YANG instance data files are used to document and/or preload the 1104 default configuration. 1106 C.1.3. Use Case 3: Documenting Factory Default Settings 1108 Nearly every server has a factory default configuration. If the 1109 system is really badly misconfigured or if the current configuration 1110 is to be abandoned the system can be reset to this default. 1112 In Netconf the operation can already be used to reset 1113 the startup datastore. There are ongoing efforts to introduce a new, 1114 more generic reset-datastore operation for the same purpose 1115 [I-D.wu-netconf-restconf-factory-restore] 1117 The operator currently has no way to know what the default 1118 configuration actually contains. YANG instance data can be used to 1119 document the factory default configuration. 1121 Authors' Addresses 1122 Balazs Lengyel 1123 Ericsson 1124 Magyar Tudosok korutja 11 1125 1117 Budapest 1126 Hungary 1128 Phone: +36-70-330-7909 1129 Email: balazs.lengyel@ericsson.com 1131 Benoit Claise 1132 Cisco Systems, Inc. 1133 De Kleetlaan 6a b1 1134 1831 Diegem 1135 Belgium 1137 Phone: +32 2 704 5622 1138 Email: bclaise@cisco.com