idnits 2.17.1 draft-lengyel-netmod-schema-annotation-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 (January 24, 2017) is 2647 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) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) == Outdated reference: A later version (-25) exists of draft-ietf-netconf-yang-push-04 == Outdated reference: A later version (-12) exists of draft-ietf-netmod-schema-mount-03 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Netmod B. Lengyel 3 Internet-Draft Ericsson 4 Intended status: Standards Track January 24, 2017 5 Expires: July 28, 2017 7 Schema Annotation for YANG Models 8 draft-lengyel-netmod-schema-annotation-00 10 Abstract 12 In some cases there is a need to qualify other YANG models or some 13 schema nodes in other models with additional properties (a.k.a. 14 annotations). This document defines a method to add annotations in 15 the form of YANG extension statements to YANG modules. The 16 annotations are defined in separate files without modifying the text 17 of the original YANG module. 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 July 28, 2017. 36 Copyright Notice 38 Copyright (c) 2017 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. Use Case - Yangpush . . . . . . . . . . . . . . . . . . . 3 55 1.2. Use Case - Vendor Annotation of a Standard Model . . . . 3 56 2. Possible solutions . . . . . . . . . . . . . . . . . . . . . 3 57 2.1. Instance Data based Solution . . . . . . . . . . . . . . 4 58 2.2. Extension based Solution . . . . . . . . . . . . . . . . 5 59 2.3. Deviation based Solution . . . . . . . . . . . . . . . . 6 60 2.4. Pros and Cons . . . . . . . . . . . . . . . . . . . . . . 6 61 3. How is this different from RFC7952 "Defining and Using 62 Metadata with YANG?" . . . . . . . . . . . . . . . . . . . . 7 63 4. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 66 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 8 69 8.2. Informative References . . . . . . . . . . . . . . . . . 8 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 72 1. Introduction 74 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 75 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 76 document are to be interpreted as described in [RFC2119]. 78 In some cases there is a need to qualify other YANG models or some 79 schema nodes in other models with additional properties (a.k.a. 80 annotations). This document defines a method to add annotations in 81 the form of YANG [RFC7950] extension statements to YANG modules. The 82 annotations are defined in separate files without modifying the text 83 of the original YANG module. 85 Annotations are often specific to the model and/or implementation so 86 they are possible to define in design time. System integrators, 87 people defining configuration ahead of time and others need this 88 information (without reading any data from a live node). 90 Often the basic YANG model and the extra properties are defined 91 separately, possibly by different organizations. Vendors may qualify 92 standard models with extra properties, or even a vendor defined base 93 model, may need different annotations depending on the specific 94 implementation. Vendors are reluctant to modify the standard models 95 (messing up the original file, too many variants of the base model), 96 so it must be possible to define such annotations in a separate file/ 97 module. 99 1.1. Use Case - Yangpush 101 In YangPush [I-D.ietf-netconf-yang-push] we need to specify for data 102 nodes whether the Yang server supports sending on-change data change 103 notifications for the specific data node or not. Some servers may 104 not support such notifications for specific data nodes because they 105 are meaningless or would result in too many notifications or the 106 server might simply not have implemented them. The support for on- 107 change notifications will be defined using a YANG extension 108 statement. 110 In some cases there is a need to specify the minimum acceptable 111 interval for a periodic subscription for a specific data node or 112 schema branch. 114 1.2. Use Case - Vendor Annotation of a Standard Model 116 Vendors sometimes want to add extra information to the standard YANG 117 models. Examples include instructions for automatic code generation 118 or formal description of side-effects of manipulating a data node. 119 It would be good for standard SW tools to be at least aware of the 120 vendor extensions, allowing vendor specific plugins to handle these 121 extensions. By providing a standard mechanism to annotate modules 122 generic SW tools might provide somevisibility to vendor specific 123 extensions e.g. providing APIs to fetch the extension, displaying the 124 extension as is. 126 2. Possible solutions 128 All solution alternatives use an Absolute schema node identifier to 129 identify which part of the YANG schema is annotated. Absolute schema 130 node identifier is defined in [RFC7950]. 132 All alternatives will have the same effect as if the YANG extension 133 statement in the annotation was placed in the base model itself. 135 The process of annotation will consist of the following steps. A 136 base model will be defined. E.g. IETF defined a standard base model 137 like ietf-system. A vendor will define extra data like instance data 138 or annotation/deviation YANG modules (e.g. ericsson-system-ann- 139 router1230-release3.yang). Annotation information MAY be defined 140 once per vendor or for every product/product release separately. 141 Annotation information will be available both in design-time as a 142 document and in run-time. 144 2.1. Instance Data based Solution 146 A new YANG module containing information about schema-annotations is 147 defined and a standard way of loading initial instance data in to 148 that module is specified. (Note the module is only an example to 149 demonstrate the concept. If the solution is selected, further work 150 on the module is needed.) 152 module ietf-schema-annotations { 153 list schema-annotations { 154 key target; 155 config false; 156 leaf target { 157 type schema-node-id; 158 description "identifies the node in the schema tree 159 that is annotated."; 160 } 162 list annotation { 163 key statement; 164 min-elements 1; 165 leaf statement { 166 type yang:yang-identifier; 167 description "The statement to be conceptually 168 added to the target schema node."; 169 } 170 leaf argument { 171 type string; 172 description "Argument to the annotation 173 statement if any."; 174 } 175 } 176 } 177 } 179 A standard format to specify initial instance data for a YANG module 180 in a file is defined. The format SHALL be the same as the XML 181 content of the operation inside the element. 182 The format was chosen as that will allow specifying the 183 operation attribute. Both the merge and the replace values might be 184 needed and/or useful. 186 If the instance data represents configuration data it SHALL be loaded 187 by the YANG server at startup into the running datastore of the 188 server before any management interface like CLI, Netconf, Restconf is 189 started. Note this MAY result in overwriting data previously stored 190 in the datastore. If the instance data represents state data it 191 SHALL be loaded by the YANG server at startup into the operation- 192 state datastore before any management interface like CLI, Netconf, 193 Restconf is started. 195 Example: 197 198 /sys:system/sys:system-time 199 200 yp:notifiable-on-change 201 false 202 203 205 Instance data for the module ietf-schema-annotations SHOULD become a 206 design time artifact provided by the model designer just as the YANG 207 modules themselves. 209 The XML instance data defining the annotations would be available in 210 design-time as an XML document and in run-time using the 211 operation. 213 2.2. Extension based Solution 215 A new YANG extension "schema-annotation" is defined, that allows 216 adding statement to another module. 218 extension schema-annotation { 219 description 220 "Annotates an existing statement with a YANG extension 221 statement defined in some module. Useful for 222 adding extension statements to a module without touching the 223 module source. 225 Substatements to this statements are conceptually added 226 to the target statement. 228 The argument is a 'absolute schema node identifier'. 229 It identifies a target node in the schema tree to 230 annotate with new statements."; 232 argument target; 233 } 235 Example: 237 sann:schema-annotation /sys:system/sys:system-time { 238 yp:notifiable-on-change false; 239 } 241 The annotating module would be available in design-time as a document 242 and in run-time using the operation. 244 2.3. Deviation based Solution 246 Deviations already allow adding/modifying model information for 247 another module. If IETF would allow the "deviate" statement to 248 handle YANG extension statements this would allow us to add/remove/ 249 modify annotations. 251 2.4. Pros and Cons 253 The Instance Data based Solution is the proposed solution. 255 o It could be usable for other purposes as well including but not 256 restricted to defining default security rules for access control 257 [RFC6536] or defining yang-schema-mounts 258 [I-D.ietf-netmod-schema-mount] in design time. 260 o It is more simple to read in runtime for management systems (MS). 262 o If annotation data was ever changed the MS could get notifications 263 about that. 265 o It could easily be linked with references to the ietf-yang-library 267 o It introduces a bigger new concept (instance data) although a 268 number of vendors are already using it. 270 The Extension Based Solution works. 272 We do not recommend using the Deviation based Solution as deviations 273 are for documenting unwelcome implementation limitations and are 274 highly discouraged. Adding our extra information is not just 275 acceptable, it is the recommended thing to do. Extending the allowed 276 substatements for the deviate statement can also be considered 277 changing [RFC7950]. 279 3. How is this different from RFC7952 "Defining and Using Metadata with 280 YANG?" 282 [RFC7952] defines metadata on the instance data level, here we need 283 metadata on the model/schema level. 285 [RFC7952] metadata is transferred in Netconf/Restconf RPCs, here we 286 usually do not need that. 288 [RFC7952] metadata is only available in runtime, here we need it to 289 be available in design time. 291 4. Open Issues 293 o Set of statements that can be the target. The initial proposal is 294 to allow the same set of schema nodes as "deviation" statement. 295 Is that OK? 297 o Set of statements that can be added. The initial proposal allows 298 only YANG extension statements. Do we want to allow anything else 299 like additional "must" statements or restrictions? Probably not 300 as that would allow redefining the base model, which we don't 301 want. We only want to add information to it. 303 o Exact data model for module ietf-schema-annotations. 305 o Do we need replace and delete operations beside the add? The 306 initial proposal only allows adding annotations. Do we need to be 307 able to replace and remove them as well? 309 5. Acknowledgements 311 The author wishes to thank Eric Voit, Einar Nilsen-Nygaard and 312 Alexander Clemm for their helpful comments contributing to this 313 draft. 315 6. IANA Considerations 317 No IANA considerations 319 7. Security Considerations 321 This document introduces a mechanism for attaching metadata defined 322 in the form of YANG extensions to the YANG schema of another YANG 323 module. By itself, this mechanism represents no security threat. 324 Security implications of a particular extension and attaching it to a 325 particular YANG module shall be considered in the document defining/ 326 attaching the extension. 328 8. References 330 8.1. Normative References 332 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 333 Requirement Levels", BCP 14, RFC 2119, 334 DOI 10.17487/RFC2119, March 1997, 335 . 337 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 338 Protocol (NETCONF) Access Control Model", RFC 6536, 339 DOI 10.17487/RFC6536, March 2012, 340 . 342 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 343 RFC 7950, DOI 10.17487/RFC7950, August 2016, 344 . 346 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 347 RFC 7952, DOI 10.17487/RFC7952, August 2016, 348 . 350 8.2. Informative References 352 [I-D.ietf-netconf-yang-push] 353 Clemm, A., Voit, E., Prieto, A., Tripathy, A., Nilsen- 354 Nygaard, E., Bierman, A., and B. Lengyel, "Subscribing to 355 YANG datastore push updates", draft-ietf-netconf-yang- 356 push-04 (work in progress), October 2016. 358 [I-D.ietf-netmod-schema-mount] 359 Bjorklund, M. and L. Lhotka, "YANG Schema Mount", draft- 360 ietf-netmod-schema-mount-03 (work in progress), October 361 2016. 363 Author's Address 365 Balazs Lengyel 366 Ericsson 368 Email: balazs.lengyel@ericsson.com