idnits 2.17.1 draft-ietf-netmod-yang-data-ext-02.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 date (March 8, 2019) is 1876 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 (==), 1 comment (--). 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 Intended status: Standards Track M. Bjorklund 5 Expires: September 9, 2019 Cisco 6 K. Watsen 7 Watsen Networks 8 March 8, 2019 10 YANG Data Structure Extensions 11 draft-ietf-netmod-yang-data-ext-02 13 Abstract 15 This document describes YANG mechanisms for defining abstract data 16 structures with YANG. It is intended to replace and extend the 17 "yang-data" extension statement defined in RFC 8040. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on September 9, 2019. 36 Copyright Notice 38 Copyright (c) 2019 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1.1. NMDA . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. YANG Data Structure Extensions Module . . . . . . . . . . . . 4 59 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 60 4.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 9 61 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 62 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 63 6.1. Normative References . . . . . . . . . . . . . . . . . . 9 64 6.2. Informative References . . . . . . . . . . . . . . . . . 10 65 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 10 66 A.1. "structure" Example . . . . . . . . . . . . . . . . . . . 10 67 A.2. "augment-structure" Example . . . . . . . . . . . . . . . 11 68 A.3. XML Encoding Example . . . . . . . . . . . . . . . . . . 12 69 A.4. JSON Encoding Example . . . . . . . . . . . . . . . . . . 12 70 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 13 71 B.1. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 13 72 B.2. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 13 73 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 13 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 76 1. Introduction 78 There is a need for standard mechanisms to allow the definition of 79 abstract data that is not intended to be implemented as configuration 80 or operational state. The "yang-data" extension statement from RFC 81 8040 [RFC8040] was defined for this purpose but it is limited in its 82 functionality. 84 The intended use of the "yang-data" extension was to model all or 85 part of a protocol message, such as the "errors" definition in the 86 YANG module "ietf-restconf" [RFC8040], or the contents of a file. 87 However, protocols are often layered such that the header or payload 88 portions of the message can be extended by external documents. The 89 YANG statements that model a protocol need to support this 90 extensibility that is already found in that protocol. 92 The "yang-data" extension from [RFC8040] has been copied here, 93 renamed to "structure", and updated to be more flexible. There is no 94 assumption that a YANG data structure can only be used as a top-level 95 abstraction, instead of nested within some other data structure. 97 This document also defines a new YANG extension statement called 98 "augment-structure", which allows abstract data structures to be 99 augmented from external modules, similar to the existing YANG 100 "augment" statement. Note that "augment" cannot be used to augment a 101 YANG data structure since a YANG compiler or other tool is not 102 required to understand the "structure" extension. 104 1.1. Terminology 106 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 107 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 108 "OPTIONAL" in this document are to be interpreted as described in BCP 109 14 [RFC2119] [RFC8174] when, and only when, they appear in all 110 capitals, as shown here. 112 The following terms are used within this document: 114 o YANG data structure: A data structure defined with the "structure" 115 statement. 117 1.1.1. NMDA 119 The following terms are defined in the Network Management Datastore 120 Architecture (NMDA) [RFC8342]. and are not redefined here: 122 o configuration 124 o operational state 126 1.1.2. YANG 128 The following terms are defined in [RFC7950]: 130 o absolute-schema-nodeid 132 o container 134 o data definition statement 136 o data node 138 o leaf 140 o leaf-list 142 o list 144 2. Definitions 146 A YANG Data Structure is defined with the "structure" extension 147 statement, defined in the YANG module "ietf-yang-structure-ext". The 148 argument to the "structure" extension statement is the name of the 149 data structure. The data structures are considered to be in the same 150 identifier namespace as defined in section 6.2.1 of [RFC7950]. In 151 particular, bullet 7: 153 All leafs, leaf-lists, lists, containers, choices, rpcs, actions, 154 notifications, anydatas, and anyxmls defined (directly or through 155 a "uses" statement) within a parent node or at the top level of 156 the module or its submodules share the same identifier namespace. 158 This means that data structures defined with the "structure" 159 statement cannot have the same name as sibling nodes from regular 160 YANG data definition statements or other "structure" statements in 161 the same YANG module. 163 This does not mean a YANG data structure has to be used as a top- 164 level protocol message or other top-level data structure. 166 3. YANG Data Structure Extensions Module 168 RFC Ed.: update the date below with the date of RFC publication and 169 remove this note. 171 file "ietf-yang-structure-ext@2019-03-07.yang" 173 module ietf-yang-structure-ext { 174 yang-version 1.1; 175 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext"; 176 prefix sx; 178 organization 179 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 180 contact 181 "WG Web: 182 WG List: 184 Author: Andy Bierman 185 187 Author: Martin Bjorklund 188 190 Author: Kent Watsen 191 "; 193 description 194 "This module contains conceptual YANG specifications for defining 195 abstract data structures. 197 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 198 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 199 'MAY', and 'OPTIONAL' in this document are to be interpreted as 200 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 201 they appear in all capitals, as shown here. 203 Copyright (c) 2019 IETF Trust and the persons identified 204 as authors of the code. All rights reserved. 206 Redistribution and use in source and binary forms, with or 207 without modification, is permitted pursuant to, and subject 208 to the license terms contained in, the Simplified BSD License 209 set forth in Section 4.c of the IETF Trust's Legal Provisions 210 Relating to IETF Documents 211 (http://trustee.ietf.org/license-info)."; 213 // RFC Ed.: update the date below with the date of RFC publication 214 // and remove this note. 216 revision 2019-03-07 { 217 description 218 "Initial revision."; 219 // RFC Ed.: replace XXXX with RFC number and remove this note 220 reference 221 "RFC XXXX: YANG Structure Extensions."; 222 } 224 extension structure { 225 argument name { 226 yin-element true; 227 } 228 description 229 "This extension is used to specify a YANG data structure that 230 represents conceptual data defined in YANG. It is intended to 231 describe hierarchical data independent of protocol context or 232 specific message encoding format. Data definition statements 233 within a 'structure' extension statement specify the generic 234 syntax for the specific YANG data structure, whose name is the 235 argument of the 'structure' extension statement. 237 Note that this extension does not define a media-type. A 238 specification using this extension MUST specify the message 239 encoding rules, including the content media type, if 240 applicable. 242 The mandatory 'name' parameter value identifies the YANG data 243 structure that is being defined. 245 This extension is only valid as a top-level statement, i.e., 246 given as a sub-statement to 'module' or 'submodule'. 248 The sub-statements of this extension MUST follow the ABNF 249 rules below, where the rules are defined in RFC 7950: 251 *must-stmt 252 [status-stmt] 253 [description-stmt] 254 [reference-stmt] 255 *(typedef-stmt / grouping-stmt) 256 *data-def-stmt 258 A YANG data structure defined with this extension statement is 259 encoded in the same way as an 'anydata' statement. This means 260 that the name of the structure is encoded as a 'container', 261 with the instantiated child statements encoded as child nodes 262 to this node. 264 The module name and namespace value for the YANG module using 265 the extension statement is assigned to each of the data 266 definition statements resulting from the YANG data structure. 268 The XPath document element is the extension statement itself, 269 such that the child nodes of the document element are 270 represented by the data-def-stmt sub-statements within this 271 extension. This conceptual document is the context for the 272 following YANG statements: 274 - must-stmt 275 - when-stmt 276 - path-stmt 277 - min-elements-stmt 278 - max-elements-stmt 279 - mandatory-stmt 280 - unique-stmt 281 - ordered-by 282 - instance-identifier data type 284 The following data-def-stmt sub-statements are constrained 285 when used within a 'structure' extension statement. 287 - The list-stmt is not required to have a key-stmt defined. 288 - The config-stmt is ignored if present. 289 "; 291 } 293 extension augment-structure { 294 argument path { 295 yin-element true; 296 } 297 description 298 "This extension is used to specify an augmentation to YANG data 299 structure defined with the 'structure' statement. It is 300 intended to describe hierarchical data independent of protocol 301 context or specific message encoding format. 303 This statement has almost the same structure as the 304 'augment-stmt'. Data definition statements within this 305 statement specify the semantics and generic syntax for the 306 additional data to be added to the specific YANG data 307 structure, identified by the 'path' argument. 309 The mandatory 'path' parameter value identifies the YANG 310 conceptual data node that is being augmented, represented as 311 an absolute-schema-nodeid string, where the first node in the 312 absolute-schema-nodeid string identifies the YANG data 313 structure to augment, and the rest of the nodes in the string 314 identifies the node within the YANG structure to augment. 316 This extension is only valid as a top-level statement, i.e., 317 given as a sub-statement to 'module' or 'submodule'. 319 The sub-statements of this extension MUST follow the ABNF 320 rules below, where the rules are defined in RFC 7950: 322 [status-stmt] 323 [description-stmt] 324 [reference-stmt] 325 1*(data-def-stmt / case-stmt) 327 The module name and namespace value for the YANG module using 328 the extension statement is assigned to instance document data 329 conforming to the data definition statements within this 330 extension. 332 The XPath document element is the augmented extension 333 statement itself, such that the child nodes of the document 334 element are represented by the data-def-stmt sub-statements 335 within the augmented 'structure' statement. 337 The context node of the 'augment-structure' statement is 338 derived in the same way as the 'augment' statement, as defined 339 in section 6.4.1 of [RFC7950]. This conceptual node is 340 considered the context node for the following YANG statements: 342 - must-stmt 343 - when-stmt 344 - path-stmt 345 - min-elements-stmt 346 - max-elements-stmt 347 - mandatory-stmt 348 - unique-stmt 349 - ordered-by 350 - instance-identifier data type 352 The following data-def-stmt sub-statements are constrained 353 when used within an 'augment-structure' extension statement. 355 - The list-stmt is not required to have a key-stmt defined. 356 - The config-stmt is ignored if present. 358 Example: 360 module foo { 361 import ietf-yang-structure-ext { prefix sx; } 363 sx:structure foo-data { 364 container foo-con { } 365 } 366 } 368 module bar { 369 import ietf-yang-structure-ext { prefix sx; } 370 import foo { prefix foo; } 372 sx:augment-structure /foo:foo-data/foo:foo-con { 373 leaf add-leaf1 { type int32; } 374 leaf add-leaf2 { type string; } 375 } 376 } 377 "; 378 } 379 } 381 383 4. IANA Considerations 385 4.1. YANG Module Registry 387 This document registers one URI as a namespace in the "IETF XML 388 Registry" [RFC3688]: 390 URI: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext 391 Registrant Contact: The IESG. 392 XML: N/A; the requested URI is an XML namespace. 394 This document registers one YANG module in the "YANG Module Names" 395 registry [RFC6020]: 397 name: ietf-yang-structure-ext 398 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext 399 prefix: sx 400 // RFC Ed.: replace XXXX with RFC number and remove this note 401 reference: RFC XXXX 403 5. Security Considerations 405 This document defines YANG extensions that are used to define 406 conceptual YANG data structures. It does not introduce any new 407 vulnerabilities beyond those specified in YANG 1.1 [RFC7950]. 409 6. References 411 6.1. Normative References 413 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 414 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 415 RFC2119, March 1997, . 418 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 419 RFC 7950, DOI 10.17487/RFC7950, August 2016, 420 . 422 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 423 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 424 . 426 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 427 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 428 May 2017, . 430 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 431 and R. Wilton, "Network Management Datastore Architecture 432 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 433 . 435 6.2. Informative References 437 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 438 DOI 10.17487/RFC3688, January 2004, . 441 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 442 the Network Configuration Protocol (NETCONF)", RFC 6020, 443 DOI 10.17487/RFC6020, October 2010, . 446 Appendix A. Examples 448 A.1. "structure" Example 450 This example shows a simple address book that could be stored as an 451 artifact. 453 module example-module { 454 yang-version 1.1; 455 namespace "urn:example:example-module"; 456 prefix exm; 458 import ietf-yang-structure-ext { 459 prefix sx; 460 } 462 sx:structure address-book { 463 list address { 464 key "last first"; 465 leaf last { 466 type string; 467 description "Last name"; 468 } 469 leaf first { 470 type string; 471 description "First name"; 472 } 473 leaf street { 474 type string; 475 description "Street name"; 476 } 477 leaf city { 478 type string; 479 description "City name"; 480 } 481 leaf state { 482 type string; 483 description "State name"; 484 } 485 } 486 } 487 } 489 A.2. "augment-structure" Example 491 This example adds "county" and "zipcode" leafs to the address book: 493 module example-module-aug { 494 yang-version 1.1; 495 namespace "urn:example:example-module-aug"; 496 prefix exma; 498 import ietf-yang-structure-ext { 499 prefix sx; 500 } 501 import example-module { 502 prefix exm; 503 } 505 sx:augment-structure "/exm:address-book/exm:address" { 506 leaf county { 507 type string; 508 description "County name"; 509 } 510 leaf zipcode { 511 type string; 512 description "Postal zipcode"; 513 } 514 } 515 } 517 A.3. XML Encoding Example 519 This example shows how an address book can be encoded in XML: 521 522
523 Flintstone 524 Fred 525 301 Cobblestone Way 526 Bedrock 527 70777 528
529 531 A.4. JSON Encoding Example 533 This example shows how an address book can be encoded in JSON: 535 "example-module:address-book": { 536 "address": [ 537 { 538 "city": "Bedrock", 539 "example-module-aug:zipcode": "70777", 540 "first": "Fred", 541 "last": "Flintstone", 542 "street": "301 Cobblestone Way" 543 } 544 ] 545 } 547 Appendix B. Change Log 549 RFC Ed.: remove this section before publication. 551 B.1. v01 to v02 553 o terminology fixes (use the term "structure" instead of "template") 555 o renamed the statement to "structure" from "yang-data" 557 o removed limitations on if-feature and identities in YANG 558 structures 560 B.2. v00 to v01 562 o moved open issues to github 564 o added examples section 566 o filled in IANA considerations 568 Appendix C. Open Issues 570 RFC Ed.: remove this section before publication. 572 The YANG Data Structure Extensions issues are tracked on github.com: 574 https://github.com/netmod-wg/yang-data-ext/issues 576 Authors' Addresses 578 Andy Bierman 579 YumaWorks 581 Email: andy@yumaworks.com 582 Martin Bjorklund 583 Cisco 585 Email: mbj@tail-f.com 587 Kent Watsen 588 Watsen Networks 590 Email: kent+ietf@watsen.net