idnits 2.17.1 draft-bierman-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 (July 3, 2017) is 2482 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 July 3, 2017 5 Expires: January 4, 2018 7 YANG Data Extensions 8 draft-bierman-netmod-yang-data-ext-00 10 Abstract 12 This document describes YANG mechanisms for extending the utility of 13 the 'yang-data' extension statement defined in RFC 8040. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on January 4, 2018. 32 Copyright Notice 34 Copyright (c) 2017 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. Restrictions on Conceptual YANG Data . . . . . . . . . . 3 55 2.2. YANG Data Extensions Module . . . . . . . . . . . . . . . 3 56 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 57 3.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 6 58 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 59 5. Normative References . . . . . . . . . . . . . . . . . . . . 6 60 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 62 1. Introduction 64 There is a need for standard mechanisms to allow the definition of 65 abstract data that is not intended to be implemented as configuration 66 data or state data. The 'yang-data' extension statement from RFC 67 8040 [RFC8040] is defined for this purpose, however it is limited in 68 its functionality. 70 The intended use of the "yang-data" extension is to model all or part 71 of a protocol message, such as the "errors" definition in ietf- 72 restconf.yang [RFC8040]. However, protocols are often layered such 73 that the header or payload portions of the message can be extended by 74 external documents. The YANG statements that model a protocol need 75 to support this extensibility that is already found in that protocol. 77 This document defines a new YANG extension statement called 78 "augment-yang-data", which allows abstract data structures to be 79 augmented from external modules, similar to the existing YANG 80 "augment" statement, which cannot be used because a YANG compiler or 81 other tool is not required to understand the "yang-data" extension. 83 1.1. Terminology 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 87 document are to be interpreted as described in [RFC2119]. 89 1.1.1. NETCONF 91 The following terms are defined in [RFC6241]: 93 o configuration data 94 o state data 96 1.1.2. YANG 98 The following terms are defined in [RFC7950]: 100 o absolute-schema-nodeid 102 o container 104 o data node 106 o leaf 108 o leaf-list 110 o list 112 2. Definitions 114 2.1. Restrictions on Conceptual YANG Data 116 This document places restrictions on the "yang-data" external 117 statements that can be used with the "augment-yang-data" extension. 118 The conceptual data definitions are considered to be in the same 119 identifier namespace as defined in section 6.2.1 of [RFC7950]. In 120 particular, bullet 7: 122 All leafs, leaf-lists, lists, containers, choices, rpcs, actions, 123 notifications, anydatas, and anyxmls defined (directly or through 124 a "uses" statement) within a parent node or at the top level of 125 the module or its submodules share the same identifier namespace. 127 This means that conceptual data defined with the "yang-data" or 128 "augment-yang-data" statements cannot have the same local-name as 129 sibling nodes from regular YANG data-def statements or other 130 "yang-data" or "augment-yang-data" statements. 132 2.2. YANG Data Extensions Module 134 The "yang-data-ext" module defines the 'augment-yang-data' extension 135 to augment conceptual data already defined with the RESTCONF 136 "yang-data" extension. 138 Note that there is no YANG tree diagram provided because pyang does 139 not produce any tree output for a module containing only an extension 140 statement. 142 file "yang-data-ext@2017-07-03.yang" 144 module yang-data-ext { 145 namespace "urn:ietf:params:xml:ns:yang:yang-data-ext"; 146 prefix "yd"; 148 organization 149 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 151 contact 152 "WG Web: 153 WG List: 155 Author: Andy Bierman 156 "; 158 description 159 "This module contains conceptual YANG specifications 160 for augmenting abstract 'yang-data' data structures. 162 Copyright (c) 2017 IETF Trust and the persons identified as 163 authors of the code. All rights reserved. 165 Redistribution and use in source and binary forms, with or 166 without modification, is permitted pursuant to, and subject 167 to the license terms contained in, the Simplified BSD License 168 set forth in Section 4.c of the IETF Trust's Legal Provisions 169 Relating to IETF Documents 170 (http://trustee.ietf.org/license-info)."; 172 revision 2017-07-03 { 173 description 174 "Initial revision."; 175 reference 176 "RFC XXXX: YANG Data Extensions."; 177 } 179 extension augment-yang-data { 180 argument path { 181 yin-element true; 182 } 183 description 184 "This extension is used to specify an augmentation to 185 conceptual data defined with the 'yang-data' statement. 186 It is intended to describe hierarchical data independent 187 of protocol context or specific message encoding format. 189 This statement has almost the same structure as the 190 'augment-stmt'. Data definition statements within this 191 statement specify the semantics and generic syntax for the 192 additional data to be added to the specific YANG data template, 193 identified by the 'path' argument. 195 Note that this extension does not define a media-type. 196 A specification using this extension MUST specify the 197 message encoding rules, including the content media type. 199 The mandatory 'path' parameter value identifies the YANG 200 conceptual data node that is being augmented, represented 201 as an absolute-schema-nodeid string. 203 This extension is ignored unless it appears as a top-level 204 statement. The sub-statements of this extension MUST follow 205 the 'data-def-stmt' rule in the YANG ABNF. 207 The module name and namespace value for the YANG module using 208 the extension statement is assigned to instance document data 209 conforming to the data definition statements within 210 this extension. 212 The XPath document root is the augmented extension statement 213 itself, such that the child nodes of the document root are 214 represented by the data-def-stmt sub-statements within 215 the augmented yang-data statement. 217 The context node of the augment-yang-data statement is derived 218 in the same way as the 'augment' statement, as defined in 219 section 6.4.1 of [RFC7950]. This conceptual node is 220 considered the context node for the following YANG statements: 222 - must-stmt 223 - when-stmt 224 - path-stmt 225 - min-elements-stmt 226 - max-elements-stmt 227 - mandatory-stmt 228 - unique-stmt 229 - ordered-by 230 - instance-identifier data type 232 The following data-def-stmt sub-statements are constrained 233 when used within a augment-yang-data extension statement. 235 - The list-stmt is not required to have a key-stmt defined. 236 - The if-feature-stmt is ignored if present. 237 - The config-stmt is ignored if present. 239 - The available identity values for any 'identityref' 240 leaf or leaf-list nodes is limited to the module 241 containing this extension statement, and the modules 242 imported into that module. 244 Example: 246 foo.yang { 247 import ietf-restconf { prefix rc; } 249 rc:yang-data foo-data { 250 container foo-con { } 251 } 252 } 254 bar.yang { 255 import yang-data-ext { prefix yd; } 256 import foo { prefix foo; } 258 yd:augment-yang-data /foo:foo-con { 259 leaf add-leaf1 { type int32; } 260 leaf add-leaf2 { type string; } 261 } 262 } 263 "; 264 } 266 } 268 270 3. IANA Considerations 272 3.1. YANG Module Registry 274 TBD 276 4. Security Considerations 278 This document defines a YANG extension which is used to define 279 conceptual YANG data. It does not introduce any new vulnerabilities 280 beyond those specified in YANG 1.1 [RFC7950]. 282 5. Normative References 284 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 285 Requirement Levels", BCP 14, RFC 2119, March 1997. 287 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 288 and A. Bierman, Ed., "Network Configuration Protocol 289 (NETCONF)", RFC 6241, June 2011. 291 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 292 RFC 7950, DOI 10.17487/RFC7950, August 2016, 293 . 295 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 296 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 297 . 299 Author's Address 301 Andy Bierman 302 YumaWorks 304 Email: andy@yumaworks.com