idnits 2.17.1 draft-agv-netmod-yang-compiler-metadata-01.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 == Line 70 has weird spacing: '...network manag...' == Line 478 has weird spacing: '... with the ...' == Line 479 has weird spacing: '... below with...' == Line 483 has weird spacing: '...as been made...' -- The document date (July 8, 2016) is 2842 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'I-D.ietf-netmod-rfc6020bis' is mentioned on line 199, but not defined == Missing Reference: 'RFC3688' is mentioned on line 482, but not defined == Missing Reference: 'RFC6020' is mentioned on line 494, but not defined == Unused Reference: 'I-D.ietf-netconf-restconf' is defined on line 549, but no explicit reference was found in the text == Unused Reference: 'RFC2330' is defined on line 564, but no explicit reference was found in the text == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-10 Summary: 0 errors (**), 0 flaws (~~), 11 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Draft Vinod Kumar S 3 NETMOD Working Group Gaurav Agrawal 4 Category: Informational Anil Kumar S N 5 Expires: January 9, 2017 July 8, 2016 7 Defining and Using Metadata for YANG compilers 8 draft-agv-netmod-yang-compiler-metadata-01 10 Abstract 12 This document defines mechanism to defining compiler metadata 13 (annotations) in YANG modules using YANG extension statement. 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 9, 2017. 32 Copyright Notice 34 Copyright (c) 2013 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 51 2.1. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . 6 52 2.2. Terms Defined in Other Documents . . . . . . . . . . . . . 6 53 2.4. Definitions of New Terms . . . . . . . . . . . . . . . . . 7 54 3. Defining compiler annotations in YANG . . . . . . . . . . . . 7 55 3.1. Example Definition . . . . . . . . . . . . . . . . . . . . 8 56 4. Using Annotations . . . . . . . . . . . . . . . . . . . . . . 10 57 5. Metadata YANG Module . . . . . . . . . . . . . . . . . . . . . 10 58 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 59 9 Security Considerations . . . . . . . . . . . . . . . . . . . . 13 60 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 13 61 11 References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 62 11.1 Normative References . . . . . . . . . . . . . . . . . . . 14 63 11.2 Informative References . . . . . . . . . . . . . . . . . . 14 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 66 1. Introduction 68 YANG started as a data modeling language used to model configuration 69 data, state data, remote procedure calls, and notifications for 70 network management protocols. The purpose of YANG was focused on 71 expressing the data organization while being exchanged over network. 72 It also addressed the constraints that needs to be taken care by the 73 data set exchanged. 75 YANG has out grown the purpose for which it was invented. Due to its 76 simplicity in structure and flexibility many tools have been 77 developed which tries to ease the application development by 78 automating the code generated corresponding to defined schema. 80 All the implementation related data structures / classes could be 81 auto generated and applications only concentrate on the business 82 logic implementation. Applications are being relieved from actual 83 protocol implementation for exchanging information with external 84 system. 86 The purpose of YANG was focused on expressing the data organization 87 while being exchanged over network. Hence the scope of automation in 88 application development cannot cater to data organization / 89 processing within the system. 91 This gap needs to be addressed in a standardized way so that it's not 92 compiler / utilities / platform / language specific. This enable 93 application to be portable across multiple platforms without any 94 additional effort with respect to data organization. 96 Also it is required that the mechanism of annotation should not be 97 in-line with original YANG module/sub-module, so that it will not 98 result in maintenance issues. 100 So there is a need to support compiler annotations in YANG, by which 101 applications can instruct the YANG utilities or compilers to automate 102 the application development related to data organization / 103 processing. These annotations should be maintained in additional YANG 104 module / sub-module which can be optionally consumed by supporting 105 compilers. 107 Typical use cases are: 109 o Feed input to YANG compiler/utilities which can be used to 110 automate the code generation based on standard data structure or 111 collections. 113 o Enable the code generation to incorporate the design patterns 114 required by applications. 116 o Enable the data structure or collections to have multiple indexes 117 beyond the current supported list's key(s). Since the actual 118 implementation would required searching the data based on 119 different leaf combinations. 121 o Enable applications to model internal data organization, required 122 for business logic implementation, and not exposed to outside 123 world. 125 Usage of compiler annotations are dependent on the compiler consuming 126 it. This draft is intended to document YANG extension to support 128 defining compiler annotation framework.It is outside the scope of 129 this document about the specific compiler annotation(s) definition / 130 usage. Individual annotation definition and usage SHOULD be 131 standardized in other docs. 133 Definition and usage of compiler annotation is limited to a 134 particular protocol or application development within a device, it 135 has no effect on how the management information is exchanged between 136 2 devices over network. A server SHOULD share its YANG file(s) after 137 removing the compiler annotations that was added for its 138 implementation. A client MUST ignore any compiler annotations present 139 in the YANG file(s). A client MAY redefine the compiler annotation as 140 per its implementation requirements. Clients MAY also add new 141 annotation depending on its implementation requirements. 143 This document proposes a systematic way for defining compiler 144 metadata annotations. For this purpose, YANG extension statement 145 "compiler-annotation" is defined in the module "agv-yang-compiler- 146 annotation" (Section 5). Other YANG modules importing this module 147 can use the "compiler-annotation" statement for defining one or more 148 compiler annotations. 150 The benefits of defining the compiler-annotations in a YANG module 151 are the following: 153 o Applications can use YANG as a tool to design the application 154 implementation. 156 o Enhance the YANG compiler(s) capability to automate the 157 application development process. 159 o Enhance the protocol development to provide better application 160 development framework. 162 o YANG could be extended to support data modeling for protocol 163 beyond NETCONF or RESTCONF. 165 Due to the rules for YANG extensions (see sec. 6.3.1 in [I-D.ietf- 166 netmod-rfc6020bis]), compiler-annotation definitions posit relatively 167 weak conformance requirements. The alternative of introducing a new 168 built-in YANG mechanism for compiler annotations was considered, but 169 it was seen as a major change to the language that is inappropriate 170 for YANG 1.1, which was chartered as a maintenance revision. After 171 evaluating real-life usage of compiler metadata annotations, it is 172 designed in such way that the ABNF grammar can seamlessly adapt the 173 current defined compiler annotations. 175 2. Terminology 177 2.1. Keywords 179 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 180 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 181 document are to be interpreted as described in [RFC2119]. 183 2.2. Terms Defined in Other Documents 185 The following terms are defined in [RFC6241]: 187 o capability, 189 o client, 191 o datastore, 193 o message, 195 o protocol operation, 197 o server. 199 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 201 o action, 203 o anydata, 205 o anyxml, 207 o built-in type, 209 o container, 211 o data model, 213 o data node, 215 o data tree, 217 o derived type, 219 o extension, 221 o leaf, 222 o leaf-list, 224 o list, 226 o module, 228 o RPC input and output. 230 2.4. Definitions of New Terms 232 o compiler-annotation: a single item of compiler metadata that is 233 attached to YANG constructs. 234 o compiler metadata: additional information that complements a 235 schema tree. 237 3. Defining compiler annotations in YANG 239 Compiler metadata annotations are defined by YANG extension statement 240 "ca:compiler-annotation". This YANG language extension is defined in 241 the module "ietf-yang-compiler-annotation" (Section 5). 243 Sub-statements of "ca:compiler-annotation" are shown in Table 2. They 244 are all core YANG statements, and the numbers in the second column 245 refer to the corresponding section in [I-D.ietf-netmod- rfc6020bis] 246 where each statement is described. 248 +---------------+---------------------+-------------+ 249 | sub-statement | RFC 6020bis section | cardinality | 250 +---------------+---------------------+-------------+ 251 | description | 7.21.3 | 0..1 | 252 | if-feature | 7.20.2 | 0..n | 253 | reference | 7.21.4 | 0..1 | 254 | status | 7.21.2 | 0..1 | 255 | units | 7.3.3 | 0..1 | 256 | ... | Current Section 5 | 1..n | 257 +---------------+---------------------+-------------+ 259 Table 2: Substatements of "ca:compiler-annotation". 261 This draft only specifies a mechanism to define compiler metadata 262 (annotations) in YANG modules using YANG extension statement. It 263 provides a generic extension based mechanism, to define the 264 annotations, specific extensions needs to be defined for specific 265 data organization annotations as sub statement to compiler annotation 266 extension. 268 An compiler annotation can be made conditional by using one or more 269 "if- feature" statements; the compiler annotation is then consumed by 270 compilers and perform the desired operation in compilation. 272 The semantics and usage rules for a specific compiler-annotation 273 extensions SHOULD be fully specified in another document. 275 A compiler-annotation MUST NOT change the schema tree semantics 276 defined by YANG. For example, it is illegal to define and use an 277 compiler-annotation that allows modification to data-def-stmts. 279 The "status" statement can be used exactly as for YANG schema nodes. 281 3.1. Example Definition 283 module example-yang { 285 namespace "urn:ietf:params:xml:ns:yang:example-yang"; 287 prefix "example-yang"; 289 organization 290 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 292 contact 293 "WG Web: 294 WG List: "; 296 description 297 "This YANG module demonstrates the usage of compiler 298 annotation by any module."; 300 revision 2016-07-08 { 301 description 302 "Initial revision."; 303 reference 304 "draft-agv-netmod-yang-compiler-metadata: example YANG which 305 is annotated"; 306 } 308 container candidate-servers { 309 list server { 310 key "name"; 311 unique "ip port"; 312 leaf name { 313 type string; 314 } 315 leaf ip { 316 type inet:ip-address; 317 } 318 leaf port { 319 type inet:port-number; 320 } 321 } 322 } 323 } 325 The following module defines the "app-data-structure" compiler- 326 annotation as specific compiler annotation extension: 328 module example-compiler-annotation { 330 namespace "urn:ietf:params:xml:ns:yang:example-compiler-annotation"; 332 prefix "example"; 334 import ietf-yang-compiler-annotation { 335 prefix "ca"; 336 } 338 import ietf-yang-app-data-structure-annotation { 339 prefix "ds"; 340 } 342 organization 343 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 345 contact 346 "WG Web: 347 WG List: "; 349 description 350 "This YANG module demonstrates the usage of compiler 351 annotation by any module."; 353 revision 2016-07-08 { 354 description 355 "Initial revision."; 356 reference 357 "draft-agv-netmod-yang-compiler-metadata: example of 358 defining and using compiler annotations with YANG"; 359 } 361 ca:compiler-annotation /candidate-servers/server { 362 ds:app-data-structure queue; 363 } 364 } 366 4. Using Annotations 368 By defining a YANG module in which a compiler metadata annotation is 369 defined using the "ca:compiler-annotation" statement, an application 370 indicates compiler to handle that compiler-annotation according to 371 the compiler-annotation's definition. That is, the compiler- 372 annotation uses it as input for automation of code generation or 373 applications development. 375 Depending on its semantics, an annotation may have an effect only in 376 certain schema trees and/or on specific schema node types. 378 A client MUST NOT use the compiler-annotation to interpret the schema 379 even if it is advertised by a server. 381 5. Metadata YANG Module 383 FC Editor: In this section, replace all occurrences of 'XXXX' with 384 he actual RFC number and all occurrences of the revision date below 385 ith the date of RFC publication (and remove this note). 387 FC Editor: Also please replace all occurrences of 'RFC 6020bis' with 388 he actual RFC number that will be assigned to [I-D.ietf-netmod- 389 fc6020bis]. 391 CODE BEGINS> file "ietf-yang-compiler-annotation.yang" 393 odule ietf-yang-compiler-annotation { 395 amespace "urn:ietf:params:xml:ns:yang:ietf-yang-compiler-annotation"; 397 refix "ca"; 399 rganization 400 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 402 ontact 403 "WG Web: 404 WG List: "; 406 escription 407 "This YANG module defines an extension statement that allows for 408 defining compiler annotations. 410 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 411 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 412 'OPTIONAL' in the module text are to be interpreted as described 413 in RFC 2119 (http://tools.ietf.org/html/rfc2119)."; 415 revision 2016-07-08 { 416 description 417 "Initial revision."; 418 reference 419 "draft-agv-netmod-yang-compiler-metadata: 420 Defining and Using compiler annotations with YANG"; 421 } 423 extension compiler-annotation { 424 argument target; 425 description 426 "This extension allows for defining compiler annotations for 427 any body-stmts. The 'ca:compiler-annotation' statement 428 contains annotations applicable to its target statement 429 identified by the argument. 431 It's purpose is to provide additional information to compiler 432 about implementation of the modeled information. 434 he argument is a string that identifies a node in the 435 chema tree. This node is called the compiler annotation's 436 target node. The target node MUST be a body-stmt as defined 437 in RFC6020bis. 439 It MAY be consumed by the compiler of the device supporting 440 the schema. 442 The compiler annotations must be defined in a seperate YANG file, 443 so that there are no maintenance issues. 445 The ca:compiler-annotation defined with this extension 446 statement do not affect the namespace or get impacted by 447 the namespace of the YANG file where it is used. 449 Semantics of the annotation and other documentation can be 450 specified using the following standard YANG substatements (all 451 are optional): 'description', 'reference', 'status', and 452 'units'. 454 The presence of a 'if-feature' child to the ca: 455 compiler-annotation, means the compiler consumes the 456 annotation when the feature is supported by the device. 458 Server SHOULD NOT share ca:compiler-annotations YANG files 459 while sharing schema with a client in protocol exchange. 461 Client receiving the schema from a Server in protocol 462 exchange, MUST ignore the YANG files with any 463 ca:compiler-annotations extension. 465 There must be one or more sub statements with specific compiler 466 annotation extensions. (Note: Specific compiler annotation 467 extensions SHOULD be covered as a part of other standard 468 documents.) 470 } // compiler-annotation 471 //module agv-yang-compiler-annotation 473 CODE ENDS> 475 8. IANA Considerations 477 RFC Editor: In this section, replace all occurrences of 'XXXX' 478 with the actual RFC number and all occurrences of the revision date 479 below with the date of RFC publication (and remove this note). 481 This document registers a URI in the "IETF XML registry" 482 [RFC3688]. Following the format in RFC 3688, the following 483 registration has been made. 485 ------------------------------------------------------------------ 486 URI: urn:agv:params:xml:ns:yang:agv-yang-compiler-annotation 488 Registrant Contact: The NETMOD WG of the IETF. 490 XML: N/A, the requested URI is an XML namespace. 491 ------------------------------------------------------------------ 493 This document registers a YANG module in the "YANG Module Names" 494 registry [RFC6020]. 496 ------------------------------------------------------------------ 497 name: agv-yang-compiler-annotation 498 namespace: urn:agv:params:xml:ns:yang: 499 agv-yang-compiler-annotation 500 prefix: md 501 reference: RFC XXXX 502 ------------------------------------------------------------------ 504 9 Security Considerations 506 This document introduces a mechanism for defining compiler metadata 507 annotations in YANG modules and attaching them to instances of YANG 508 schema nodes. By itself, this mechanism represents no security 509 threat. Security implications of a particular compiler-annotation 510 defined using this mechanism MUST be duly considered and documented 511 in the the compiler-annotation's definition. 513 10. Acknowledgments 514 11 References 516 11.1 Normative References 518 I-D.ietf-netmod-rfc6020bis] 519 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 520 draft-ietf-netmod-rfc6020bis-11 (work in progress), 521 February 2016. 523 I-D.ietf-netmod-yang-json] 524 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 525 draft-ietf-netmod-yang-json-09 (work in progress), March 526 2016. 528 RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 529 Requirement Levels", BCP 14, RFC 2119, 530 DOI 10.17487/RFC2119, March 1997, 531 . 533 RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 534 DOI 10.17487/RFC3688, January 2004, 535 . 537 RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for 538 Syntax Specifications: ABNF", STD 68, RFC 5234, 539 DOI 10.17487/RFC5234, January 2008, 540 . 542 RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 543 the Network Configuration Protocol (NETCONF)", RFC 6020, 544 DOI 10.17487/RFC6020, October 2010, 545 . 547 11.2 Informative References 549 [I-D.ietf-netconf-restconf] 550 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 551 Protocol", draft-ietf-netconf-restconf-10 (work in 552 progress), March 2016. 554 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., 555 and A. Bierman, Ed., "Network Configuration Protocol 556 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 557 . 559 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 560 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 561 RFC2119, March 1997, 562 . 564 [RFC2330] Paxson, V., Almes, G., Mahdavi, J., and M. Mathis, 565 "Framework for IP Performance Metrics", RFC 2330, 566 May 1998. 568 Authors' Addresses 570 Vinod Kumar S 571 Huawei Technologies India Pvt. Ltd, 572 Near EPIP Industrial Area, 573 Kundalahalli Village, 574 Whitefield, 575 Bangalore - 560066 577 EMail: vinods.kumar@huawei.com 579 Gaurav Agrawal 580 Huawei Technologies India Pvt. Ltd, 581 Near EPIP Industrial Area, 582 Kundalahalli Village, 583 Whitefield, 584 Bangalore - 560066 586 EMail: gaurav.agrawal@huawei.com 588 Anil Kumar S N 589 Huawei Technologies India Pvt. Ltd, 590 Near EPIP Industrial Area, 591 Kundalahalli Village, 592 Whitefield, 593 Bangalore - 560066 595 EMail: anil.ietf@gmail.com