idnits 2.17.1 draft-ietf-netmod-yang-instance-file-format-04.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 (August 12, 2019) is 1718 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 840, but no explicit reference was found in the text == Outdated reference: A later version (-05) exists of draft-ietf-netmod-yang-data-ext-04 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: February 13, 2020 Cisco Systems, Inc. 6 August 12, 2019 8 YANG Instance Data File Format 9 draft-ietf-netmod-yang-instance-file-format-04 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 February 13, 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. Simplified-Inline Method . . . . . . . . . . . . . . 7 62 3.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 7 63 3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 64 4. Data Life cycle . . . . . . . . . . . . . . . . . . . . . . . 12 65 5. Delivery of Instance Data . . . . . . . . . . . . . . . . . . 13 66 6. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 13 67 7. Yang Instance Data Model . . . . . . . . . . . . . . . . . . 13 68 7.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 13 69 7.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 14 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 71 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 72 9.1. URI Registration . . . . . . . . . . . . . . . . . . . . 19 73 9.2. YANG Module Name Registration . . . . . . . . . . . . . . 19 74 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 75 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 76 11.1. Normative References . . . . . . . . . . . . . . . . . . 19 77 11.2. Informative References . . . . . . . . . . . . . . . . . 20 78 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 21 79 Appendix B. Changes between revisions . . . . . . . . . . . . . 21 80 Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 22 81 C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 22 82 C.1.1. Use Case 1: Early Documentation of Server 83 Capabilities . . . . . . . . . . . . . . . . . . . . 22 84 C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 24 85 C.1.3. Use Case 3: Documenting Factory Default Settings . . 24 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 88 1. Terminology 90 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 91 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 92 "OPTIONAL" in this document are to be interpreted as described in BCP 93 14 RFC 2119 [RFC2119] RFC 8174 [RFC8174] when, and only when, they 94 appear in all capitals, as shown here. 96 Instance Data Set: A named set of data items decorated with metadata 97 that can be used as instance data in a YANG data tree. 99 Instance Data File: A file containing an instance data set formatted 100 according to the rules described in this document. 102 Content-schema: A set of YANG modules with their revision,suupported 103 features and deviations for which the instance data set contains 104 instance data 106 Content defining Yang module(s): YANG module(s) that make up the 107 content-schema 109 YANG Instance Data, or just instance data for short, is data that 110 could be stored in a datastore and whose syntax and semantics is 111 defined by YANG models. 113 The term Server is used as defined in [RFC8342] 115 2. Introduction 117 There is a need to document data defined in YANG models when a live 118 server is not available. Data is often needed already at design or 119 implementation time or needed by groups that do not have a live 120 running server available. To facilitate this off-line delivery of 121 data this document specifies a standard format for YANG instance data 122 sets and YANG instance data files. 124 The following is a list of already implemented and potential use 125 cases. 127 UC1 Documentation of server capabilities 129 UC2 Preloading default configuration data 131 UC3 Documenting Factory Default Settings 133 UC4 Instance data used as backup 135 UC5 Storing the configuration of a device, e.g. for archive or audit 136 purposes 138 UC6 Storing diagnostics data 140 UC7 Allowing YANG instance data to potentially be carried within 141 other IPC message formats 143 UC8 Default instance data used as part of a templating solution 144 UC9 Providing data examples in RFCs or internet drafts 146 In Appendix C we describe the first three use cases in detail. 148 There are many and varied use cases where YANG instance data could be 149 used. We do not want to limit future uses of instance data sets, so 150 specifying how and when to use Yang instance data is out of scope for 151 this document. It is anticipated that other documents will define 152 specific use cases. Use cases are listed here only to indicate the 153 need for this work. 155 2.1. Principles 157 The following is a list of the basic principles of the instance data 158 format: 160 P1 Two standard formats are based on the XML and the JSON encoding 162 P2 Re-use existing formats similar to the response to a 163 operation/request 165 P3 Add metadata about the instance data set (Section 3, Paragraph 9) 167 P4 A YANG instance data set may contain data for many YANG modules 169 P5 Instance data may include configuration data, state data or a mix 170 of the two 172 P6 Partial data sets are allowed 174 P7 YANG instance data format may be used for any data for which YANG 175 module(s) are defined and available to the reader, independent of 176 whether the module is actually implemented by a server 178 3. Instance Data File Format 180 A YANG instance data file MUST contain a single instance data set and 181 no additional data. 183 The format of the instance data set is defined by the ietf-yang- 184 instance-data YANG module. It is made up of a header part and 185 content-data. The header part carries metadata for the instance data 186 set. The content-data, defined as an anydata data node, carries the 187 "real data" that we want to document/provide. The syntax and 188 semantics of content-data is defined by the content-schema. 190 Two formats are specified based on the XML and JSON YANG encodings. 191 Later as other YANG encodings (e.g. CBOR) are defined further 192 instance data formats may be specified. 194 The content-data part SHALL follow the encoding rules defined in 195 [RFC7950] for XML and [RFC7951] for JSON and MUST use UTF-8 character 196 encoding. Content-data MAY include: 198 metadata as defined by [RFC7952]. 200 a default attribute as defined in [RFC6243] section 6. and in 201 [RFC8040] section 4.8.9. 203 origin metadata as specified in [RFC8526] and [RFC8527] 205 implementation specific metadata. Unknown metadata MUST be 206 ignored by users of YANG instance data, allowing it to be used 207 later for other purposes. 209 in the XML format implementation specific XML attributes. Unknown 210 attributes MUST be ignored by users of YANG instance data, 211 allowing them to be used later for other purposes. 213 The content-data part will be very similar to the result returned for 214 a NETCONF or for a RESTCONF get operation. 216 The content-data part MUST conform to the content-schema. An 217 instance data set MAY contain data for any number of YANG modules; if 218 needed it MAY carry the complete configuration and state data set for 219 a server. Default values SHOULD NOT be included. 221 Config=true and config=false data MAY be mixed in the instance data 222 file. 224 Instance data files MAY contain partial data sets. This means 225 mandatory, min-elements, require-instance=true, must and when 226 constrains MAY be violated. 228 The name of the instance data file SHOULD take one of the following 229 two forms: 231 If revision information inside the data set is present 233 * instance-data-set-name ['@' revision-date] '.filetype' 235 * E.g. acme-router-modules@2018-01-25.xml 236 If the leaf name is present in the instance data header this MUST 237 be used. Revision-date MUST be set to the latest revision date 238 inside the instance data set. 240 If timestamp information inside the data set is present 242 * instance-data-set-name ['@' timestamp] '.filetype' 244 * E.g. acme-router-modules@2018-01-25T15_06_34_3+01_00.json 246 If the leaf name is present in the instance data header this MUST 247 be used. If the leaf timestamp is present in the instance data 248 header this MUST be used; the semicolons and the decimal point if 249 present shall be replaced by underscores. 251 The revision date or timestamp is optional. ".filetype" SHALL be 252 ".json" or ".xml" according to the format used. 254 Metadata, information about the data set itself SHOULD be included in 255 the instance data set. Some metadata items are defined in the YANG 256 module ietf-yang-instance-data, but other items MAY also be used. 257 Metadata SHOULD include: 259 o Name of the data set 261 o Content schema specification 263 o Description of the instance data set. The description SHOULD 264 contain information whether and how the data can change during the 265 lifetime of the server. 267 3.1. Specifying the Content Schema 269 To properly understand and use an instance data set the user needs to 270 know the content-schema. One of the following methods SHOULD be 271 used: 273 Inline method: Include the needed information as part of the 274 instance data set. 276 Simplified-Inline method: Include the needed information as part 277 of the instance data set; short specification. 279 URI method: Include a URI that references another YANG instance 280 data file. This instance data file will use the same content- 281 schema as the referenced YANG instance data file. (if you don't 282 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. Simplified-Inline Method 315 The instance data set contains a list of content defining YANG 316 modules including the revision date for each. Usage of this method 317 implies that the modules are used without any deviations and with all 318 features supported. 320 3.1.3. URI Method 322 A schema-uri leaf SHALL contain a URI that references another YANG 323 instance data file. The current instance data file will use the same 324 content schema as the referenced file. 326 The referenced instance data file MAY have no content-data if it is 327 used solely for specifying the content-schema. The referenced YANG 328 instance data file might use the INLINE method or might use the URI 329 method to reference further instance data file(s). However at the 330 end of this reference chain there MUST be an instance data file using 331 the INLINE method. 333 If a referenced instance data file is not available the revision 334 data, supported features and deviations for the target YANG modules 335 are unknown. 337 The URI method is advantageous when the user wants to avoid the 338 overhead of specifying the content-schema in each instance data file: 339 E.g. In Use Case 6, when the system creates a diagnostic file every 340 minute to document the state of the server. 342 3.2. Examples 344 The following example is based on "UC1, Documenting Server 345 Capabilities". It provides (a shortened) list of supported YANG 346 modules and Netconf capabilities for a server. It uses the inline 347 method to specify the content-schema. 349 350 352 acme-router-modules 353 354 ietf-yang-library@2016-06-21.yang 355 356 357 358 359 ietf-yang-library 360 2016-06-21 361 362 363 ietf-netconf-monitoring 364 2010-10-04 365 366 367 368 369 1956-10-23 370 Initial version 371 372 Defines the minimal set of modules that any acme-router 373 will contain. 374 info@acme.com 375 376 379 380 381 ietf-yang-library 382 2016-06-21 383 384 urn:ietf:params:xml:ns:yang:ietf-yang-library 385 386 implement 387 388 389 ietf-system 390 2014-08-06 391 urn:ietf:params:xml:ns:yang:ietf-system 392 sys:authentication 393 sys:local-users 394 395 acme-system-ext 396 2018-08-06 397 398 implement 399 400 401 ietf-yang-types 402 2013-07-15 403 urn:ietf:params:xml:ns:yang:ietf-yang-types 404 405 import 406 407 408 acme-system-ext 409 2018-08-06 410 urn:rdns:acme.com:oammodel:acme-system-ext 411 412 implement 413 414 415 416 417 418 urn:ietf:params:netconf:capability:validate:1.1 419 420 421 422 423 424 Figure 1: XML Instance Data Set - Use case 1, Documenting server 425 capabilities 427 The following example is based on "UC2, Preloading Default 428 Configuration". It provides a (shortened) default rule set for a 429 read-only operator role. It uses the inline method for specifying 430 the content-schema. 432 433 435 read-only-acm-rules 436 ietf-yang-library@2019-01-04.yang 437 438 439 440 all 441 442 ietf-netconf-acm 443 2012-02-22 444 445 446 447 448 449 1776-07-04 450 Initial version 451 452 Access control rules for a read-only role. 453 454 455 true 456 deny 457 deny 458 459 read-only-role 460 read-only-group 461 462 read-all 463 * 464 read 465 permit 466 467 468 469 470 472 Figure 2: XML Instance Data Set - Use case 2, Preloading access 473 control data 475 The following example is based on UC6 Storing diagnostics data. An 476 instance data set is produced by the server every 15 minutes that 477 contains statistics about NETCONF. As a new set is produced 478 periodically many times a day a revision-date would be useless; 479 instead a timestamp is included. 481 { 482 "ietf-yang-instance-data:instance-data-set": { 483 "name": "acme-router-netconf-diagnostics", 484 "schema-uri": "file:///acme-netconf-diagnostics-yanglib.json", 485 "timestamp": "2018-01-25T17:00:38Z", 486 "description": 487 "Netconf statistics", 488 "content-data": { 489 "ietf-netconf-monitoring:netconf-state": { 490 "statistics": { 491 "netconf-start-time ": "2018-12-05T17:45:00Z", 492 "in-bad-hellos ": "32", 493 "in-sessions ": "397", 494 "dropped-sessions ": "87", 495 "in-rpcs ": "8711", 496 "in-bad-rpcs ": "408", 497 "out-rpc-errors ": "408", 498 "out-notifications": "39007" 499 } 500 } 501 } 502 } 503 } 505 Figure 3: JSON Instance Data File example - UC6 Storing diagnostics 506 data 508 4. Data Life cycle 510 In UC2 "Preloading default configuration data" the loaded data may be 511 changed later e.g. by management operations. In UC6 "Storing 512 Diagnostics data" the diagnostics values may change on device every 513 second. 515 YANG instance data is a snap-shot of information at a specific point 516 of time. If the data changes afterwards this is not represented in 517 the instance data set anymore. The valid values can be retrieved in 518 run-time via NETCONF/RESTCONF or received e.g. in Yang-Push 519 notifications. 521 Whether the instance data changes and if so, when and how, SHOULD be 522 described either in the instance data set's description statement or 523 in some other implementation specific manner. 525 5. Delivery of Instance Data 527 Instance data sets that are produced as a result of some sort of 528 specification or design effort SHOULD be available without the need 529 for a live server e.g. via download from the vendor's website, or in 530 any other way product documentation is distributed. 532 Other instance data sets may be read from or produced by the YANG 533 server itself e.g. UC6 documenting diagnostic data. 535 6. Backwards Compatibility 537 The concept of backwards compatibility and what changes are backwards 538 compatible are not defined for instance data sets as it is highly 539 dependent on the specific use case and the content-schema. 541 For instance data that is the result of a design or specification 542 activity some changes that may be good to avoid are listed. YANG 543 uses the concept of managed entities identified by key values; if the 544 connection between the represented entity and the key value is not 545 preserved during an update this may lead to problems. 547 o If the key value of a list entry that represents the same managed 548 entity as before is changed, the user may mistakenly identify the 549 list entry as new. 551 o If the meaning of a list entry is changed, but the key values are 552 not (e.g. redefining an alarm-type but not changing its alarm- 553 type-id) the change may not be noticed. 555 o If the key value of a previously removed list entry is reused for 556 a different entity, the change may be mis-interpreted as 557 reintroducing the previous entity. 559 7. Yang Instance Data Model 561 7.1. Tree Diagram 563 The following tree diagram [RFC8340] provides an overview of the data 564 model. 566 module: ietf-yang-instance-data 567 structure instance-data-set: 568 +--rw name? string 569 +--rw (content-schema-spec)? 570 | +--:(simplified-inline) 571 | +--rw module* string 572 | +--:(inline) 573 | | +--rw inline-spec* string 574 | | +--rw inline-content-schema 575 | +--:(uri) 576 | +--rw schema-uri? inet:uri 577 +--rw description? string 578 +--rw contact? string 579 +--rw organization? string 580 +--rw datastore? ds:datastore-ref 581 +--rw revision* [date] 582 | +--rw date string 583 | +--rw description? string 584 +--rw timestamp? yang:date-and-time 585 +--rw content-data? 587 7.2. YANG Model 589 file "ietf-yang-instance-data@2019-07-04.yang" 590 module ietf-yang-instance-data { 591 yang-version 1.1; 592 namespace 593 "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"; 594 prefix yid ; 596 import ietf-yang-structure-ext { prefix sx; } 597 import ietf-datastores { prefix ds; } 598 import ietf-inet-types { prefix inet; } 599 import ietf-yang-types { prefix yang; } 600 import ietf-yang-metadata { prefix "md"; } 602 organization "IETF NETMOD Working Group"; 603 contact 604 "WG Web: 605 WG List: 607 Author: Balazs Lengyel 608 "; 610 description "The module defines the structure and content of YANG 611 instance data sets. 613 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 614 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 615 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 616 are to be interpreted as described in BCP 14 (RFC 2119) 617 (RFC 8174) when, and only when, they appear in all 618 capitals, as shown here. 620 Copyright (c) 2019 IETF Trust and the persons identified as 621 authors of the code. All rights reserved. 623 Redistribution and use in source and binary forms, with or 624 without modification, is permitted pursuant to, and subject 625 to the license terms contained in, the Simplified BSD License 626 set forth in Section 4.c of the IETF Trust's Legal Provisions 627 Relating to IETF Documents 628 (http://trustee.ietf.org/license-info). 630 This version of this YANG module is part of RFC XXXX; see 631 the RFC itself for full legal notices."; 633 revision 2019-07-04 { 634 description "Initial revision."; 635 reference "RFC XXXX: YANG Instance Data Format"; 636 } 638 sx:structure instance-data-set { 639 description "A data structure to define a format for a 640 YANG instance data set.Consists of meta-data about 641 the instance data set and the real content-data."; 643 leaf name { 644 type string; 645 description "Name of the YANG instance data set."; 646 } 648 choice content-schema-spec { 649 description "Specification of the content-schema"; 651 case simplified-inline { 652 leaf-list module { 653 type string { 654 pattern '.+@\d{4}-\d{2}-\d{2}\.yang'; 655 } 656 description "The list of content defining YANG 657 modules including the revision date for each. 658 Usage of this leaf-list implies the modules are 659 used without any deviations and with all features 660 supported."; 661 } 663 } 664 case inline { 665 leaf-list inline-spec { 666 type string { 667 pattern '.+@\d{4}-\d{2}-\d{2}\.yang'; 668 } 669 min-elements 1; 670 ordered-by user; 671 description 672 "Indicates that content defining Yang modules 673 are specified inline. 674 Each value MUST be a YANG Module name including the 675 revision-date as defined for YANG file names in RFC7950. 677 E.g. ietf-yang-library@2016-06-21.yang 679 The first item is either ietf-yang-library or some other 680 YANG module that contains a list of YANG modules with 681 their name, revision-date, supported-features and 682 deviations. 683 As some versions of ietf-yang-library MAY contain 684 different module-sets for different datastores, if 685 multiple module-sets are included, the instance data set's 686 meta-data MUST contain the datastore information and 687 instance data for the ietf-yang-library MUST also contain 688 information specifying the module-set for the relevant 689 datastore. 691 Subsequent items MAY specify YANG modules augmenting the 692 first module with useful data (e.g. a version label)."; 693 } 694 anydata inline-content-schema { 695 mandatory true; 696 description "Instance data corresponding to the YANG modules 697 specified in the inline-spec nodes defining the set 698 of content defining Yang YANG modules for this 699 instance-data-set."; 700 } 701 } 703 case uri { 704 leaf schema-uri { 705 type inet:uri; 706 description 707 "A reference to another YANG instance data file. 708 This instance data file will use the same set of target 709 YANG modules, revisions, supported features and deviations 710 as the referenced YANG instance data file."; 712 } 713 } 714 } 716 leaf-list description { 717 type string; 718 description "Description of the instance data set."; 719 } 721 leaf contact { 722 type string; 723 description "Contact information for the person or 724 organization to whom queries concerning this 725 instance data set should be sent."; 726 } 728 leaf organization { 729 type string; 730 description "Organization responsible for the instance 731 data set."; 732 } 734 leaf datastore { 735 type ds:datastore-ref; 736 description "The identity of the datastore with which the 737 instance data set is associated e.g. the datastore from 738 where the data was read or the datastore where the data 739 could be loaded or the datastore which is being documented. 740 If a single specific datastore can not be specified, the 741 leaf MUST be absent. 743 If this leaf is absent, then the datastore to which the 744 instance data belongs is undefined."; 745 } 747 list revision { 748 key date; 749 description "Instance data sets that are produced as 750 a result of some sort of specification or design effort 751 SHOULD have at least one revision entry. For every 752 published editorial change, a new one SHOULD be added 753 in front of the revisions sequence so that all 754 revisions are in reverse chronological order. 756 For instance data sets that are read from 757 or produced by a server or otherwise 758 subject to frequent updates or changes, revision 759 SHOULD NOT be present"; 761 leaf date { 762 type string { 763 pattern '\d{4}-\d{2}-\d{2}'; 764 } 765 description "Specifies the date the instance data set 766 was last modified. Formatted as YYYY-MM-DD"; 767 } 769 leaf description { 770 type string; 771 description 772 "Description of this revision of the instance data set."; 773 } 774 } 776 leaf timestamp { 777 type yang:date-and-time; 778 description "The date and time when the instance data set 779 was last modified. 781 For instance data sets that are read from or produced 782 by a server or otherwise subject to frequent 783 updates or changes, timestamp SHOULD be present"; 784 } 786 anydata content-data { 787 description "Contains the real instance data. 788 The data MUST conform to the relevant YANG Modules specified 789 either in the content-schema-spec or in some other 790 implementation specific manner."; 791 } 792 } 793 } 794 796 8. Security Considerations 798 Depending on the nature of the instance data, instance data files MAY 799 need to be handled in a secure way. The same type of handling should 800 be applied, that would be needed for the result of a operation 801 returning the same data. 803 9. IANA Considerations 805 This document registers one URI and one YANG module. 807 9.1. URI Registration 809 This document registers one URI in the IETF XML registry [RFC3688]. 810 Following the format in RFC 3688, the following registration is 811 requested to be made: 813 URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 815 Registrant Contact: The IESG. 817 XML: N/A, the requested URI is an XML namespace. 819 9.2. YANG Module Name Registration 821 This document registers one YANG module in the YANG Module Names 822 registry [RFC6020]. 824 name: ietf-yang-instance-data 825 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 826 prefix: yid 827 reference: RFC XXXX 829 10. Acknowledgments 831 For their valuable comments, discussions, and feedback, we wish to 832 acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe 833 Clarke, Kent Watsen Martin Bjorklund, Ladislav Lhotka, Qin Wu and 834 other members of the Netmod WG. 836 11. References 838 11.1. Normative References 840 [I-D.ietf-netmod-yang-data-ext] 841 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 842 Structure Extensions", draft-ietf-netmod-yang-data-ext-04 843 (work in progress), July 2019. 845 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 846 DOI 10.17487/RFC3688, January 2004, 847 . 849 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 850 the Network Configuration Protocol (NETCONF)", RFC 6020, 851 DOI 10.17487/RFC6020, October 2010, 852 . 854 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 855 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 856 . 858 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 859 RFC 7950, DOI 10.17487/RFC7950, August 2016, 860 . 862 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 863 RFC 7951, DOI 10.17487/RFC7951, August 2016, 864 . 866 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 867 RFC 7952, DOI 10.17487/RFC7952, August 2016, 868 . 870 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 871 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 872 . 874 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 875 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 876 . 878 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 879 and R. Wilton, "Network Management Datastore Architecture 880 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 881 . 883 [RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 884 and R. Wilton, "NETCONF Extensions to Support the Network 885 Management Datastore Architecture", RFC 8526, 886 DOI 10.17487/RFC8526, March 2019, 887 . 889 [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 890 and R. Wilton, "RESTCONF Extensions to Support the Network 891 Management Datastore Architecture", RFC 8527, 892 DOI 10.17487/RFC8527, March 2019, 893 . 895 11.2. Informative References 897 [I-D.ietf-ccamp-alarm-module] 898 Vallin, S. and M. Bjorklund, "YANG Alarm Module", draft- 899 ietf-ccamp-alarm-module-09 (work in progress), April 2019. 901 [I-D.ietf-netconf-rfc7895bis] 902 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 903 and R. Wilton, "YANG Library", draft-ietf-netconf- 904 rfc7895bis-07 (work in progress), October 2018. 906 [I-D.ietf-netconf-yang-push] 907 Clemm, A. and E. Voit, "Subscription to YANG Datastores", 908 draft-ietf-netconf-yang-push-25 (work in progress), May 909 2019. 911 [I-D.wu-netconf-restconf-factory-restore] 912 Wu, Q., Lengyel, B., and Y. Niu, "Factory default 913 Setting", draft-wu-netconf-restconf-factory-restore-03 914 (work in progress), October 2018. 916 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 917 Requirement Levels", BCP 14, RFC 2119, 918 DOI 10.17487/RFC2119, March 1997, 919 . 921 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 922 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 923 May 2017, . 925 Appendix A. Open Issues 927 o - 929 Appendix B. Changes between revisions 931 v03 - v04 933 o removed entity-tag and last-modified timestamp 935 o Added simplified-inline method of content-schema specification 937 v02 - v03 939 o target renamed to "content-schema" and "content defining Yang 940 module(s)" 942 o Made name of instance data set optional 944 o Updated according to draft-ietf-netmod-yang-data-ext-03 946 o Clarified that entity-tag and last-modified timestamp are encoded 947 as metadata. While they contain useful data, the HTTP-header 948 based encoding from Restconf is not suitable. 950 v01 - v02 952 o Removed design time from terminology 954 o Defined the format of the content-data part by referencing various 955 RFCs and drafts instead of the result of the get-data and get 956 operations. 958 o Changed target-ptr to a choice 960 o Inline target-ptr may include augmenting modules and alternatives 961 to ietf-yang-library 963 o Moved list of target modules into a separate 964 element. 966 o Added backwards compatibility considerations 968 v00 - v01 970 o Added the target-ptr metadata with 3 methods 972 o Added timestamp metadata 974 o Removed usage of dedicated .yid file extension 976 o Added list of use cases 978 o Added list of principles 980 o Updated examples 982 o Moved detailed use case descriptions to appendix 984 Appendix C. Detailed Use Cases - Non-Normative 986 C.1. Use Cases 988 We present a number of use cases were YANG instance data is needed. 990 C.1.1. Use Case 1: Early Documentation of Server Capabilities 992 A server has a number of server-capabilities that are defined in YANG 993 modules and can be retrieved from the server using protocols like 994 NETCONF or RESTCONF. server capabilities include 995 o data defined in ietf-yang-library: YANG modules, submodules, 996 features, deviations, schema-mounts, datastores supported 997 ([I-D.ietf-netconf-rfc7895bis]) 999 o alarms supported ([I-D.ietf-ccamp-alarm-module]) 1001 o data nodes, subtrees that support or do not support on-change 1002 notifications ([I-D.ietf-netconf-yang-push]) 1004 o netconf-capabilities in ietf-netconf-monitoring 1006 While it is good practice to allow a client to query these 1007 capabilities from the live server, that is often not possible. 1009 Often when a network node is released an associated NMS (network 1010 management system) is also released with it. The NMS depends on the 1011 capabilities of the server. During NMS implementation information 1012 about server capabilities is needed. If the information is not 1013 available early in some off-line document, but only as instance data 1014 from the live network node, the NMS implementation will be delayed, 1015 because it has to wait for the network node to be ready. Also 1016 assuming that all NMS implementors will have a correctly configured 1017 network node available to retrieve data from, is a very expensive 1018 proposition. (An NMS may handle dozens of node types.) 1020 Network operators often build their own home-grown NMS systems that 1021 needs to be integrated with a vendor's network node. The operator 1022 needs to know the network node's server capabilities in order to do 1023 this. Moreover the network operator's decision to buy a vendor's 1024 product may even be influenced by the network node's OAM feature set 1025 documented as the Server's capabilities. 1027 Beside NMS implementors, system integrators and many others also need 1028 the same information early. Examples could be model driven testing, 1029 generating documentation, etc. 1031 Most server-capabilities are relatively stable and change only during 1032 upgrade or due to licensing or addition or removal of HW. They are 1033 usually defined by a vendor at design time, before the product is 1034 released. It feasible and advantageous to define/document them early 1035 e.g. in a YANG instance data File. 1037 It is anticipated that a separate IETF document will define in detail 1038 how and which set of server capabilities should be documented. 1040 C.1.2. Use Case 2: Preloading Data 1042 There are parts of the configuration that must be fully configurable 1043 by the operator, however for which often a simple default 1044 configuration will be sufficient. 1046 One example is access control groups/roles and related rules. While 1047 a sophisticated operator may define dozens of different groups often 1048 a basic (read-only operator, read-write system administrator, 1049 security-administrator) triplet will be enough. Vendors will often 1050 provide such default configuration data to make device configuration 1051 easier for an operator. 1053 Defining Access control data is a complex task. To help the device 1054 vendor pre-defines a set of default groups (/nacm:nacm/groups) and 1055 rules for these groups to access specific parts of common models 1056 (/nacm:nacm/rule-list/rule). 1058 YANG instance data files are used to document and/or preload the 1059 default configuration. 1061 C.1.3. Use Case 3: Documenting Factory Default Settings 1063 Nearly every server has a factory default configuration. If the 1064 system is really badly misconfigured or if the current configuration 1065 is to be abandoned the system can be reset to this default. 1067 In Netconf the operation can already be used to reset 1068 the startup datastore. There are ongoing efforts to introduce a new, 1069 more generic reset-datastore operation for the same purpose 1070 [I-D.wu-netconf-restconf-factory-restore] 1072 The operator currently has no way to know what the default 1073 configuration actually contains. YANG instance data can be used to 1074 document the factory default configuration. 1076 Authors' Addresses 1078 Balazs Lengyel 1079 Ericsson 1080 Magyar Tudosok korutja 11 1081 1117 Budapest 1082 Hungary 1084 Phone: +36-70-330-7909 1085 Email: balazs.lengyel@ericsson.com 1086 Benoit Claise 1087 Cisco Systems, Inc. 1088 De Kleetlaan 6a b1 1089 1831 Diegem 1090 Belgium 1092 Phone: +32 2 704 5622 1093 Email: bclaise@cisco.com