--- 1/draft-ietf-netmod-yang-metadata-04.txt 2016-03-10 01:16:07.654385645 -0800 +++ 2/draft-ietf-netmod-yang-metadata-05.txt 2016-03-10 01:16:07.694386641 -0800 @@ -1,18 +1,19 @@ NETMOD Working Group L. Lhotka Internet-Draft CZ.NIC -Intended status: Standards Track February 24, 2016 -Expires: August 27, 2016 +Updates: 6110 (if approved) March 10, 2016 +Intended status: Standards Track +Expires: September 11, 2016 Defining and Using Metadata with YANG - draft-ietf-netmod-yang-metadata-04 + draft-ietf-netmod-yang-metadata-05 Abstract This document defines a YANG extension statement that allows for defining metadata annotations in YANG modules. The document also specifies XML and JSON encoding of annotations and other rules for annotating instances of YANG data nodes. Status of This Memo @@ -22,21 +23,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on August 27, 2016. + This Internet-Draft will expire on September 11, 2016. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -44,51 +45,52 @@ to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Keywords . . . . . . . . . . . . . . . . . . . . . . . . 4 - 2.2. Terms Defined in Other Documents . . . . . . . . . . . . 4 + 2.2. Terms Defined in Other Documents . . . . . . . . . . . . 5 2.3. Namespaces and Prefixes . . . . . . . . . . . . . . . . . 6 - 2.4. Definitions of New Terms . . . . . . . . . . . . . . . . 6 - 3. Defining Annotations in YANG . . . . . . . . . . . . . . . . 6 - 3.1. Example Definition . . . . . . . . . . . . . . . . . . . 7 + 2.4. Definitions of New Terms . . . . . . . . . . . . . . . . 7 + 3. Defining Annotations in YANG . . . . . . . . . . . . . . . . 7 + 3.1. Example Definition . . . . . . . . . . . . . . . . . . . 8 4. Using Annotations . . . . . . . . . . . . . . . . . . . . . . 8 5. The Encoding of Annotations . . . . . . . . . . . . . . . . . 9 5.1. XML Encoding . . . . . . . . . . . . . . . . . . . . . . 9 - 5.2. JSON Encoding . . . . . . . . . . . . . . . . . . . . . . 9 + 5.2. JSON Encoding . . . . . . . . . . . . . . . . . . . . . . 10 5.2.1. Metadata Object and Annotations . . . . . . . . . . . 10 5.2.2. Adding Annotations to Anydata, Container and List Entries . . . . . . . . . . . . . . . . . . . . . . . 10 5.2.3. Adding Annotations to Anyxml and Leaf Instances . . . 11 5.2.4. Adding Annotations to Leaf-list Entries . . . . . . . 12 6. Representing Annotations in DSDL Schemas . . . . . . . . . . 12 7. Metadata YANG Module . . . . . . . . . . . . . . . . . . . . 14 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 - 9. Security Considerations . . . . . . . . . . . . . . . . . . . 16 + 9. Security Considerations . . . . . . . . . . . . . . . . . . . 17 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 11.1. Normative References . . . . . . . . . . . . . . . . . . 17 11.2. Informative References . . . . . . . . . . . . . . . . . 18 - Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 18 - A.1. Changes Between Revisions -03 and -04 . . . . . . . . . . 18 - A.2. Changes Between Revisions -02 and -03 . . . . . . . . . . 19 - A.3. Changes Between Revisions -01 and -02 . . . . . . . . . . 19 - A.4. Changes Between Revisions -00 and -01 . . . . . . . . . . 19 - A.5. Changes Between draft-lhotka-netmod-yang-metadata-01 and - draft-ietf-netmod-yang-metadata-00 . . . . . . . . . . . 19 - A.6. Changes Between draft-lhotka-netmod-yang-metadata-00 and - -01 . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 + Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 19 + A.1. Changes Between Revisions -04 and -05 . . . . . . . . . . 19 + A.2. Changes Between Revisions -03 and -04 . . . . . . . . . . 19 + A.3. Changes Between Revisions -02 and -03 . . . . . . . . . . 19 + A.4. Changes Between Revisions -01 and -02 . . . . . . . . . . 19 + A.5. Changes Between Revisions -00 and -01 . . . . . . . . . . 19 + A.6. Changes Between draft-lhotka-netmod-yang-metadata-01 and + draft-ietf-netmod-yang-metadata-00 . . . . . . . . . . . 20 + A.7. Changes Between draft-lhotka-netmod-yang-metadata-00 and + -01 . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20 1. Introduction There is a need to be able to annotate instances of YANG [I-D.ietf-netmod-rfc6020bis] data nodes with metadata. Typical use cases are: o Complementing regular data model information with instance- specific metadata, comments etc. @@ -149,33 +151,43 @@ tools supporting a certain annotation can thus take them into account and modify their behavior accordingly. o Semantics of an annotation are defined in the "description" and "reference" statements. o An annotation can be declared as conditional by using the "if- feature" statement. o Values of annotations are not limited to strings; any YANG built- - in or derived type may be used for them. + in or derived type may be specified for them. In the XML encoding, XML attributes are a natural instrument for attaching annotations to data node instances. This document deliberately adopts some restrictions in order to remain compatible with the XML encoding of YANG data node instances and limitations of XML attributes. Specifically, o annotations are scalar values and cannot be further structured; o annotations cannot be attached to a whole list or leaf-list instance, only to individual list or leaf-list entries. + Due to the rules for YANG extensions (see sec. 6.3.1 in + [I-D.ietf-netmod-rfc6020bis]), annotation definitions posit + relatively weak conformance requirements. The alternative of + introducing a new built-in YANG statement for defining annotations + was considered, but it was seen as a major change to the language + that is inappropriate for YANG 1.1, which was chartered as a + maintenance revision. After evaluating real-life usage of metadata + annotations, it is conceivable that such a new built-in statement + might be added in a future revision of YANG. + 2. Terminology 2.1. Keywords The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2.2. Terms Defined in Other Documents @@ -193,30 +206,32 @@ o server. The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: o action, o anydata, o anyxml, - o data type, + o built-in type, o container, o data model, o data node, o data tree, + o derived type, + o extension, o leaf, o leaf-list, o list, o module, @@ -619,21 +635,21 @@ 7. Metadata YANG Module RFC Editor: In this section, replace all occurrences of 'XXXX' with the actual RFC number and all occurrences of the revision date below with the date of RFC publication (and remove this note). RFC Editor: Also please replace all occurrences of 'RFC 6020bis' with the actual RFC number that will be assigned to [I-D.ietf-netmod-rfc6020bis]. - file "ietf-yang-metadata@2016-02-24.yang" + file "ietf-yang-metadata@2016-03-10.yang" module ietf-yang-metadata { namespace "urn:ietf:params:xml:ns:yang:ietf-yang-metadata"; prefix "md"; organization "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; @@ -664,21 +680,21 @@ without modification, is permitted pursuant to, and subject to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX (http://tools.ietf.org/html/rfcXXXX); see the RFC itself for full legal notices."; - revision 2016-02-24 { + revision 2016-03-10 { description "Initial revision."; reference "RFC XXXX: Defining and Using Metadata with YANG"; } extension annotation { argument name; description "This extension allows for defining metadata annotations in @@ -768,22 +784,22 @@ 11.1. Normative References [I-D.ietf-netmod-rfc6020bis] Bjorklund, M., "The YANG 1.1 Data Modeling Language", draft-ietf-netmod-rfc6020bis-11 (work in progress), February 2016. [I-D.ietf-netmod-yang-json] Lhotka, L., "JSON Encoding of Data Modeled with YANG", - draft-ietf-netmod-yang-json-08 (work in progress), - February 2016. + draft-ietf-netmod-yang-json-09 (work in progress), March + 2016. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . @@ -833,31 +849,36 @@ [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, . Appendix A. Change Log RFC Editor: Remove this section upon publication as an RFC. -A.1. Changes Between Revisions -03 and -04 +A.1. Changes Between Revisions -04 and -05 + + o Added explanation of why a YANG extension is used rather than a + built-in statement. + +A.2. Changes Between Revisions -03 and -04 o Added explanation of what "top level of a module" means. -A.2. Changes Between Revisions -02 and -03 +A.3. Changes Between Revisions -02 and -03 o Section 4 was considerably simplified, also because member names starting with "@" are now permitted by [I-D.ietf-netmod-yang-json]. -A.3. Changes Between Revisions -01 and -02 +A.4. Changes Between Revisions -01 and -02 o The "type" statement became mandatory. o Terminology section was extended. o The annotation "inactive" defined in the example module was replaced with "last-modified" that is supposedly less controversial. o Introduction now states limitation due to XML attribute @@ -865,33 +886,33 @@ o A recommendation was added to define annotations in a module by themselves. o Section "Using Annotations" was added. o An example for "anyxml" was added. o RFC 6241 was moved to informative references. -A.4. Changes Between Revisions -00 and -01 +A.5. Changes Between Revisions -00 and -01 o Define JSON encoding for annotations attached to 'anydata' nodes. -A.5. Changes Between draft-lhotka-netmod-yang-metadata-01 and draft- +A.6. Changes Between draft-lhotka-netmod-yang-metadata-01 and draft- ietf-netmod-yang-metadata-00 o References to RFC 6020 were changed to the 6020bis I-D. o Text about RFC 2119 key words was added to "ietf-yang-metadata" module description. -A.6. Changes Between draft-lhotka-netmod-yang-metadata-00 and -01 +A.7. Changes Between draft-lhotka-netmod-yang-metadata-00 and -01 o Encoding of annotations for anyxml nodes was changed to be the same as for leafs. This was necessary because anyxml value now needn't be an object. o It is stated that "md:annotation" statement defines only the syntax of an annotation. o Allowed "if-feature" as a substatement of "md:annotation".