idnits 2.17.1 draft-lhotka-netmod-yang-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 -- The document date (February 28, 2015) is 3337 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-03 -- Possible downref: Non-RFC (?) normative reference: ref. '8' == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-04 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 February 28, 2015 5 Expires: September 1, 2015 7 Defining and Using Metadata with YANG 8 draft-lhotka-netmod-yang-metadata-01 10 Abstract 12 This document defines a YANG extension statement that allows for 13 defining the syntax of metadata annotions in YANG modules. The 14 document also specifies the XML and JSON encoding of annotations and 15 other rules for annotating 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 September 1, 2015. 34 Copyright Notice 36 Copyright (c) 2015 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 . . . . . . . . . . . . . . . . . 7 55 4.1. XML Encoding . . . . . . . . . . . . . . . . . . . . . . 7 56 4.2. JSON Encoding . . . . . . . . . . . . . . . . . . . . . . 7 57 4.2.1. Metadata Object and Annotations . . . . . . . . . . . 8 58 4.2.2. Adding Annotations to Container and List Instances . 8 59 4.2.3. Adding Annotations to Leaf or Anyxml Instances . . . 9 60 4.2.4. Adding Annotations to Leaf-list Instances . . . . . . 9 61 5. Representing Annotations in DSDL Schemas . . . . . . . . . . 10 62 6. Metadata YANG Module . . . . . . . . . . . . . . . . . . . . 11 63 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 64 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14 65 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 66 9.1. Normative References . . . . . . . . . . . . . . . . . . 14 67 9.2. Informative References . . . . . . . . . . . . . . . . . 15 68 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 15 69 A.1. Changes Between Revisions -00 and -01 . . . . . . . . . . 15 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 72 1. Introduction 74 There is a need to be able to annotate instances of YANG [3] data 75 nodes with metadata. Typical use cases are: 77 o Deactivating a subtree in a configuration datastore while keeping 78 the data in place. 80 o Complementing data model information with instance-specific data. 82 o RPC operations may use metadata annotations for various purposes 83 in both requests and responses. For example, the 84 operation in the NETCONF protocol (see section 7.2 of [5]) uses 85 annotations in the form of XML attributes for identifying the 86 point in the configuration and type of the operation. 88 However, metadata annotations could potentially lead to 89 interoperability problems if they are used in an ad hoc way by 90 different organizations and/or without proper documentation. A sound 91 metadata framework for YANG should therefore satisfy these 92 requirements: 94 1. The set of annotations must be extensible in a distributed manner 95 so as to allow for defining new annotations without running into 96 the risk of collisions with annotations defined and used by 97 others. 99 2. Syntax and semantics of annotations must be documented and the 100 documentation must be easily accessible. 102 3. Clients of network management protocols such as NETCONF [5] or 103 RESTCONF [10] must be able to learn all annotations supported by 104 a given server and identify each of them correctly. 106 This document proposes a systematic way for defining the syntax of 107 metadata annotations. For this purpose, YANG extension statement 108 "annotation" is defined in the module "ietf-yang-metadata" 109 (Section 6). Other YANG modules importing this module can use the 110 "annotation" statement for defining the syntax one or more 111 annotations. 113 Semantics of metadata annotations MUST be defined separately. How it 114 is done is outside the scope of this document. 116 The benefits of defining the syntax of metadata annotations in a YANG 117 module are the following: 119 o Each annotation is bound to a YANG module name, namespace URI and 120 prefix. This makes its encoding in instance documents (both XML 121 and JSON) straightforward and consistent with the encoding of YANG 122 data node instances. 124 o Annotations are indirectly registered through IANA YANG module 125 registration. 127 o Annotations are included in the data model. Specifically, servers 128 indicate syntactic support for certain annotations using standard 129 module advertisement methods, such as the message in 130 NETCONF. 132 o Values of annotations are not limited to strings; any YANG built- 133 in or derived type may be used for them. 135 2. Terminology 137 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 138 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 139 document are to be interpreted as described in [1]. 141 The following terms are defined in [5]: 143 o client, 144 o datastore, 146 o message, 148 o operation, 150 o server. 152 The following terms are defined in [3]: 154 o anyxml, 156 o built-in type, 158 o derived type, 160 o container, 162 o data model, 164 o data node, 166 o derived type, 168 o extension, 170 o leaf-list, 172 o list, 174 o module, 176 o RPC operation, 178 o submodule, 180 o type. 182 The following terms are defined in [8]: 184 o attribute, 186 o document, 188 o element, 190 o namespace, 191 o prefix. 193 The following terms are defined in [6]: 195 o array, 197 o member, 199 o object, 201 o primitive type. 203 In the following text, XML element names and YANG extension 204 statements are always written with explicit namespace prefixes that 205 are assumed to be bound to URI references as shown in Table 1. 207 +--------+------------------------------------------------+ 208 | Prefix | URI Reference | 209 +--------+------------------------------------------------+ 210 | rng | http://relaxng.org/ns/structure/1.0 | 211 | md | urn:ietf:params:xml:ns:yang:ietf-yang-metadata | 212 | ein | http://example.org/example-inactive | 213 +--------+------------------------------------------------+ 215 Table 1: Used namespace prefixes and corresponding URI references 217 3. Defining Annotations in YANG 219 Metadata annotations are defined with YANG extension statement 220 "md:annotation". This YANG language extension is defined in the 221 module "ietf-yang-metadata" (Section 6). 223 Substatements of "md:annotation" are shown in Table 2. They are all 224 core YANG statements, and the numbers in the second column refer to 225 the corresponding sections in RFC 6020 [3] where each statement is 226 described. 228 +--------------+------------------+-------------+ 229 | substatement | RFC 6020 section | cardinality | 230 +--------------+------------------+-------------+ 231 | description | 7.19.3 | 0..1 | 232 | if-feature | 7.18.2 | 0..n | 233 | reference | 7.19.4 | 0..1 | 234 | status | 7.19.2 | 0..1 | 235 | type | 7.6.3 | 0..1 | 236 | units | 7.3.3 | 0..1 | 237 +--------------+------------------+-------------+ 239 Table 2: Substatements of "md:annotation". 241 Using the "type" statement, a type may be specified for the 242 annotation value according to the same rules as for YANG leaf or 243 leaf-list types. However, the "type" statement is optional as a 244 substatement of "md:annotation" statement. If it is not present, the 245 built-in "string" type is the default. 247 The "if-feature" statement, if present, makes the annotation 248 conditional: it is supported only by servers that advertise the 249 corresponding feature. 251 For example, the following module defines the "inactive" annotation: 253 module example-inactive { 254 namespace "http://example.org/example-inactive"; 255 prefix "ein"; 256 import ietf-yang-metadata { 257 prefix "md"; 258 } 259 md:annotation inactive { 260 type boolean; 261 description 262 "If this annotation is attached to a configuration data node, 263 then the data subtree rooted at this node is deactivated."; 264 } 265 } 267 By advertising a YANG module in which metadata annotation X is 268 defined using the "md:annotation" statement, a server specifies just 269 the syntax of annotation X. This means that configuration or state 270 data, RPC messages and notifications will be considered syntactically 271 valid if annotation X is attached to any data node instance, provided 272 that all rules stated in this document are observed. However, the 273 semantics of an annotation including the expected behavior of clients 274 and servers MUST be specified by other means that are outside the 275 scope of this document. 277 4. The Encoding of Annotations 279 XML attributes are a natural choice for encoding metadata in XML 280 instance documents. For JSON [6], there is no generally established 281 method for encoding metadata. This document thus introduces a 282 special encoding method that is consistent with the JSON encoding of 283 YANG data node instances as defined in [7]. 285 4.1. XML Encoding 287 Metadata annotations are added to XML-encoded instances of YANG data 288 nodes as XML attributes according to these rules: 290 o The local name of the attribute SHALL be the same as the name of 291 the annotation specified in the argument of the corresponding 292 "md:annotation" statement. 294 o The namespace of the attribute SHALL be identified by the URI that 295 appears as the argument of the "namespace" statement in the YANG 296 module where the annotation is defined. It is RECOMMENDED that 297 the prefix specified by the "prefix" statement in the same module 298 is used in the qualified name of the attribute. 300 o The attribute value SHALL be encoded in the same way as the value 301 of a YANG leaf instance having the same type. 303 For example, the "inactive" annotation defined in Section 3 may be 304 encoded as follows: 306 308 ... 309 311 4.2. JSON Encoding 313 The JSON metadata encoding defined in this section has the following 314 properties: 316 1. The encoding of YANG data node instances as defined in [7] does 317 not change. 319 2. Namespaces of metadata annotations are encoded in the same way as 320 namespaces of YANG data node instances, see [7]. 322 4.2.1. Metadata Object and Annotations 324 All metadata annotations assigned to a YANG data node instance are 325 encoded as members (name/value pairs) of a single JSON object, 326 henceforth denoted as the metadata object. The placement and name of 327 this object depends on the type of the data node as specified in the 328 following subsections. 330 The name of a metadata annotation (as a member of the metadata 331 object) SHALL be of the following form: 333 MODULE_NAME:LOCAL_NAME 335 where MODULE_NAME is the name of the YANG module in which the 336 annotation is defined, and LOCAL_NAME is the name of the annotation 337 specified in the argument of the corresponding "md:annotation" 338 statement. 340 Note that unlike YANG data node instances, for annotations the 341 explicit namespace identifier (MODULE_NAME) must always be used. 343 The value of a metadata annotation SHALL be encoded in exactly the 344 same way as the value of a YANG leaf node having the same type as the 345 annotation. 347 4.2.2. Adding Annotations to Container and List Instances 349 For an instance that is encoded as a JSON object (i.e., a container 350 or list entry), the metadata object is added as a new member of that 351 object with the name "@". 353 Examples: 355 o "cask" is a container node: 357 "cask": { 358 "@": { 359 "example-inactive:inactive": true 360 }, 361 ... 362 } 364 o "seq" is a list whose key is "name", annotation "inactive" is 365 added only to the first entry: 367 "seq": [ 368 { 369 "@": { 370 "example-inactive:inactive": true 371 }, 372 "name": "one", 373 ... 374 }, 375 { 376 "name": "two", 377 ... 378 } 379 ] 381 4.2.3. Adding Annotations to Leaf or Anyxml Instances 383 For a leaf or anyxml instance, the metadata object is added as a 384 sibling name/value pair whose the name is the symbol "@" concatenated 385 with the name of the leaf or anyxml member that is being annotated. 387 For example, if "flag" is a leaf node of the "boolean" type: 389 "flag": true, 390 "@flag": { 391 "example-inactive:inactive": true 392 } 394 4.2.4. Adding Annotations to Leaf-list Instances 396 For a leaf-list instance, which is represented as a JSON array with 397 values of a primitive type, annotations may be assigned to one or 398 more entries by adding a name/array pair as a sibling the leaf-list 399 instance, where the name is the symbol "@" concatenated with the name 400 of the leaf-list that is being annotated, and the value is a JSON 401 array whose i-th element is the metadata object with annotations 402 assigned to the i-th entry of the leaf-list instance, or null if the 403 i-th entry has no annotations. 405 Trailing null values in the array, i.e., those following the last 406 non-null metadata object, MAY be omitted. 408 For example, in the following leaf-list instance with four entries, 409 the "inactive" annotation is added to the second and third entry in 410 the following way: 412 "bibliomod:folio": [6, 3, 7, 8], 413 "@bibliomod:folio": [ 414 null, 415 {"example-inactive:inactive": true}, 416 {"example-inactive:inactive": true} 417 ] 419 5. Representing Annotations in DSDL Schemas 421 RFC 6110 [4] defines a standard mapping of YANG data models to 422 Document Schema Definition Languages (DSDL) [9]. This section 423 specifies the mapping for the extension statement "md:annotation" 424 (Section 6), which enables validation of XML instance documents 425 containing metadata annotations. 427 The first step of the DSDL mapping procedure, i.e., the 428 transformation of the YANG data model to the hybrid schema (see 429 sec. 6 in [4]), is modified as follows: 431 1. If the data model contains at least one "md:annotation" 432 statement, then a RELAX NG named pattern definition MUST be added 433 as a child of the root element in the hybrid 434 schema. It is RECOMMENDED to use the name "__yang_metadata__" 435 for this named pattern. 437 2. A reference to the named pattern described in item 1 MUST be 438 included as a child of every pattern that 439 corresponds to a container, leaf, list or leaf-list data node. 441 3. Every metadata annotation definition in the form 443 md:annotation ARGUMENT; 445 or 447 md:annotation ARGUMENT { 448 ... 449 } 451 is mapped to the following RELAX NG pattern: 453 454 ... 455 457 where PREFIX is the namespace prefix bound to the namespace URI 458 of the YANG module that contains the "md:annotation" statement. 459 Each "rng:attribute" pattern SHALL be wrapped in the 460 pattern, and this SHALL be inserted as a child of 461 the named pattern definition described in item 1. 463 4. Substatements of "md:annotation", if there are any, SHALL be 464 mapped to children of the "rng:attribute" pattern exactly as 465 described in sec. 10 of [4]. 467 For example, the named pattern definition (item 1), when constructed 468 only for the "inactive" annotation, will have the following form: 470 471 472 473 474 true 475 false 476 477 478 479 481 Every "rng:element" pattern that corresponds to a container, leaf, 482 list or leaf-list data node will then contain a reference to the 483 above named pattern, for example 485 486 487 ... 488 490 Note that it is not necessary to use such a reference for 491 "rng:element" patterns corresponding to anyxml data nodes because 492 they already permit any XML attributes to be attached to their 493 instances. 495 The second step of the DSDL mapping procedure, i.e., the 496 transformation of the hybrid schema to RELAX NG, Schematron and DSRL 497 schemas, is unaffected by the inclusion of "md:annotation". 499 6. Metadata YANG Module 501 RFC Editor: In this section, replace all occurrences of 'XXXX' with 502 the actual RFC number and all occurrences of the revision date below 503 with the date of RFC publication (and remove this note). 505 file "ietf-yang-metadata@2015-02-28.yang" 507 module ietf-yang-metadata { 508 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-metadata"; 510 prefix "md"; 512 organization 513 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 515 contact 516 "WG Web: 517 WG List: 519 WG Chair: Thomas Nadeau 520 522 WG Chair: Juergen Schoenwaelder 523 525 Editor: Ladislav Lhotka 526 "; 528 description 529 "This YANG module defines an extension statement that allows for 530 defining metadata annotations. 532 Copyright (c) 2014 IETF Trust and the persons identified as 533 authors of the code. All rights reserved. 535 Redistribution and use in source and binary forms, with or 536 without modification, is permitted pursuant to, and subject to 537 the license terms contained in, the Simplified BSD License set 538 forth in Section 4.c of the IETF Trust's Legal Provisions 539 Relating to IETF Documents 540 (http://trustee.ietf.org/license-info). 542 This version of this YANG module is part of RFC XXXX; see the 543 RFC itself for full legal notices."; 545 revision 2015-02-28 { 546 description 547 "Initial revision."; 548 reference 549 "RFC XXXX: Defining and Using Metadata with YANG"; 550 } 552 extension annotation { 553 argument name; 554 description 555 "This extension allows for defining metadata annotations in 556 YANG modules. The 'md:annotation' statement can appear only at 557 the top level of a YANG module. 559 An annotation defined with this extension statement inherits 560 the namespace and other context from the YANG module in which 561 it is defined. 563 Other properties of the annotation and documentation may be 564 specified using the following standard YANG substatements (all 565 are optional): 'description', 'if-feature', 'reference', 566 'status', 'type' and 'units'. If the 'type' statement is not 567 present, the built-in 'string' type is used by default. 569 A server announces syntactic support for a particular 570 annotation by including the module in which the annotation is 571 defined among the advertised YANG modules (e.g. in NETCONF 572 hello message). 574 The 'description' and/or 'reference' statements should provide 575 links to the specification of the annotation's semantics. 577 XML and JSON encoding of annotations is defined in 578 RFC XXXX."; 579 } 580 } 582 584 7. IANA Considerations 586 RFC Ed.: In this section, replace all occurrences of 'XXXX' with the 587 actual RFC number (and remove this note). 589 This document registers the following namespace URI in the IETF XML 590 registry [2]: 592 ---------------------------------------------------------- 593 URI: urn:ietf:params:xml:ns:yang:ietf-yang-metadata 595 Registrant Contact: The IESG. 597 XML: N/A, the requested URI is an XML namespace. 598 ---------------------------------------------------------- 600 This document registers the following YANG module in the YANG Module 601 Names registry [3]: 603 ------------------------------------------------------------------- 604 name: ietf-yang-metadata 605 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-metadata 606 prefix: md 607 reference: RFC XXXX 608 ------------------------------------------------------------------- 610 8. Security Considerations 612 This document introduces a mechanism for defining the syntax of 613 metadata annotations in YANG modules and using them with instances of 614 YANG data nodes. By itself, this mechanism represents no security 615 threat. Security implications of a particular annotation defined 616 using this mechanism have to be duly considered and documented in the 617 specification of the annotation's semantics. 619 9. References 621 9.1. Normative References 623 [1] Bradner, S., "Key words for use in RFCs to Indicate 624 Requirement Levels", BCP 14, RFC 2119, March 1997. 626 [2] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 627 January 2004. 629 [3] Bjorklund, M., "YANG - A Data Modeling Language for the 630 Network Configuration Protocol (NETCONF)", RFC 6020, 631 October 2010. 633 [4] Lhotka, L., "Mapping YANG to Document Schema Definition 634 Languages and Validating NETCONF Content", RFC 6110, 635 February 2011. 637 [5] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 638 Bierman, "Network Configuration Protocol (NETCONF)", RFC 639 6241, June 2011. 641 [6] Bray, T., "The JavaScript Object Notation (JSON) Data 642 Interchange Format", RFC 7159, March 2014. 644 [7] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 645 draft-ietf-netmod-yang-json-03 (work in progress), 646 February 2015. 648 [8] Cowan, J. and R. Tobin, "XML Information Set (Second 649 Edition)", World Wide Web Consortium Recommendation REC- 650 xml-infoset-20040204, February 2004, 651 . 653 9.2. Informative References 655 [9] International Organization for Standardization, "Document 656 Schema Definition Languages (DSDL) - Part 1: Overview", 657 ISO/IEC 19757-1, November 2004. 659 [10] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 660 Protocol", draft-ietf-netconf-restconf-04 (work in 661 progress), January 2015. 663 Appendix A. Change Log 665 RFC Editor: Remove this section upon publication as an RFC. 667 A.1. Changes Between Revisions -00 and -01 669 o Encoding of annotations for anyxml nodes was changed to be the 670 same as for leafs. This was necessary because anyxml value now 671 needn't be an object. 673 o It is stated that "md:annotation" statement defines only the 674 syntax of an annotation. 676 o Allowed "if-feature" as a substatement of "md:annotation". 678 Author's Address 680 Ladislav Lhotka 681 CZ.NIC 683 Email: lhotka@nic.cz