idnits 2.17.1 draft-ietf-netmod-yang-data-ext-00.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 (February 19, 2018) is 2257 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) == Outdated reference: A later version (-10) exists of draft-ietf-netmod-revised-datastores-05 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 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: August 23, 2018 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 February 19, 2018 10 YANG Data Extensions 11 draft-ietf-netmod-yang-data-ext-00 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 August 23, 2018. 36 Copyright Notice 38 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2.1. Restrictions on Conceptual YANG Data . . . . . . . . . . 4 59 2.2. YANG Data Extensions Module . . . . . . . . . . . . . . . 4 60 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 61 3.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 9 62 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 63 5. Normative References . . . . . . . . . . . . . . . . . . . . 9 64 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 9 65 A.1. uses-yang-data . . . . . . . . . . . . . . . . . . . . . 9 66 A.2. error-info . . . . . . . . . . . . . . . . . . . . . . . 9 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 69 1. Introduction 71 There is a need for standard mechanisms to allow the definition of 72 abstract data that is not intended to be implemented as configuration 73 or operational state. The "yang-data" extension statement from RFC 74 8040 [RFC8040] is defined for this purpose, however it is limited in 75 its functionality. 77 The intended use of the "yang-data" extension is to model all or part 78 of a protocol message, such as the "errors" definition in ietf- 79 restconf.yang [RFC8040], or the contents of a file. However, 80 protocols are often layered such that the header or payload portions 81 of the message can be extended by external documents. The YANG 82 statements that model a protocol need to support this extensibility 83 that is already found in that protocol. 85 This document defines a new YANG extension statement called 86 "augment-yang-data", which allows abstract data structures to be 87 augmented from external modules, similar to the existing YANG 88 "augment" statement. Note that "augment" cannot be used to augment a 89 yang data structure since a YANG compiler or other tool is not 90 required to understand the "yang-data" extension. 92 The "yang-data" extension from [RFC8040] has been copied here and 93 updated to be more flexible. There is no longer a requirement for 94 the "yang-data" statement to result in exactly one container object. 95 There is no longer an assumption that a yang data structure can only 96 be used as a top-level abstraction, instead of nested within some 97 other data structure. 99 1.1. Terminology 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 103 document are to be interpreted as described in [RFC2119]. 105 The following terms are used within this document: 107 o yang data structure: A data structure defined with the "yang-data" 108 statement. 110 1.1.1. NMDA 112 The following terms are defined in the Network Management Datastore 113 Architecture (NMDA) [I-D.ietf-netmod-revised-datastores]. and are 114 not redefined here: 116 o configuration 118 o operational state 120 1.1.2. YANG 122 The following terms are defined in [RFC7950]: 124 o absolute-schema-nodeid 126 o container 128 o data definition statement 130 o data node 132 o leaf 134 o leaf-list 136 o list 138 2. Definitions 139 2.1. Restrictions on Conceptual YANG Data 141 This document places restrictions on the "yang-data" external 142 statements that can be used with the "yang-data" and 143 "augment-yang-data" extensions. The conceptual data definitions are 144 considered to be in the same identifier namespace as defined in 145 section 6.2.1 of [RFC7950]. In particular, bullet 7: 147 All leafs, leaf-lists, lists, containers, choices, rpcs, actions, 148 notifications, anydatas, and anyxmls defined (directly or through 149 a "uses" statement) within a parent node or at the top level of 150 the module or its submodules share the same identifier namespace. 152 This means that conceptual data defined with the "yang-data" or 153 "augment-yang-data" statements cannot have the same local-name as 154 sibling nodes from regular YANG data definition statements or other 155 "yang-data" or "augment-yang-data" statements. 157 This does not mean a yang data structure has to be used as a top- 158 level protocol message or other top-level data structure. A yang 159 data structure does not have to result in a single container. 161 2.2. YANG Data Extensions Module 163 The "ietf-yang-data-ext" module defines the "augment-yang-data" 164 extension to augment conceptual data already defined with the 165 "yang-data" extension. The RESTCONF "yang-data" extension has been 166 moved to this document and updated. 168 RFC Ed.: update the date below with the date of RFC publication and 169 remove this note. 171 file "ietf-yang-data-ext@2018-02-19.yang" 173 module ietf-yang-data-ext { 174 yang-version 1.1; 175 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-data-ext"; 176 prefix "yd"; 178 organization 179 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 181 contact 182 "WG Web: 183 WG List: 185 Author: Andy Bierman 186 188 Author: Martin Bjorklund 189 191 Author: Kent Watsen 192 "; 194 description 195 "This module contains conceptual YANG specifications 196 for defining abstract 'yang-data' data structures. 198 Copyright (c) 2017 - 2018 IETF Trust and the persons identified 199 as authors of the code. All rights reserved. 201 Redistribution and use in source and binary forms, with or 202 without modification, is permitted pursuant to, and subject 203 to the license terms contained in, the Simplified BSD License 204 set forth in Section 4.c of the IETF Trust's Legal Provisions 205 Relating to IETF Documents 206 (http://trustee.ietf.org/license-info)."; 208 revision 2018-02-19 { 209 description 210 "Initial revision."; 211 reference 212 "RFC XXXX: YANG Data Extensions."; 213 } 215 extension yang-data { 216 argument name { 217 yin-element true; 218 } 219 description 220 "This extension is used to specify a YANG data template which 221 represents conceptual data defined in YANG. It is 222 intended to describe hierarchical data independent of 223 protocol context or specific message encoding format. 224 Data definition statements within a yang-data extension 225 specify the generic syntax for the specific YANG data 226 template, whose name is the argument of the yang-data 227 extension statement. 229 Note that this extension does not define a media-type. 230 A specification using this extension MUST specify the 231 message encoding rules, including the content media type. 233 The mandatory 'name' parameter value identifies the YANG 234 data template that is being defined. It contains the 235 template name. This parameter is only used for readability 236 purposes. There are no mechanisms to reuse yang-data by 237 its template name value. 239 This extension is ignored unless it appears as a top-level 240 statement. It MUST contain data definition statements 241 that result in a set of data definition statements. 243 If the yang data template is intended to be used as 244 a top-level structure, then the yang data template needs to 245 result in a single container, so an instance of the YANG data 246 template can thus be translated into an XML instance document, 247 whose top-level element corresponds to the top-level container. 249 The module name and namespace value for the YANG module using 250 the extension statement is assigned to each of the data 251 definition statements resulting from the yang data template. 252 The name of each data definition statement resulting from 253 a yang data template is assigned to a top-level identifier name 254 in the data node identifier namespace, according to RFC 7950, 255 section 6.2.1. 257 The sub-statements of this extension MUST follow the 258 'data-def-stmt' rule in the YANG ABNF. 260 The XPath document root is the extension statement itself, 261 such that the child nodes of the document root are 262 represented by the data-def-stmt sub-statements within 263 this extension. This conceptual document is the context 264 for the following YANG statements: 266 - must-stmt 267 - when-stmt 268 - path-stmt 269 - min-elements-stmt 270 - max-elements-stmt 271 - mandatory-stmt 272 - unique-stmt 273 - ordered-by 274 - instance-identifier data type 276 The following data-def-stmt sub-statements are constrained 277 when used within a yang-data-resource extension statement. 279 - The list-stmt is not required to have a key-stmt defined. 280 - The if-feature-stmt is ignored if present. 281 - The config-stmt is ignored if present. 283 - The available identity values for any 'identityref' 284 leaf or leaf-list nodes is limited to the module 285 containing this extension statement, and the modules 286 imported into that module. 287 "; 288 } 290 extension augment-yang-data { 291 argument path { 292 yin-element true; 293 } 294 description 295 "This extension is used to specify an augmentation to 296 conceptual data defined with the 'yang-data' statement. 297 It is intended to describe hierarchical data independent 298 of protocol context or specific message encoding format. 300 This statement has almost the same structure as the 301 'augment-stmt'. Data definition statements within this 302 statement specify the semantics and generic syntax for the 303 additional data to be added to the specific YANG data template, 304 identified by the 'path' argument. 306 The mandatory 'path' parameter value identifies the YANG 307 conceptual data node that is being augmented, represented 308 as an absolute-schema-nodeid string. 310 This extension is ignored unless it appears as a top-level 311 statement. The sub-statements of this extension MUST follow 312 the 'data-def-stmt' rule in the YANG ABNF. 314 The module name and namespace value for the YANG module using 315 the extension statement is assigned to instance document data 316 conforming to the data definition statements within 317 this extension. 319 The XPath document root is the augmented extension statement 320 itself, such that the child nodes of the document root are 321 represented by the data-def-stmt sub-statements within 322 the augmented yang-data statement. 324 The context node of the augment-yang-data statement is derived 325 in the same way as the 'augment' statement, as defined in 326 section 6.4.1 of [RFC7950]. This conceptual node is 327 considered the context node for the following YANG statements: 329 - must-stmt 330 - when-stmt 331 - path-stmt 332 - min-elements-stmt 333 - max-elements-stmt 334 - mandatory-stmt 335 - unique-stmt 336 - ordered-by 337 - instance-identifier data type 339 The following data-def-stmt sub-statements are constrained 340 when used within a augment-yang-data extension statement. 342 - The list-stmt is not required to have a key-stmt defined. 343 - The if-feature-stmt is ignored if present. 344 - The config-stmt is ignored if present. 345 - The available identity values for any 'identityref' 346 leaf or leaf-list nodes is limited to the module 347 containing this extension statement, and the modules 348 imported into that module. 350 Example: 352 foo.yang { 353 import yang-data-ext { prefix yd; } 355 yd:yang-data foo-data { 356 container foo-con { } 357 } 358 } 360 bar.yang { 361 import yang-data-ext { prefix yd; } 362 import foo { prefix foo; } 364 yd:augment-yang-data /foo:foo-con { 365 leaf add-leaf1 { type int32; } 366 leaf add-leaf2 { type string; } 367 } 368 } 369 "; 370 } 372 } 374 376 3. IANA Considerations 378 3.1. YANG Module Registry 380 TBD 382 4. Security Considerations 384 This document defines YANG extensions that are used to define 385 conceptual YANG data. It does not introduce any new vulnerabilities 386 beyond those specified in YANG 1.1 [RFC7950]. 388 5. Normative References 390 [I-D.ietf-netmod-revised-datastores] 391 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 392 and R. Wilton, "Network Management Datastore 393 Architecture", draft-ietf-netmod-revised-datastores-05 394 (work in progress), October 2017. 396 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 397 Requirement Levels", BCP 14, RFC 2119, March 1997. 399 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 400 RFC 7950, DOI 10.17487/RFC7950, August 2016, 401 . 403 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 404 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 405 . 407 Appendix A. Open Issues 409 A.1. uses-yang-data 411 Is there a need for a separate grouping and uses mechanism for yang- 412 data? Currently only real grouping-stmt and uses-stmt are used. 414 A.2. error-info 416 Is there a need for a special-purpose extension to define yang-data 417 for the contents of the node in NETCONF and 418 RESTCONF responses? This node is defined with anyxml so 419 there is no way for a YANG tool to use real schema nodes, based on 420 the RPC operation being requested or the error-app-tag that is being 421 returned. 423 Authors' Addresses 425 Andy Bierman 426 YumaWorks 428 Email: andy@yumaworks.com 430 Martin Bjorklund 431 Tail-f Systems 433 Email: mbj@tail-f.com 435 Kent Watsen 436 Juniper Networks 438 Email: kwatsen@juniper.net