idnits 2.17.1 draft-lhotka-netmod-yang-metadata-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 (September 11, 2014) is 3514 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 7159 (ref. '6') (Obsoleted by RFC 8259) == Outdated reference: A later version (-10) exists of draft-ietf-netmod-yang-json-00 -- Possible downref: Non-RFC (?) normative reference: ref. '8' == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-01 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD Working Group L. Lhotka 3 Internet-Draft CZ.NIC 4 Intended status: Standards Track September 11, 2014 5 Expires: March 15, 2015 7 Defining and Using Metadata with YANG 8 draft-lhotka-netmod-yang-metadata-00 10 Abstract 12 This document defines a YANG extension statement that allows for 13 defining metadata annotions in YANG modules. The document also 14 specifies the encoding of annotations and rules for annotating 15 instances of YANG data nodes. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on March 15, 2015. 34 Copyright Notice 36 Copyright (c) 2014 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 3. Defining Annotations in YANG . . . . . . . . . . . . . . . . 5 54 4. The Encoding of Annotations . . . . . . . . . . . . . . . . . 6 55 4.1. XML Encoding . . . . . . . . . . . . . . . . . . . . . . 6 56 4.2. JSON Encoding . . . . . . . . . . . . . . . . . . . . . . 7 57 4.2.1. Metadata Object and Annotations . . . . . . . . . . . 7 58 4.2.2. Adding Annotations to Container, Anyxml and List 59 Instances . . . . . . . . . . . . . . . . . . . . . . 8 60 4.2.3. Adding Annotations to Leaf Instances . . . . . . . . 8 61 4.2.4. Adding Annotations to Leaf-list Instances . . . . . . 9 62 5. Representing Annotations in DSDL Schemas . . . . . . . . . . 9 63 6. Metadata YANG Module . . . . . . . . . . . . . . . . . . . . 11 64 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 65 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 66 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 67 9.1. Normative References . . . . . . . . . . . . . . . . . . 13 68 9.2. Informative References . . . . . . . . . . . . . . . . . 14 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 71 1. Introduction 73 There is a need to be able to annotate instances of YANG [3] data 74 nodes with various metadata. Typical use cases are: 76 o Deactivating a subtree in a configuration datastore while keeping 77 the data in place. 79 o Qualifying the data model information with instance-specific data. 80 For example, an annotation may be attached to an instance of a 81 leaf with the "union" type to indicate the member type to which 82 the instance belongs. 84 o RPC operations may use metadata annotations for different purposes 85 in both requests and responses. For example, the 86 operation in the NETCONF protocol (see section 7.2 of [5]) uses 87 annotations in the form of XML attributes for identifying the 88 point in the configuration and type of the operation. 90 However, metadata annotations could potentially lead to 91 interoperability problems if they are used in an ad hoc way by 92 different organizations and/or without proper documentation. A sound 93 metadata framework for YANG should therefore satisfy these 94 requirements: 96 1. The set of annotations must be extensible in a distributed manner 97 so as to allow for defining new annotations without running into 98 the risk of collisions with annotations defined and used by 99 others. 101 2. Syntax and semantics of annotations must be documented and the 102 documentation must be easily accessible. 104 3. Clients of network management protocols such as NETCONF [5] or 105 RESTCONF [10] must be able to learn all annotations supported by 106 a given server and identify each of them correctly. 108 This document proposes a systematic way for defining and using 109 metadata annotations that satisfies the above requirements. For this 110 purpose, YANG extension statement "annotation" is defined in the 111 module "ietf-yang-metadata" (Section 6). Other YANG modules 112 importing this module can use the "annotation" statement for defining 113 one or more annotations. 115 The benefits of defining metadata annotations in a YANG module are as 116 follows: 118 o Each annotation is bound to a YANG module name, namespace URI and 119 prefix. This makes its encoding in instance documents (both XML 120 and JSON) straightforward and consistent with the encoding of YANG 121 data node instances. 123 o Annotations are indirectly registered through IANA YANG module 124 registration. 126 o Annotations are included in the data model. Specifically, servers 127 indicate support for certain annotations using standard module 128 advertisement methods, such as the message in NETCONF. 130 o Values of annotations need not be strings; any YANG built-in or 131 derived type may be used for them. 133 2. Terminology 135 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 136 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 137 document are to be interpreted as described in [1]. 139 The following terms are defined in [5]: 141 o client, 143 o datastore, 144 o message, 146 o operation, 148 o server. 150 The following terms are defined in [3]: 152 o anyxml, 154 o built-in type, 156 o derived type, 158 o container, 160 o data model, 162 o data node, 164 o derived type, 166 o extension, 168 o leaf-list, 170 o list, 172 o module, 174 o RPC operation, 176 o submodule, 178 o type. 180 The following terms are defined in [8]: 182 o attribute, 184 o document, 186 o element, 188 o namespace, 190 o prefix. 192 The following terms are defined in [6]: 194 o array, 196 o member, 198 o object, 200 o primitive type. 202 XML element names and YANG extension statements are always written 203 with explicit namespace prefixes that are assumed to be bound to URI 204 references as shown in Table 1. 206 +--------+------------------------------------------------+ 207 | Prefix | URI Reference | 208 +--------+------------------------------------------------+ 209 | rng | http://relaxng.org/ns/structure/1.0 | 210 | md | urn:ietf:params:xml:ns:yang:ietf-yang-metadata | 211 | ein | http://example.org/example-inactive | 212 +--------+------------------------------------------------+ 214 Table 1: Used namespace prefixes and corresponding URI references 216 3. Defining Annotations in YANG 218 Metadata annotations are defined with YANG extension statement 219 "md:annotation". This YANG language extension is defined in the 220 module "ietf-yang-metadata" (Section 6). 222 Substatements of "md:annotation" are shown in Table 2. They are all 223 core YANG statements, and the numbers in the second column refer to 224 the corresponding sections in RFC 6020 [3] where each statement is 225 described. 227 +--------------+------------------+-------------+ 228 | substatement | RFC 6020 section | cardinality | 229 +--------------+------------------+-------------+ 230 | description | 7.19.3 | 0..1 | 231 | reference | 7.19.4 | 0..1 | 232 | status | 7.19.2 | 0..1 | 233 | type | 7.6.3 | 0..1 | 234 | units | 7.3.3 | 0..1 | 235 +--------------+------------------+-------------+ 237 Table 2: Substatements of "md:annotation". 239 Using the "type" statement, a type may be specified for the 240 annotation value according to the same rules as for YANG leaf or 241 leaf-list types. However, the "type" statement is optional as a 242 substatement of "md:annotation" statement. If it is not present, the 243 built-in "string" type is the default. 245 For example, the following module defines the "inactive" annotation: 247 module example-inactive { 248 namespace "http://example.org/example-inactive"; 249 prefix "ein"; 250 import ietf-yang-metadata { 251 prefix "md"; 252 } 253 md:annotation inactive { 254 type boolean; 255 description 256 "If this annotation is attached to a configuration data node, 257 and its value is 'true', then the server MUST behave 258 as if the data subtree rooted at this node was not 259 present."; 260 } 261 } 263 Metadata annotations defined with the "md:annotation" statement may 264 be attached to any valid instance of a data node, i.e., container, 265 leaf, list, leaf-list or anyxml, throughout the data model. Metadata 266 annotations are always optional. 268 4. The Encoding of Annotations 270 XML attributes are a natural choice for encoding metadata in XML 271 instance documents. For JSON [6], there is no generally established 272 method for encoding metadata. This document thus introduces a 273 special encoding method that is consistent with the JSON encoding of 274 YANG data node instances as defined in [7]. 276 4.1. XML Encoding 278 Metadata annotations are added to XML-encoded instances of YANG data 279 nodes as XML attributes according to these rules: 281 o The local name of the attribute SHALL be the same as the name of 282 the annotation specified in the argument of the corresponding 283 "md:annotation" statement. 285 o The namespace of the attribute SHALL be identified by the URI that 286 appears as the argument of the "namespace" statement in the YANG 287 module where the annotation is defined. It is RECOMMENDED that 288 the prefix specified by the "prefix" statement in the same module 289 is used in the qualified name of the attribute. 291 o The attribute value SHALL be encoded in the same way as the value 292 of a YANG leaf instance having the same type. 294 For example, the "inactive" annotation as defined in Section 3 may be 295 encoded as follows: 297 299 ... 300 302 4.2. JSON Encoding 304 The metadata encoding defined in this section has the following 305 properties: 307 1. The encoding of YANG data node instances as defined in [7] does 308 not change. 310 2. Namespaces of metadata annotations are encoded in the same way as 311 namespaces of YANG data node instances, see [7]. 313 4.2.1. Metadata Object and Annotations 315 All metadata annotations assigned to a YANG data node instance are 316 encoded as members (name/value pairs) of a single JSON object, 317 henceforth denoted as the metadata object. The placement and name of 318 this object depends on the type of the data node as specified in the 319 following subsections. 321 The name of a metadata annotation (member of the metadata object) 322 SHALL be of the following form: 324 MODULE_NAME:LOCAL_NAME 326 where MODULE_NAME is the name of the YANG module in which the 327 annotation is defined, and LOCAL_NAME is the name of the annotation 328 specified in the argument of the corresponding "md:annotation" 329 statement. 331 Note that unlike YANG data node instances, for annotations the 332 explicit namespace identifier (MODULE_NAME) must always be used. 334 The value of a metadata annotation SHALL be encoded in exactly the 335 same way as the value of a YANG leaf node having the same type as the 336 annotation. 338 4.2.2. Adding Annotations to Container, Anyxml and List Instances 340 For an instance that is translated to a JSON object (i.e., a 341 container, anyxml or list entry), the metadata object is added as a 342 new member of that object with the name "@". 344 Examples: 346 o "cask" is a container or anyxml node: 348 "cask": { 349 "@": { 350 "example-inactive:inactive": true 351 }, 352 ... 353 } 355 o "seq" is a list whose key is "name", annotation "inactive" is 356 added only to the first entry: 358 "seq": [ 359 { 360 "@": { 361 "example-inactive:inactive": true 362 }, 363 "name": "one", 364 ... 365 }, 366 { 367 "name": "two", 368 ... 369 } 370 ] 372 4.2.3. Adding Annotations to Leaf Instances 374 For a leaf instance, the metadata object is added as a sibling name/ 375 value pair whose the name is the symbol "@" concatenated with the 376 identifier of the leaf. 378 For example, if "flag" is a leaf node: 380 "flag": true, 381 "@flag": { 382 "example-inactive:inactive": true 383 } 385 4.2.4. Adding Annotations to Leaf-list Instances 387 For a leaf-list instance, which is represented as a JSON array with 388 values of a primitive type, annotations may be assigned to one or 389 more entries by adding a name/array pair as a sibling the leaf-list 390 instance, where the name is the symbol "@" concatenated with the 391 identifier of the leaf-list, and the value is a JSON array whose i-th 392 element is the metadata object with annotations assigned to the i-th 393 entry of the leaf-list instance, or null if the i-th entry has no 394 annotations. 396 Trailing null values in the array, i.e., those following the last 397 non-null metadata object, MAY be omitted. 399 For example, in the following leaf-list instance with four entries, 400 the "inactive" annotation is added to the second and third entry in 401 the following way: 403 "folio": [6, 3, 7, 8], 404 "@folio": [ 405 null, 406 {"example-inactive:inactive": true}, 407 {"example-inactive:inactive": true} 408 ] 410 5. Representing Annotations in DSDL Schemas 412 RFC 6110 [4] defines a standard mapping of YANG data models to 413 Document Schema Definition Languages (DSDL) [9]. This section 414 specifies the mapping for the extension statement "md:annotation" 415 (Section 6), which enables validation of XML instance documents 416 containing metadata annotations. 418 The first step of the DSDL mapping procedure, i.e., the 419 transformation of the YANG data model to the hybrid schema (see 420 sec. 6 in [4]), is modified as follows: 422 1. If the data model contains at least one "md:annotation" 423 statement, then a RELAX NG named pattern definition MUST be added 424 a child of the root element in the hybrid schema. 425 It is RECOMMENDED to use the name "__yang_metadata__" for this 426 named pattern. 428 2. A reference to the named pattern described in item 1 MUST be 429 included as a child of every pattern that 430 corresponds to a container, leaf, list or leaf-list data node. 432 3. Every metadata annotation definition in the form 434 md:annotation ARGUMENT; 436 or 438 md:annotation ARGUMENT { 439 ... 440 } 442 is mapped to the following RELAX NG pattern: 444 445 ... 446 448 where PREFIX is the namespace prefix bound to the namespace URI 449 of the YANG module that contains the "md:annotation" statement. 450 The "rng:attribute" pattern SHALL be inserted as a child of the 451 named pattern definition described in item 1. 453 4. Substatements of "md:annotation", if there are any, SHALL be 454 mapped to children of the "rng:attribute" pattern exactly as 455 described in sec. 10 of [4]. 457 For example, the named pattern definition (item 1), when constructed 458 only for the "inactive" annotation, will have the following form: 460 461 462 463 true 464 false 465 466 467 469 Every "rng:element" pattern that corresponds to a container, leaf, 470 list or leaf-list data node will then contain a reference to the 471 above named pattern, for example 472 473 474 ... 475 477 Note that it is not necessary to use such a reference for 478 "rng:element" patterns corresponding to anyxml data nodes because 479 they already permit any XML attributes to be attached to their 480 instances. 482 The second step of the DSDL mapping procedure, i.e., the 483 transformation of the hybrid schema to RELAX NG, Schematron and DSRL 484 schemas, is unaffected by the inclusion of "md:annotation". 486 6. Metadata YANG Module 488 RFC Ed.: In this section, replace all occurrences of 'XXXX' with the 489 actual RFC number and all occurrences of the revision date below with 490 the date of RFC publication (and remove this note). 492 file "yang-metadata@2014-09-11.yang" 494 module ietf-yang-metadata { 496 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-metadata"; 498 prefix "md"; 500 organization 501 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 503 contact 504 "Editor: Ladislav Lhotka 505 "; 507 description 508 "This YANG module defines an extension statement that allows for 509 defining metadata annotations."; 511 revision 2014-09-11 { 512 description 513 "Initial revision."; 514 reference 515 "RFC XXXX: Defining and Using Metadata with YANG"; 516 } 518 extension annotation { 519 argument name; 520 description 521 "This extension allows for defining metadata annotations in 522 YANG modules. The 'md:annotation' statement can appear only at 523 the top level of a YANG module. 525 An annotation defined with this extension statement inherits 526 the namespace and other context from the YANG module in which 527 it is defined. 529 Other properties of the annotation and documentation may be 530 specified using the following standard YANG substatements (all 531 are optional and may appear only once): 'type', 'description', 532 'reference', 'status' and 'units'. If the 'type' statement is 533 not present, the built-in 'string' type is used by default. 535 A server announces support for a particular annotation by 536 including the module in which the annotation is defined among 537 the advertised YANG modules (e.g. in NETCONF hello message). 538 Depending on the prescribed usage patterns, the annotation 539 then may be attached by the server and/or client to any valid 540 instance of a data node defined by the server's data model. 542 XML and JSON encoding of annotations is defined in 543 RFC XXXX."; 544 } 545 } 547 549 7. IANA Considerations 551 RFC Ed.: In this section, replace all occurrences of 'XXXX' with the 552 actual RFC number (and remove this note). 554 This document registers the following namespace URI in the IETF XML 555 registry [2]: 557 ---------------------------------------------------------- 558 URI: urn:ietf:params:xml:ns:yang:ietf-yang-metadata 560 Registrant Contact: The IESG. 562 XML: N/A, the requested URI is an XML namespace. 563 ---------------------------------------------------------- 565 This document registers the following YANG module in the YANG Module 566 Names registry [3]: 568 ------------------------------------------------------------------- 569 name: ietf-yang-metadata 570 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-metadata 571 prefix: md 572 reference: RFC XXXX 573 ------------------------------------------------------------------- 575 8. Security Considerations 577 This document introduces a mechanism for defining metadata 578 annotations in YANG modules and using them with instances of YANG 579 data nodes. By itself, this mechanism represents no security threat. 580 Security implications of a particular annotation defined using this 581 mechanism have to be duly considered and documented. 583 9. References 585 9.1. Normative References 587 [1] Bradner, S., "Key words for use in RFCs to Indicate 588 Requirement Levels", BCP 14, RFC 2119, March 1997. 590 [2] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 591 January 2004. 593 [3] Bjorklund, M., "YANG - A Data Modeling Language for the 594 Network Configuration Protocol (NETCONF)", RFC 6020, 595 October 2010. 597 [4] Lhotka, L., "Mapping YANG to Document Schema Definition 598 Languages and Validating NETCONF Content", RFC 6110, 599 February 2011. 601 [5] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 602 Bierman, "Network Configuration Protocol (NETCONF)", RFC 603 6241, June 2011. 605 [6] Bray, T., "The JavaScript Object Notation (JSON) Data 606 Interchange Format", RFC 7159, March 2014. 608 [7] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 609 draft-ietf-netmod-yang-json-00 (work in progress), April 610 2014. 612 [8] Cowan, J. and R. Tobin, "XML Information Set (Second 613 Edition)", World Wide Web Consortium Recommendation REC- 614 xml-infoset-20040204, February 2004, 615 . 617 9.2. Informative References 619 [9] International Organization for Standardization, "Document 620 Schema Definition Languages (DSDL) - Part 1: Overview", 621 ISO/IEC 19757-1, November 2004. 623 [10] Bierman, A., Bjorklund, M., Watsen, K., and R. Fernando, 624 "RESTCONF Protocol", draft-ietf-netconf-restconf-01 (work 625 in progress), July 2014. 627 Author's Address 629 Ladislav Lhotka 630 CZ.NIC 632 Email: lhotka@nic.cz