idnits 2.17.1 draft-ietf-netmod-yang-data-ext-05.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 (December 10, 2019) is 1600 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 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: June 12, 2020 K. Watsen 7 Watsen Networks 8 December 10, 2019 10 YANG Data Structure Extensions 11 draft-ietf-netmod-yang-data-ext-05 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 June 12, 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 . . . . . . . . . 5 58 4. YANG Data Structure Extensions Module . . . . . . . . . . . . 5 59 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 60 5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 10 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 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 74 1. Introduction 76 There is a need for standard mechanisms to allow the definition of 77 abstract data that is not intended to be implemented as configuration 78 or operational state. The "yang-data" extension statement from RFC 79 8040 [RFC8040] was defined for this purpose but it is limited in its 80 functionality. 82 The intended use of the "yang-data" extension was to model all or 83 part of a protocol message, such as the "errors" definition in the 84 YANG module "ietf-restconf" [RFC8040], or the contents of a file. 85 However, protocols are often layered such that the header or payload 86 portions of the message can be extended by external documents. The 87 YANG statements that model a protocol need to support this 88 extensibility that is already found in that protocol. 90 This document defines a new YANG extension statement called 91 "structure", which is similar to but more flexible than the 92 "yang-data" extension from [RFC8040]. There is no assumption that a 93 YANG data structure can only be used as a top-level abstraction, and 94 it may also be nested within some other data structure. 96 This document also defines a new YANG extension statement called 97 "augment-structure", which allows abstract data structures to be 98 augmented from external modules, similarly to the existing YANG 99 "augment" statement. Note that "augment" cannot be used to augment a 100 YANG data structure since a YANG compiler or other tool is not 101 required to understand the "structure" extension. 103 1.1. Terminology 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 107 "OPTIONAL" in this document are to be interpreted as described in BCP 108 14 [RFC2119] [RFC8174] when, and only when, they appear in all 109 capitals, as shown here. 111 The following terms are used within this document: 113 o YANG data structure: A data structure defined with the "structure" 114 statement. 116 1.1.1. NMDA 118 The following terms are defined in the Network Management Datastore 119 Architecture (NMDA) [RFC8342], and are not redefined here: 121 o configuration 123 o operational state 125 1.1.2. YANG 127 The following terms are defined in [RFC7950]: 129 o absolute-schema-nodeid 131 o container 133 o data definition statement 135 o data node 137 o leaf 139 o leaf-list 141 o list 143 2. Definitions 145 A YANG data structure is defined with the "structure" extension 146 statement, defined in the YANG module "ietf-yang-structure-ext". The 147 argument to the "structure" extension statement is the name of the 148 data structure. The data structures are considered to be in the same 149 identifier namespace as defined in section 6.2.1 of [RFC7950]. In 150 particular, bullet 7: 152 All leafs, leaf-lists, lists, containers, choices, rpcs, actions, 153 notifications, anydatas, and anyxmls defined (directly or through 154 a "uses" statement) within a parent node or at the top level of 155 the module or its submodules share the same identifier namespace. 157 This means that data structures defined with the "structure" 158 statement cannot have the same name as sibling nodes from regular 159 YANG data definition statements or other "structure" statements in 160 the same YANG module. 162 This does not mean a YANG data structure, once defined, has to be 163 used as a top-level protocol message or other top-level data 164 structure. 166 A YANG data structure is encoded in the same way as an "anydata" 167 node. This means that the name of the structure is encoded as a 168 "container", with the instantiated children encoded as child nodes to 169 this node. For example, this structure: 171 module example-errors { 172 ... 174 sx:structure my-error { 175 leaf error-number { 176 type int; 177 } 178 } 179 } 181 can be encoded in JSON as: 183 "example-errors:my-error": { 184 "error-number": 131 185 } 187 3. YANG Data Structures in YANG Tree Diagrams 189 A YANG data structure can be printed in a YANG Tree Diagram 190 [RFC8340]. This document updates RFC 8340 by defining two new 191 sections in the tree diagram for a module: 193 1. YANG data structures, offset by two spaces and identified by the 194 keyword "structure" followed by the name of the YANG data 195 structure and a colon (":") character. 197 2. YANG data structure augmentations, offset by 2 spaces and 198 identified by the keyword "augment-structure" followed by the 199 augment target structure name and a colon (":") character. 201 The new sections, including spaces conventions is: 203 structure : 204 +-- 205 +-- 206 | +-- 207 +-- 208 structure : 209 +-- 211 augment-structure : 212 +-- 213 +-- 214 | +-- 215 +-- 216 augment-structure : 217 +-- 219 Nodes in YANG data structures are printed according to the rules 220 defined in section 2.6 in [RFC8340]. 222 4. YANG Data Structure Extensions Module 224 RFC Ed.: update the date below with the date of RFC publication and 225 remove this note. 227 file "ietf-yang-structure-ext@2019-03-07.yang" 229 module ietf-yang-structure-ext { 230 yang-version 1.1; 231 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext"; 232 prefix sx; 234 organization 235 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 236 contact 237 "WG Web: 238 WG List: 240 Author: Andy Bierman 241 243 Author: Martin Bjorklund 244 246 Author: Kent Watsen 247 "; 248 description 249 "This module contains conceptual YANG specifications for defining 250 abstract data structures. 252 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 253 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 254 'MAY', and 'OPTIONAL' in this document are to be interpreted as 255 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 256 they appear in all capitals, as shown here. 258 Copyright (c) 2019 IETF Trust and the persons identified as 259 authors of the code. All rights reserved. 261 Redistribution and use in source and binary forms, with or 262 without modification, is permitted pursuant to, and subject to 263 the license terms contained in, the Simplified BSD License set 264 forth in Section 4.c of the IETF Trust's Legal Provisions 265 Relating to IETF Documents 266 (http://trustee.ietf.org/license-info). 268 This version of this YANG module is part of RFC XXXX 269 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 270 for full legal notices."; 272 // RFC Ed.: update the date below with the date of RFC publication 273 // and remove this note. 275 revision 2019-03-07 { 276 description 277 "Initial revision."; 278 // RFC Ed.: replace XXXX with RFC number and remove this note 279 reference 280 "RFC XXXX: YANG Structure Extensions."; 281 } 282 extension structure { 283 argument name { 284 yin-element true; 285 } 286 description 287 "This extension is used to specify a YANG data structure that 288 represents conceptual data defined in YANG. It is intended to 289 describe hierarchical data independent of protocol context or 290 specific message encoding format. Data definition statements 291 within a 'structure' extension statement specify the generic 292 syntax for the specific YANG data structure, whose name is the 293 argument of the 'structure' extension statement. 295 Note that this extension does not define a media-type. A 296 specification using this extension MUST specify the message 297 encoding rules, including the content media type, if 298 applicable. 300 The mandatory 'name' parameter value identifies the YANG data 301 structure that is being defined. 303 This extension is only valid as a top-level statement, i.e., 304 given as a sub-statement to 'module' or 'submodule'. 306 The sub-statements of this extension MUST follow the ABNF 307 rules below, where the rules are defined in RFC 7950: 309 *must-stmt 310 [status-stmt] 311 [description-stmt] 312 [reference-stmt] 313 *(typedef-stmt / grouping-stmt) 314 *data-def-stmt 316 A YANG data structure defined with this extension statement is 317 encoded in the same way as an 'anydata' node. This means 318 that the name of the structure is encoded as a 'container', 319 with the instantiated child statements encoded as child nodes 320 to this node. 322 The module name and namespace value for the YANG module using 323 the extension statement is assigned to each of the data 324 definition statements resulting from the YANG data structure. 326 The XPath document element is the extension statement itself, 327 such that the child nodes of the document element are 328 represented by the data-def-stmt sub-statements within this 329 extension. This conceptual document is the context for the 330 following YANG statements: 332 - must-stmt 333 - when-stmt 334 - path-stmt 335 - min-elements-stmt 336 - max-elements-stmt 337 - mandatory-stmt 338 - unique-stmt 339 - ordered-by 340 - instance-identifier data type 342 The following data-def-stmt sub-statements are constrained 343 when used within a 'structure' extension statement. 345 - The list-stmt is not required to have a key-stmt defined. 346 - The config-stmt is ignored if present. 347 "; 348 } 350 extension augment-structure { 351 argument path { 352 yin-element true; 353 } 354 description 355 "This extension is used to specify an augmentation to YANG data 356 structure defined with the 'structure' statement. It is 357 intended to describe hierarchical data independent of protocol 358 context or specific message encoding format. 360 This statement has almost the same structure as the 361 'augment-stmt'. Data definition statements within this 362 statement specify the semantics and generic syntax for the 363 additional data to be added to the specific YANG data 364 structure, identified by the 'path' argument. 366 The mandatory 'path' parameter value identifies the YANG 367 conceptual data node that is being augmented, represented as 368 an absolute-schema-nodeid string, where the first node in the 369 absolute-schema-nodeid string identifies the YANG data 370 structure to augment, and the rest of the nodes in the string 371 identifies the node within the YANG structure to augment. 373 This extension is only valid as a top-level statement, i.e., 374 given as a sub-statement to 'module' or 'submodule'. 376 The sub-statements of this extension MUST follow the ABNF 377 rules below, where the rules are defined in RFC 7950: 379 [status-stmt] 380 [description-stmt] 381 [reference-stmt] 382 1*(data-def-stmt / case-stmt) 384 The module name and namespace value for the YANG module using 385 the extension statement is assigned to instance document data 386 conforming to the data definition statements within this 387 extension. 389 The XPath document element is the augmented extension 390 statement itself, such that the child nodes of the document 391 element are represented by the data-def-stmt sub-statements 392 within the augmented 'structure' statement. 394 The context node of the 'augment-structure' statement is 395 derived in the same way as the 'augment' statement, as defined 396 in section 6.4.1 of [RFC7950]. This conceptual node is 397 considered the context node for the following YANG statements: 399 - must-stmt 400 - when-stmt 401 - path-stmt 402 - min-elements-stmt 403 - max-elements-stmt 404 - mandatory-stmt 405 - unique-stmt 406 - ordered-by 407 - instance-identifier data type 409 The following data-def-stmt sub-statements are constrained 410 when used within an 'augment-structure' extension statement. 412 - The list-stmt is not required to have a key-stmt defined. 413 - The config-stmt is ignored if present. 415 Example: 417 module foo { 418 import ietf-yang-structure-ext { prefix sx; } 420 sx:structure foo-data { 421 container foo-con { } 422 } 423 } 425 module bar { 426 import ietf-yang-structure-ext { prefix sx; } 427 import foo { prefix foo; } 429 sx:augment-structure /foo:foo-data/foo:foo-con { 430 leaf add-leaf1 { type int32; } 431 leaf add-leaf2 { type string; } 432 } 433 } 434 "; 435 } 436 } 438 440 5. IANA Considerations 442 5.1. YANG Module Registry 444 This document registers one URI as a namespace in the "IETF XML 445 Registry" [RFC3688]: 447 URI: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext 448 Registrant Contact: The IESG. 449 XML: N/A; the requested URI is an XML namespace. 451 This document registers one YANG module in the "YANG Module Names" 452 registry [RFC6020]: 454 name: ietf-yang-structure-ext 455 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext 456 prefix: sx 457 // RFC Ed.: replace XXXX with RFC number and remove this note 458 reference: RFC XXXX 460 6. Security Considerations 462 This document defines YANG extensions that are used to define 463 conceptual YANG data structures. It does not introduce any new 464 vulnerabilities beyond those specified in YANG 1.1 [RFC7950]. 466 7. References 468 7.1. Normative References 470 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 471 Requirement Levels", BCP 14, RFC 2119, 472 DOI 10.17487/RFC2119, March 1997, 473 . 475 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 476 RFC 7950, DOI 10.17487/RFC7950, August 2016, 477 . 479 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 480 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 481 . 483 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 484 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 485 May 2017, . 487 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 488 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 489 . 491 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 492 and R. Wilton, "Network Management Datastore Architecture 493 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 494 . 496 7.2. Informative References 498 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 499 DOI 10.17487/RFC3688, January 2004, 500 . 502 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 503 the Network Configuration Protocol (NETCONF)", RFC 6020, 504 DOI 10.17487/RFC6020, October 2010, 505 . 507 Appendix A. Examples 509 A.1. "structure" Example 511 This example shows a simple address book that could be stored as an 512 artifact. 514 module example-module { 515 yang-version 1.1; 516 namespace "urn:example:example-module"; 517 prefix exm; 519 import ietf-yang-structure-ext { 520 prefix sx; 521 } 523 sx:structure address-book { 524 list address { 525 key "last first"; 526 leaf last { 527 type string; 528 description "Last name"; 529 } 530 leaf first { 531 type string; 532 description "First name"; 533 } 534 leaf street { 535 type string; 536 description "Street name"; 537 } 538 leaf city { 539 type string; 540 description "City name"; 541 } 542 leaf state { 543 type string; 544 description "State name"; 545 } 546 } 547 } 548 } 550 Below is the tree diagram of this module. 552 module: example-module 554 structure address-book: 555 +-- address* [last first] 556 +-- last string 557 +-- first string 558 +-- street? string 559 +-- city? string 560 +-- state? string 562 A.2. "augment-structure" Example 564 This example adds "county" and "zipcode" leafs to the address book: 566 module example-module-aug { 567 yang-version 1.1; 568 namespace "urn:example:example-module-aug"; 569 prefix exma; 571 import ietf-yang-structure-ext { 572 prefix sx; 573 } 574 import example-module { 575 prefix exm; 576 } 578 sx:augment-structure "/exm:address-book/exm:address" { 579 leaf county { 580 type string; 581 description "County name"; 582 } 583 leaf zipcode { 584 type string; 585 description "Postal zipcode"; 586 } 587 } 588 } 590 Below is the tree diagram of this module. 592 module: example-module-aug 594 augment-structure /exm:address-book/exm:address: 595 +-- county? string 596 +-- zipcode? string 598 A.3. XML Encoding Example 600 This example shows how an address book can be encoded in XML: 602 603
604 Flintstone 605 Fred 606 301 Cobblestone Way 607 Bedrock 608 70777 609
610
611 Root 612 Charlie 613 4711 Cobblestone Way 614 Bedrock 615 70777 616
617 619 A.4. JSON Encoding Example 621 This example shows how an address book can be encoded in JSON: 623 "example-module:address-book": { 624 "address": [ 625 { 626 "city": "Bedrock", 627 "example-module-aug:zipcode": "70777", 628 "first": "Fred", 629 "last": "Flintstone", 630 "street": "301 Cobblestone Way" 631 }, 632 { 633 "city": "Bedrock", 634 "example-module-aug:zipcode": "70777", 635 "first": "Charlie", 636 "last": "Root", 637 "street": "4711 Cobblestone Way" 638 } 639 ] 640 } 642 A.5. "structure" example that defines a non-top-level structure 644 The following example defines a data structure with error 645 information, that can be included in an element in an 646 . 648 module example-error-info { 649 yang-version 1.1; 650 namespace "urn:example:example-error-info"; 651 prefix exei; 653 import ietf-yang-structure-ext { 654 prefix sx; 655 } 657 sx:structure my-example-error-info { 658 leaf error-code { 659 type uint32; 660 } 661 } 663 } 665 The example below shows how this structure can be used in an 666 . 668 670 671 protocol 672 operation-failed 673 error 674 675 677 42 678 679 680 681 683 Authors' Addresses 685 Andy Bierman 686 YumaWorks 688 Email: andy@yumaworks.com 690 Martin Bjorklund 691 Cisco 693 Email: mbj@tail-f.com 694 Kent Watsen 695 Watsen Networks 697 Email: kent+ietf@watsen.net