draft-ietf-netmod-yang-metadata-00.txt   draft-ietf-netmod-yang-metadata-01.txt 
NETMOD Working Group L. Lhotka NETMOD Working Group L. Lhotka
Internet-Draft CZ.NIC Internet-Draft CZ.NIC
Intended status: Standards Track April 16, 2015 Intended status: Standards Track June 10, 2015
Expires: October 18, 2015 Expires: December 12, 2015
Defining and Using Metadata with YANG Defining and Using Metadata with YANG
draft-ietf-netmod-yang-metadata-00 draft-ietf-netmod-yang-metadata-01
Abstract Abstract
This document defines a YANG extension statement that allows for This document defines a YANG extension statement that allows for
defining syntax of metadata annotions in YANG modules. The document defining syntax of metadata annotions in YANG modules. The document
also specifies XML and JSON encoding of annotations and other rules also specifies XML and JSON encoding of annotations and other rules
for annotating instances of YANG data nodes. for annotating instances of YANG data nodes.
Status of This Memo Status of This Memo
skipping to change at page 1, line 33 skipping to change at page 1, line 33
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." 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 Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 14 skipping to change at page 2, line 14
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Defining Annotations in YANG . . . . . . . . . . . . . . . . 5 3. Defining Annotations in YANG . . . . . . . . . . . . . . . . 5
4. The Encoding of Annotations . . . . . . . . . . . . . . . . . 7 4. The Encoding of Annotations . . . . . . . . . . . . . . . . . 7
4.1. XML Encoding . . . . . . . . . . . . . . . . . . . . . . 7 4.1. XML Encoding . . . . . . . . . . . . . . . . . . . . . . 7
4.2. JSON Encoding . . . . . . . . . . . . . . . . . . . . . . 7 4.2. JSON Encoding . . . . . . . . . . . . . . . . . . . . . . 7
4.2.1. Metadata Object and Annotations . . . . . . . . . . . 8 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.3. Adding Annotations to Anyxml and Leaf Instances . . . 9
4.2.4. Adding Annotations to Leaf-list Instances . . . . . . 9 4.2.4. Adding Annotations to Leaf-list Instances . . . . . . 9
5. Representing Annotations in DSDL Schemas . . . . . . . . . . 10 5. Representing Annotations in DSDL Schemas . . . . . . . . . . 10
6. Metadata YANG Module . . . . . . . . . . . . . . . . . . . . 11 6. Metadata YANG Module . . . . . . . . . . . . . . . . . . . . 11
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
8. Security Considerations . . . . . . . . . . . . . . . . . . . 14 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
10.1. Normative References . . . . . . . . . . . . . . . . . . 14 10.1. Normative References . . . . . . . . . . . . . . . . . . 14
10.2. Informative References . . . . . . . . . . . . . . . . . 15 10.2. Informative References . . . . . . . . . . . . . . . . . 15
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 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 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 -01 . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction 1. Introduction
There is a need to be able to annotate instances of There is a need to be able to annotate instances of
YANG [I-D.ietf-netmod-rfc6020bis] data nodes with metadata. Typical YANG [I-D.ietf-netmod-rfc6020bis] data nodes with metadata. Typical
use cases are: use cases are:
o Deactivating a subtree in a configuration datastore while keeping o Deactivating a subtree in a configuration datastore while keeping
skipping to change at page 4, line 25 skipping to change at page 4, line 25
o datastore, o datastore,
o message, o message,
o operation, o operation,
o server. o server.
The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: The following terms are defined in [I-D.ietf-netmod-rfc6020bis]:
o anydata,
o anyxml, o anyxml,
o built-in type, o built-in type,
o derived type, o derived type,
o container, o container,
o data model, o data model,
skipping to change at page 8, line 34 skipping to change at page 8, line 34
specified in the argument of the corresponding "md:annotation" specified in the argument of the corresponding "md:annotation"
statement. statement.
Note that unlike YANG data node instances, for annotations the Note that unlike YANG data node instances, for annotations the
explicit namespace identifier (MODULE_NAME) must always be used. explicit namespace identifier (MODULE_NAME) must always be used.
The value of a metadata annotation SHALL be encoded in exactly the 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 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. 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 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 a list entry, or anydata node), the metadata object is added as a new
object with the name "@". member of that object with the name "@".
Examples: Examples:
o "cask" is a container node: o "cask" is a container node:
"cask": { "cask": {
"@": { "@": {
"example-inactive:inactive": true "example-inactive:inactive": true
}, },
... ...
skipping to change at page 11, line 49 skipping to change at page 11, line 49
The second step of the DSDL mapping procedure, i.e., the The second step of the DSDL mapping procedure, i.e., the
transformation of the hybrid schema to RELAX NG, Schematron and DSRL transformation of the hybrid schema to RELAX NG, Schematron and DSRL
schemas, is unaffected by the inclusion of "md:annotation". schemas, is unaffected by the inclusion of "md:annotation".
6. Metadata YANG Module 6. Metadata YANG Module
RFC Editor: In this section, replace all occurrences of 'XXXX' with RFC Editor: In this section, replace all occurrences of 'XXXX' with
the actual RFC number and all occurrences of the revision date below the actual RFC number and all occurrences of the revision date below
with the date of RFC publication (and remove this note). with the date of RFC publication (and remove this note).
<CODE BEGINS> file "ietf-yang-metadata@2015-04-16.yang" <CODE BEGINS> file "ietf-yang-metadata@2015-06-09.yang"
module ietf-yang-metadata { module ietf-yang-metadata {
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-metadata"; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-metadata";
prefix "md"; prefix "md";
organization organization
"IETF NETMOD (NETCONF Data Modeling Language) Working Group"; "IETF NETMOD (NETCONF Data Modeling Language) Working Group";
contact contact
skipping to change at page 12, line 47 skipping to change at page 12, line 47
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and
'OPTIONAL' in the module text are to be interpreted as described 'OPTIONAL' in the module text are to be interpreted as described
in RFC 2119 (http://tools.ietf.org/html/rfc2119). in RFC 2119 (http://tools.ietf.org/html/rfc2119).
This version of this YANG module is part of RFC XXXX This version of this YANG module is part of RFC XXXX
(http://tools.ietf.org/html/rfcXXXX); see the RFC itself for (http://tools.ietf.org/html/rfcXXXX); see the RFC itself for
full legal notices."; full legal notices.";
revision 2015-04-16 { revision 2015-06-09 {
description description
"Initial revision."; "Initial revision.";
reference reference
"RFC XXXX: Defining and Using Metadata with YANG"; "RFC XXXX: Defining and Using Metadata with YANG";
} }
extension annotation { extension annotation {
argument name; argument name;
description description
skipping to change at page 14, line 44 skipping to change at page 14, line 44
The author wishes to thank Andy Bierman, Martin Bjorklund and Kent The author wishes to thank Andy Bierman, Martin Bjorklund and Kent
Watsen for their helpful comments and suggestions. Watsen for their helpful comments and suggestions.
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.ietf-netmod-rfc6020bis] [I-D.ietf-netmod-rfc6020bis]
Bjorklund, M., "YANG - A Data Modeling Language for the Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", draft-ietf- 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] [I-D.ietf-netmod-yang-json]
Lhotka, L., "JSON Encoding of Data Modeled with YANG", Lhotka, L., "JSON Encoding of Data Modeled with YANG",
draft-ietf-netmod-yang-json-03 (work in progress), draft-ietf-netmod-yang-json-03 (work in progress),
February 2015. February 2015.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
skipping to change at page 15, line 29 skipping to change at page 15, line 29
[W3C.REC-xml-infoset-20040204] [W3C.REC-xml-infoset-20040204]
Cowan, J. and R. Tobin, "XML Information Set (Second Cowan, J. and R. Tobin, "XML Information Set (Second
Edition)", World Wide Web Consortium Recommendation REC- Edition)", World Wide Web Consortium Recommendation REC-
xml-infoset-20040204, February 2004, xml-infoset-20040204, February 2004,
<http://www.w3.org/TR/2004/REC-xml-infoset-20040204>. <http://www.w3.org/TR/2004/REC-xml-infoset-20040204>.
10.2. Informative References 10.2. Informative References
[I-D.ietf-netconf-restconf] [I-D.ietf-netconf-restconf]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", draft-ietf-netconf-restconf-04 (work in Protocol", draft-ietf-netconf-restconf-05 (work in
progress), January 2015. progress), June 2015.
[ISO.19757-1] [ISO.19757-1]
International Organization for Standardization, "Document International Organization for Standardization, "Document
Schema Definition Languages (DSDL) - Part 1: Overview", Schema Definition Languages (DSDL) - Part 1: Overview",
ISO/IEC 19757-1, November 2004. ISO/IEC 19757-1, November 2004.
Appendix A. Change Log Appendix A. Change Log
RFC Editor: Remove this section upon publication as an RFC. 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 ietf-netmod-yang-metadata-00
o References to RFC 6020 were changed to the 6021bis I-D. 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" o Text about RFC 2119 key words was added to "ietf-yang-metadata"
module description. 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 o Encoding of annotations for anyxml nodes was changed to be the
same as for leafs. This was necessary because anyxml value now same as for leafs. This was necessary because anyxml value now
needn't be an object. needn't be an object.
o It is stated that "md:annotation" statement defines only the o It is stated that "md:annotation" statement defines only the
syntax of an annotation. syntax of an annotation.
o Allowed "if-feature" as a substatement of "md:annotation". o Allowed "if-feature" as a substatement of "md:annotation".
 End of changes. 15 change blocks. 
18 lines changed or deleted 26 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/