idnits 2.17.1 draft-ietf-netmod-yang-data-ext-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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC8340, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 15, 2019) is 1747 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) -- Looks like a reference, but probably isn't: '1' on line 680 Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Updates: 8340 (if approved) M. Bjorklund 5 Intended status: Standards Track Cisco 6 Expires: January 16, 2020 K. Watsen 7 Watsen Networks 8 July 15, 2019 10 YANG Data Structure Extensions 11 draft-ietf-netmod-yang-data-ext-04 13 Abstract 15 This document describes YANG mechanisms for defining abstract data 16 structures with YANG. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on January 16, 2020. 35 Copyright Notice 37 Copyright (c) 2019 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1.1. NMDA . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3. YANG Data Structures in YANG Tree Diagrams . . . . . . . . . 4 58 4. YANG Data Structure Extensions Module . . . . . . . . . . . . 5 59 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 60 5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 9 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 62 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 63 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 64 7.2. Informative References . . . . . . . . . . . . . . . . . 11 65 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 11 66 A.1. "structure" Example . . . . . . . . . . . . . . . . . . . 11 67 A.2. "augment-structure" Example . . . . . . . . . . . . . . . 13 68 A.3. XML Encoding Example . . . . . . . . . . . . . . . . . . 13 69 A.4. JSON Encoding Example . . . . . . . . . . . . . . . . . . 14 70 A.5. "structure" example that defines a non-top-level 71 structure . . . . . . . . . . . . . . . . . . . . . . . . 14 72 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 15 73 B.1. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 15 74 B.2. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 15 75 B.3. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 15 76 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 16 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 79 1. Introduction 81 There is a need for standard mechanisms to allow the definition of 82 abstract data that is not intended to be implemented as configuration 83 or operational state. The "yang-data" extension statement from RFC 84 8040 [RFC8040] was defined for this purpose but it is limited in its 85 functionality. 87 The intended use of the "yang-data" extension was to model all or 88 part of a protocol message, such as the "errors" definition in the 89 YANG module "ietf-restconf" [RFC8040], or the contents of a file. 90 However, protocols are often layered such that the header or payload 91 portions of the message can be extended by external documents. The 92 YANG statements that model a protocol need to support this 93 extensibility that is already found in that protocol. 95 The "yang-data" extension from [RFC8040] has been copied here, 96 renamed to "structure", and updated to be more flexible. There is no 97 assumption that a YANG data structure can only be used as a top-level 98 abstraction, instead of nested within some other data structure. 100 This document also defines a new YANG extension statement called 101 "augment-structure", which allows abstract data structures to be 102 augmented from external modules, similar to the existing YANG 103 "augment" statement. Note that "augment" cannot be used to augment a 104 YANG data structure since a YANG compiler or other tool is not 105 required to understand the "structure" extension. 107 1.1. Terminology 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 111 "OPTIONAL" in this document are to be interpreted as described in BCP 112 14 [RFC2119] [RFC8174] when, and only when, they appear in all 113 capitals, as shown here. 115 The following terms are used within this document: 117 o YANG data structure: A data structure defined with the "structure" 118 statement. 120 1.1.1. NMDA 122 The following terms are defined in the Network Management Datastore 123 Architecture (NMDA) [RFC8342]. and are not redefined here: 125 o configuration 127 o operational state 129 1.1.2. YANG 131 The following terms are defined in [RFC7950]: 133 o absolute-schema-nodeid 135 o container 137 o data definition statement 139 o data node 141 o leaf 143 o leaf-list 144 o list 146 2. Definitions 148 A YANG Data Structure is defined with the "structure" extension 149 statement, defined in the YANG module "ietf-yang-structure-ext". The 150 argument to the "structure" extension statement is the name of the 151 data structure. The data structures are considered to be in the same 152 identifier namespace as defined in section 6.2.1 of [RFC7950]. In 153 particular, bullet 7: 155 All leafs, leaf-lists, lists, containers, choices, rpcs, actions, 156 notifications, anydatas, and anyxmls defined (directly or through 157 a "uses" statement) within a parent node or at the top level of 158 the module or its submodules share the same identifier namespace. 160 This means that data structures defined with the "structure" 161 statement cannot have the same name as sibling nodes from regular 162 YANG data definition statements or other "structure" statements in 163 the same YANG module. 165 This does not mean a YANG data structure has to be used as a top- 166 level protocol message or other top-level data structure. 168 3. YANG Data Structures in YANG Tree Diagrams 170 A YANG Data Structure can be printed in a YANG Tree Diagram 171 [RFC8340]. This document updates RFC 8340 by defining two new 172 sections in the tree diagram for a module: 174 1. YANG data structures, offset by two spaces and identified by the 175 keyword "structure" followed by the name of the YANG data 176 structure and a colon (":") character. 178 2. YANG data structure augmentations, offset by 2 spaces and 179 identified by the keyword "augment-structure" followed by the 180 augment target structure name and a colon (":") character. 182 The new sections, including spaces conventions is: 184 structure : 185 +-- 186 +-- 187 | +-- 188 +-- 189 structure : 190 +-- 192 augment-structure : 193 +-- 194 +-- 195 | +-- 196 +-- 197 augment-structure : 198 +-- 200 4. YANG Data Structure Extensions Module 202 RFC Ed.: update the date below with the date of RFC publication and 203 remove this note. 205 file "ietf-yang-structure-ext@2019-03-07.yang" 207 module ietf-yang-structure-ext { 208 yang-version 1.1; 209 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext"; 210 prefix sx; 212 organization 213 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 214 contact 215 "WG Web: 216 WG List: 218 Author: Andy Bierman 219 221 Author: Martin Bjorklund 222 224 Author: Kent Watsen 225 "; 226 description 227 "This module contains conceptual YANG specifications for defining 228 abstract data structures. 230 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 231 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 232 'MAY', and 'OPTIONAL' in this document are to be interpreted as 233 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 234 they appear in all capitals, as shown here. 236 Copyright (c) 2019 IETF Trust and the persons identified 237 as authors of the code. All rights reserved. 239 Redistribution and use in source and binary forms, with or 240 without modification, is permitted pursuant to, and subject 241 to the license terms contained in, the Simplified BSD License 242 set forth in Section 4.c of the IETF Trust's Legal Provisions 243 Relating to IETF Documents 244 (http://trustee.ietf.org/license-info)."; 246 // RFC Ed.: update the date below with the date of RFC publication 247 // and remove this note. 249 revision 2019-03-07 { 250 description 251 "Initial revision."; 252 // RFC Ed.: replace XXXX with RFC number and remove this note 253 reference 254 "RFC XXXX: YANG Structure Extensions."; 255 } 257 extension structure { 258 argument name { 259 yin-element true; 260 } 261 description 262 "This extension is used to specify a YANG data structure that 263 represents conceptual data defined in YANG. It is intended to 264 describe hierarchical data independent of protocol context or 265 specific message encoding format. Data definition statements 266 within a 'structure' extension statement specify the generic 267 syntax for the specific YANG data structure, whose name is the 268 argument of the 'structure' extension statement. 270 Note that this extension does not define a media-type. A 271 specification using this extension MUST specify the message 272 encoding rules, including the content media type, if 273 applicable. 275 The mandatory 'name' parameter value identifies the YANG data 276 structure that is being defined. 278 This extension is only valid as a top-level statement, i.e., 279 given as a sub-statement to 'module' or 'submodule'. 281 The sub-statements of this extension MUST follow the ABNF 282 rules below, where the rules are defined in RFC 7950: 284 *must-stmt 285 [status-stmt] 286 [description-stmt] 287 [reference-stmt] 288 *(typedef-stmt / grouping-stmt) 289 *data-def-stmt 291 A YANG data structure defined with this extension statement is 292 encoded in the same way as an 'anydata' statement. This means 293 that the name of the structure is encoded as a 'container', 294 with the instantiated child statements encoded as child nodes 295 to this node. 297 The module name and namespace value for the YANG module using 298 the extension statement is assigned to each of the data 299 definition statements resulting from the YANG data structure. 301 The XPath document element is the extension statement itself, 302 such that the child nodes of the document element are 303 represented by the data-def-stmt sub-statements within this 304 extension. This conceptual document is the context for the 305 following YANG statements: 307 - must-stmt 308 - when-stmt 309 - path-stmt 310 - min-elements-stmt 311 - max-elements-stmt 312 - mandatory-stmt 313 - unique-stmt 314 - ordered-by 315 - instance-identifier data type 317 The following data-def-stmt sub-statements are constrained 318 when used within a 'structure' extension statement. 320 - The list-stmt is not required to have a key-stmt defined. 321 - The config-stmt is ignored if present. 322 "; 323 } 325 extension augment-structure { 326 argument path { 327 yin-element true; 328 } 329 description 330 "This extension is used to specify an augmentation to YANG data 331 structure defined with the 'structure' statement. It is 332 intended to describe hierarchical data independent of protocol 333 context or specific message encoding format. 335 This statement has almost the same structure as the 336 'augment-stmt'. Data definition statements within this 337 statement specify the semantics and generic syntax for the 338 additional data to be added to the specific YANG data 339 structure, identified by the 'path' argument. 341 The mandatory 'path' parameter value identifies the YANG 342 conceptual data node that is being augmented, represented as 343 an absolute-schema-nodeid string, where the first node in the 344 absolute-schema-nodeid string identifies the YANG data 345 structure to augment, and the rest of the nodes in the string 346 identifies the node within the YANG structure to augment. 348 This extension is only valid as a top-level statement, i.e., 349 given as a sub-statement to 'module' or 'submodule'. 351 The sub-statements of this extension MUST follow the ABNF 352 rules below, where the rules are defined in RFC 7950: 354 [status-stmt] 355 [description-stmt] 356 [reference-stmt] 357 1*(data-def-stmt / case-stmt) 359 The module name and namespace value for the YANG module using 360 the extension statement is assigned to instance document data 361 conforming to the data definition statements within this 362 extension. 364 The XPath document element is the augmented extension 365 statement itself, such that the child nodes of the document 366 element are represented by the data-def-stmt sub-statements 367 within the augmented 'structure' statement. 369 The context node of the 'augment-structure' statement is 370 derived in the same way as the 'augment' statement, as defined 371 in section 6.4.1 of [RFC7950]. This conceptual node is 372 considered the context node for the following YANG statements: 374 - must-stmt 375 - when-stmt 376 - path-stmt 377 - min-elements-stmt 378 - max-elements-stmt 379 - mandatory-stmt 380 - unique-stmt 381 - ordered-by 382 - instance-identifier data type 384 The following data-def-stmt sub-statements are constrained 385 when used within an 'augment-structure' extension statement. 387 - The list-stmt is not required to have a key-stmt defined. 388 - The config-stmt is ignored if present. 390 Example: 392 module foo { 393 import ietf-yang-structure-ext { prefix sx; } 395 sx:structure foo-data { 396 container foo-con { } 397 } 398 } 400 module bar { 401 import ietf-yang-structure-ext { prefix sx; } 402 import foo { prefix foo; } 404 sx:augment-structure /foo:foo-data/foo:foo-con { 405 leaf add-leaf1 { type int32; } 406 leaf add-leaf2 { type string; } 407 } 408 } 409 "; 410 } 411 } 413 415 5. IANA Considerations 417 5.1. YANG Module Registry 419 This document registers one URI as a namespace in the "IETF XML 420 Registry" [RFC3688]: 422 URI: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext 423 Registrant Contact: The IESG. 424 XML: N/A; the requested URI is an XML namespace. 426 This document registers one YANG module in the "YANG Module Names" 427 registry [RFC6020]: 429 name: ietf-yang-structure-ext 430 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext 431 prefix: sx 432 // RFC Ed.: replace XXXX with RFC number and remove this note 433 reference: RFC XXXX 435 6. Security Considerations 437 This document defines YANG extensions that are used to define 438 conceptual YANG data structures. It does not introduce any new 439 vulnerabilities beyond those specified in YANG 1.1 [RFC7950]. 441 7. References 443 7.1. Normative References 445 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 446 Requirement Levels", BCP 14, RFC 2119, 447 DOI 10.17487/RFC2119, March 1997, 448 . 450 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 451 RFC 7950, DOI 10.17487/RFC7950, August 2016, 452 . 454 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 455 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 456 . 458 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 459 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 460 May 2017, . 462 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 463 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 464 . 466 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 467 and R. Wilton, "Network Management Datastore Architecture 468 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 469 . 471 7.2. Informative References 473 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 474 DOI 10.17487/RFC3688, January 2004, 475 . 477 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 478 the Network Configuration Protocol (NETCONF)", RFC 6020, 479 DOI 10.17487/RFC6020, October 2010, 480 . 482 7.3. URIs 484 [1] https://github.com/netmod-wg/yang-data-ext/issues 486 Appendix A. Examples 488 A.1. "structure" Example 490 This example shows a simple address book that could be stored as an 491 artifact. 493 module example-module { 494 yang-version 1.1; 495 namespace "urn:example:example-module"; 496 prefix exm; 498 import ietf-yang-structure-ext { 499 prefix sx; 500 } 502 sx:structure address-book { 503 list address { 504 key "last first"; 505 leaf last { 506 type string; 507 description "Last name"; 508 } 509 leaf first { 510 type string; 511 description "First name"; 512 } 513 leaf street { 514 type string; 515 description "Street name"; 516 } 517 leaf city { 518 type string; 519 description "City name"; 520 } 521 leaf state { 522 type string; 523 description "State name"; 524 } 525 } 526 } 527 } 529 Below is the tree diagram of this module. 531 module: example-module 533 structure address-book: 534 +-- address* [last first] 535 +-- last string 536 +-- first string 537 +-- street? string 538 +-- city? string 539 +-- state? string 541 A.2. "augment-structure" Example 543 This example adds "county" and "zipcode" leafs to the address book: 545 module example-module-aug { 546 yang-version 1.1; 547 namespace "urn:example:example-module-aug"; 548 prefix exma; 550 import ietf-yang-structure-ext { 551 prefix sx; 552 } 553 import example-module { 554 prefix exm; 555 } 557 sx:augment-structure "/exm:address-book/exm:address" { 558 leaf county { 559 type string; 560 description "County name"; 561 } 562 leaf zipcode { 563 type string; 564 description "Postal zipcode"; 565 } 566 } 567 } 569 Below is the tree diagram of this module. 571 module: example-module-aug 573 augment-structure /exm:address-book/exm:address: 574 +-- county? string 575 +-- zipcode? string 577 A.3. XML Encoding Example 579 This example shows how an address book can be encoded in XML: 581 582
583 Flintstone 584 Fred 585 301 Cobblestone Way 586 Bedrock 587 70777 588
589 591 A.4. JSON Encoding Example 593 This example shows how an address book can be encoded in JSON: 595 "example-module:address-book": { 596 "address": [ 597 { 598 "city": "Bedrock", 599 "example-module-aug:zipcode": "70777", 600 "first": "Fred", 601 "last": "Flintstone", 602 "street": "301 Cobblestone Way" 603 } 604 ] 605 } 607 A.5. "structure" example that defines a non-top-level structure 609 The following example defines a data structure with error 610 information, that can be included in an element in an 611 . 613 module example-error-info { 614 yang-version 1.1; 615 namespace "urn:example:example-error-info"; 616 prefix exei; 618 import ietf-yang-structure-ext { 619 prefix sx; 620 } 622 sx:structure my-example-error-info { 623 leaf error-code { 624 type uint32; 625 } 626 } 628 } 629 The example below shows how this structure can be used in an 630 . 632 634 635 protocol 636 operation-failed 637 error 638 639 641 42 642 643 644 645 647 Appendix B. Change Log 649 RFC Ed.: remove this section before publication. 651 B.1. v02 to v03 653 o added YANG tree diagram syntax 655 o added more examples 657 B.2. v01 to v02 659 o terminology fixes (use the term "structure" instead of "template") 661 o renamed the statement to "structure" from "yang-data" 663 o removed limitations on if-feature and identities in YANG 664 structures 666 B.3. v00 to v01 668 o moved open issues to github 670 o added examples section 672 o filled in IANA considerations 674 Appendix C. Open Issues 676 RFC Ed.: remove this section before publication. 678 The YANG Data Structure Extensions issues are tracked on github.com: 680 https://github.com/netmod-wg/yang-data-ext/issues [1] 682 Authors' Addresses 684 Andy Bierman 685 YumaWorks 687 Email: andy@yumaworks.com 689 Martin Bjorklund 690 Cisco 692 Email: mbj@tail-f.com 694 Kent Watsen 695 Watsen Networks 697 Email: kent+ietf@watsen.net