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