--- 1/draft-ietf-netmod-yang-metadata-06.txt 2016-03-21 14:22:20.508195956 -0700 +++ 2/draft-ietf-netmod-yang-metadata-07.txt 2016-03-21 14:22:20.560197247 -0700 @@ -1,19 +1,19 @@ NETMOD Working Group L. Lhotka Internet-Draft CZ.NIC -Updates: 6110 (if approved) March 11, 2016 +Updates: 6110 (if approved) March 21, 2016 Intended status: Standards Track -Expires: September 12, 2016 +Expires: September 22, 2016 Defining and Using Metadata with YANG - draft-ietf-netmod-yang-metadata-06 + draft-ietf-netmod-yang-metadata-07 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 @@ -23,42 +23,42 @@ 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 September 12, 2016. + This Internet-Draft will expire on September 22, 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 carefully, as they describe your rights and restrictions with respect 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.1. Keywords . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Terms Defined in Other Documents . . . . . . . . . . . . 5 2.3. Namespaces and Prefixes . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . . . . . . 10 5.2.1. Metadata Object and Annotations . . . . . . . . . . . 10 @@ -68,29 +68,30 @@ 5.2.4. Adding Annotations to Leaf-list Entries . . . . . . . 12 6. Representing Annotations in DSDL Schemas . . . . . . . . . . 13 7. Metadata YANG Module . . . . . . . . . . . . . . . . . . . . 14 8. IANA 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 . . . . . . . . . . . . . . . . . . . . . 19 - A.1. Changes Between Revisions -05 and -06 . . . . . . . . . . 19 - A.2. Changes Between Revisions -04 and -05 . . . . . . . . . . 19 - A.3. Changes Between Revisions -03 and -04 . . . . . . . . . . 19 - A.4. Changes Between Revisions -02 and -03 . . . . . . . . . . 19 - A.5. Changes Between Revisions -01 and -02 . . . . . . . . . . 19 - A.6. Changes Between Revisions -00 and -01 . . . . . . . . . . 20 - A.7. Changes Between draft-lhotka-netmod-yang-metadata-01 and + A.1. Changes Between Revisions -06 and -07 . . . . . . . . . . 19 + A.2. Changes Between Revisions -05 and -06 . . . . . . . . . . 19 + A.3. Changes Between Revisions -04 and -05 . . . . . . . . . . 19 + A.4. Changes Between Revisions -03 and -04 . . . . . . . . . . 19 + A.5. Changes Between Revisions -02 and -03 . . . . . . . . . . 19 + A.6. Changes Between Revisions -01 and -02 . . . . . . . . . . 19 + A.7. Changes Between Revisions -00 and -01 . . . . . . . . . . 20 + A.8. Changes Between draft-lhotka-netmod-yang-metadata-01 and draft-ietf-netmod-yang-metadata-00 . . . . . . . . . . . 20 - A.8. Changes Between draft-lhotka-netmod-yang-metadata-00 and + A.9. 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- @@ -641,21 +640,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-03-11.yang" + file "ietf-yang-metadata@2016-03-21.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"; @@ -686,21 +685,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-03-11 { + revision 2016-03-21 { 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 @@ -770,21 +769,23 @@ This document introduces a mechanism for defining metadata annotations in YANG modules and attaching them to instances of YANG data nodes. By itself, this mechanism represents no security threat. Security implications of a particular annotation defined using this mechanism MUST be duly considered and documented in the the annotation's definition. An annotation SHOULD be subject to the same or stricter access control rules as the data node instance to which the annotation is - attached. + attached. It is RECOMMENDED that security-sensitive or privacy- + sensitive data be modeled as regular YANG data nodes rather than + annotations. 10. Acknowledgments The author wishes to thank Andy Bierman, Martin Bjorklund, Benoit Claise, Juergen Schoenwaelder, and Kent Watsen for their helpful comments and suggestions. 11. References 11.1. Normative References @@ -837,57 +838,61 @@ Bray, T., Hollander, D., Layman, A., and R. Tobin, "Namespaces in XML 1.1 (Second Edition)", World Wide Web Consortium Recommendation REC-xml-names11-20060816, August 2006, . 11.2. Informative References [I-D.ietf-netconf-restconf] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF - Protocol", draft-ietf-netconf-restconf-09 (work in - progress), December 2015. + Protocol", draft-ietf-netconf-restconf-10 (work in + progress), March 2016. [ISO.19757-1] International Organization for Standardization, "Document Schema Definition Languages (DSDL) - Part 1: Overview", ISO/IEC 19757-1, November 2004. [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 -05 and -06 +A.1. Changes Between Revisions -06 and -07 + + o Added sentence in Sec. 9 (Stephen Farrell's suggestion). + +A.2. Changes Between Revisions -05 and -06 o Added explanation of why a YANG extension is used rather than a built-in statement. -A.2. Changes Between Revisions -04 and -05 +A.3. Changes Between Revisions -04 and -05 o Clarification regarding the type of an annotation. -A.3. Changes Between Revisions -03 and -04 +A.4. Changes Between Revisions -03 and -04 o Added explanation of what "top level of a module" means. -A.4. Changes Between Revisions -02 and -03 +A.5. 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.5. Changes Between Revisions -01 and -02 +A.6. 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 @@ -895,33 +900,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.6. Changes Between Revisions -00 and -01 +A.7. Changes Between Revisions -00 and -01 o Define JSON encoding for annotations attached to 'anydata' nodes. -A.7. Changes Between draft-lhotka-netmod-yang-metadata-01 and draft- +A.8. 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.8. Changes Between draft-lhotka-netmod-yang-metadata-00 and -01 +A.9. 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".