--- 1/draft-ietf-netmod-yang-metadata-00.txt 2015-06-10 02:15:02.915203141 -0700 +++ 2/draft-ietf-netmod-yang-metadata-01.txt 2015-06-10 02:15:02.967204391 -0700 @@ -1,18 +1,18 @@ NETMOD Working Group L. Lhotka Internet-Draft CZ.NIC -Intended status: Standards Track April 16, 2015 -Expires: October 18, 2015 +Intended status: Standards Track June 10, 2015 +Expires: December 12, 2015 Defining and Using Metadata with YANG - draft-ietf-netmod-yang-metadata-00 + draft-ietf-netmod-yang-metadata-01 Abstract This document defines a YANG extension statement that allows for defining syntax of metadata annotions 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 +22,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 October 18, 2015. + This Internet-Draft will expire on December 12, 2015. Copyright Notice Copyright (c) 2015 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 @@ -48,35 +48,37 @@ Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Defining Annotations in YANG . . . . . . . . . . . . . . . . 5 4. The Encoding of Annotations . . . . . . . . . . . . . . . . . 7 4.1. XML Encoding . . . . . . . . . . . . . . . . . . . . . . 7 4.2. JSON Encoding . . . . . . . . . . . . . . . . . . . . . . 7 4.2.1. Metadata Object and Annotations . . . . . . . . . . . 8 - 4.2.2. Adding Annotations to Container and List Instances . 8 + 4.2.2. Adding Annotations to Anydata, Container and List + Instances . . . . . . . . . . . . . . . . . . . . . . 8 4.2.3. Adding Annotations to Anyxml and Leaf Instances . . . 9 4.2.4. Adding Annotations to Leaf-list Instances . . . . . . 9 5. Representing Annotations in DSDL Schemas . . . . . . . . . . 10 6. Metadata YANG Module . . . . . . . . . . . . . . . . . . . . 11 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 10.1. Normative References . . . . . . . . . . . . . . . . . . 14 10.2. Informative References . . . . . . . . . . . . . . . . . 15 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 15 - A.1. Changes Between draft-lhotka-netmod-yang-metadata-01 and + A.1. Changes Between Revisions -00 and -01 . . . . . . . . . . 15 + A.2. Changes Between draft-lhotka-netmod-yang-metadata-01 and draft-ietf-netmod-yang-metadata-00 . . . . . . . . . . . 15 - A.2. Changes Between draft-lhotka-netmod-yang-metadata-00 and + A.3. Changes Between draft-lhotka-netmod-yang-metadata-00 and -01 . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 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 Deactivating a subtree in a configuration datastore while keeping @@ -150,20 +152,22 @@ o datastore, o message, o operation, o server. The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: + o anydata, + o anyxml, o built-in type, o derived type, o container, o data model, @@ -349,25 +352,25 @@ specified in the argument of the corresponding "md:annotation" statement. Note that unlike YANG data node instances, for annotations the explicit namespace identifier (MODULE_NAME) must always be used. The value of a metadata annotation SHALL be encoded in exactly the same way as the value of a YANG leaf node having the same type as the annotation, see [I-D.ietf-netmod-yang-json], sec. 6. -4.2.2. Adding Annotations to Container and List Instances +4.2.2. Adding Annotations to Anydata, Container and List Instances - For an instance that is encoded as a JSON object (i.e., a container - or list entry), the metadata object is added as a new member of that - object with the name "@". + For an instance that is encoded as a JSON object (i.e., a container, + a list entry, or anydata node), the metadata object is added as a new + member of that object with the name "@". Examples: o "cask" is a container node: "cask": { "@": { "example-inactive:inactive": true }, ... @@ -507,21 +510,21 @@ The second step of the DSDL mapping procedure, i.e., the transformation of the hybrid schema to RELAX NG, Schematron and DSRL schemas, is unaffected by the inclusion of "md:annotation". 6. 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). - file "ietf-yang-metadata@2015-04-16.yang" + file "ietf-yang-metadata@2015-06-09.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"; contact @@ -553,21 +556,21 @@ The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in the module text are to be interpreted as described in RFC 2119 (http://tools.ietf.org/html/rfc2119). 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 2015-04-16 { + revision 2015-06-09 { description "Initial revision."; reference "RFC XXXX: Defining and Using Metadata with YANG"; } extension annotation { argument name; description @@ -642,21 +645,21 @@ The author wishes to thank Andy Bierman, Martin Bjorklund and Kent Watsen for their helpful comments and suggestions. 10. References 10.1. Normative References [I-D.ietf-netmod-rfc6020bis] Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", draft-ietf- - netmod-rfc6020bis-04 (work in progress), March 2015. + netmod-rfc6020bis-05 (work in progress), May 2015. [I-D.ietf-netmod-yang-json] Lhotka, L., "JSON Encoding of Data Modeled with YANG", draft-ietf-netmod-yang-json-03 (work in progress), February 2015. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, @@ -676,41 +679,45 @@ [W3C.REC-xml-infoset-20040204] Cowan, J. and R. Tobin, "XML Information Set (Second Edition)", World Wide Web Consortium Recommendation REC- xml-infoset-20040204, February 2004, . 10.2. Informative References [I-D.ietf-netconf-restconf] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF - Protocol", draft-ietf-netconf-restconf-04 (work in - progress), January 2015. + Protocol", draft-ietf-netconf-restconf-05 (work in + progress), June 2015. [ISO.19757-1] International Organization for Standardization, "Document Schema Definition Languages (DSDL) - Part 1: Overview", ISO/IEC 19757-1, November 2004. Appendix A. Change Log RFC Editor: Remove this section upon publication as an RFC. -A.1. Changes Between draft-lhotka-netmod-yang-metadata-01 and draft- +A.1. Changes Between Revisions -00 and -01 + + o Define JSON encoding for annotations attached to 'anydata' nodes. + +A.2. Changes Between draft-lhotka-netmod-yang-metadata-01 and draft- ietf-netmod-yang-metadata-00 o References to RFC 6020 were changed to the 6021bis I-D. o Text about RFC 2119 key words was added to "ietf-yang-metadata" module description. -A.2. Changes Between draft-lhotka-netmod-yang-metadata-00 and -01 +A.3. 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".