idnits 2.17.1 draft-lhotka-netmod-yang-annotations-00.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 (November 28, 2014) is 3437 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) == Outdated reference: A later version (-01) exists of draft-lhotka-netmod-yang-metadata-00 -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 0 errors (**), 0 flaws (~~), 2 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 November 28, 2014 5 Expires: June 1, 2015 7 Common Metadata Annotations for Data Modelled with YANG 8 draft-lhotka-netmod-yang-annotations-00 10 Abstract 12 This document introduces a collection of common metadata annotations 13 intended for use in data modeled with the YANG language. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on June 1, 2015. 32 Copyright Notice 34 Copyright (c) 2014 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 51 3. Common Metadata Annotations . . . . . . . . . . . . . . . . . 3 52 3.1. The "inactive" Annotation . . . . . . . . . . . . . . . . 3 53 3.2. The "type" Annotation . . . . . . . . . . . . . . . . . . 4 54 4. YANG Annotations Module . . . . . . . . . . . . . . . . . . . 5 55 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 56 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 57 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 58 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 59 7.2. Informative References . . . . . . . . . . . . . . . . . 9 60 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 62 1. Introduction 64 This document introduces a collection of metadata annotations that 65 are intended for general use in data modeled with the YANG data 66 modeling language [RFC6020]. YANG module "ietf-yang-annotations" 67 (Section 4) defines these annotations using the extension statement 68 "annotation" that is defined in the "ietf-yang-metadata" module 69 [I-D.lhotka-netmod-yang-metadata]. 71 2. Terminology 73 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 74 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 75 document are to be interpreted as described in [RFC2119]. 77 The following terms are defined in [RFC6241]: 79 o client, 81 o configuration data, 83 o configuration datastore, 85 o notification, 87 o operation, 89 o RPC method, 91 o server, 93 o state data. 95 3. Common Metadata Annotations 97 YANG module "ietf-yang-annotations" (Section 4) contains normative 98 definitions of the following metadata annotations: 100 o inactive - deactivates a subtree in a configuration datastore, 102 o type - indicates the actual type for a leaf instance with the 103 "union" type". 105 The following subsections provide an informal explanation and 106 examples showing typical use of these annotations. The examples are 107 based on YANG modules "ietf-interfaces" [RFC7223] and "ietf-system" 108 [RFC7317]. 110 3.1. The "inactive" Annotation 112 A client uses the "inactive" annotation for deactivating a subtree in 113 a configuration datastore while keeping the subtree in place. 115 For example, a NETCONF client can use the following 116 operation to deactivate the configuration of an interface in the 117 "running" datastore: 119 121 122 123 124 125 126 129 130 eth0 131 132 133 134 135 137 A RESTCONF client can achieve the same effect with the following HTTP 138 request: 140 PATCH /restconf/data/ietf-interfaces:interfaces/ 141 interface/name=eth0 HTTP/1.1 142 Host: example.com 143 Content-Type: application/yang.data+json 145 { 146 "@": { 147 "ietf-yang-annotations:inactive": true 148 } 149 } 151 3.2. The "type" Annotation 153 Clients and servers use the "type" annotation to specify the actual 154 type for an instance of a leaf that has the "union" type (or a type 155 derived from "union"). The value of this annotation has to be one of 156 the member types appearing in the specification of the "union" type. 158 For example, a NETCONF client can use the following 159 operation to set an IPv6 address of a name server in DNS resolver 160 configuration: 162 164 165 166 167 168 169 172 173 174 primary 175 176
177 2001:db8:0:2::1 178
179 180 181 182 183 184 185 186 A RESTCONF client can perform the same configuration with the 187 following HTTP request: 189 PUT /restconf/data/ietf-system:system/ 190 dns-resolver/server/name=eth0/udp-and-tcp/address HTTP/1.1 191 Host: example.com 192 Content-Type: application/yang.data+json 194 { 195 "@address": { 196 "ietf-yang-annotations:type": "ietf-inet-types:ipv6-address" 197 }, 198 "address": "2001:db8:0:2::1" 199 } 201 4. YANG Annotations Module 203 RFC Editor: In this section, replace all occurrences of 'XXXX' with 204 the actual RFC number and all occurrences of the revision date below 205 with the date of RFC publication (and remove this note). 207 file "yang-annotations@2014-11-28.yang" 209 module ietf-yang-annotations { 211 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-annotations"; 213 prefix "yann"; 215 import ietf-yang-metadata { 216 prefix "md"; 217 } 219 organization 220 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 222 contact 223 "WG Web: 224 WG List: 226 WG Chair: Thomas Nadeau 227 229 WG Chair: Juergen Schoenwaelder 230 232 Editor: Ladislav Lhotka 233 "; 235 description 236 "This module defines generally useful metadata annotations for 237 data modelled with YANG. 239 Copyright (c) 2014 IETF Trust and the persons identified as 240 authors of the code. All rights reserved. 242 Redistribution and use in source and binary forms, with or 243 without modification, is permitted pursuant to, and subject to 244 the license terms contained in, the Simplified BSD License set 245 forth in Section 4.c of the IETF Trust's Legal Provisions 246 Relating to IETF Documents 247 (http://trustee.ietf.org/license-info). 249 This version of this YANG module is part of RFC XXXX; see the 250 RFC itself for full legal notices."; 252 revision 2014-11-28 { 253 description 254 "Initial revision."; 255 reference 256 "RFC XXXX: Common Metadata Annotations for Data Modelled with 257 YANG."; 258 } 260 md:annotation "inactive" { 261 type boolean; 262 description 263 "A client uses this annotation for deactivating a subtree in a 264 configuration datastore. 266 If a server advertises support for this annotation, then a 267 client MAY attach it to any data node instance in any 268 configuration datastore via standard editing methods. If its 269 value is 'true', then the server MUST behave as if the subtree 270 rooted at this data node was not present. If its value is 271 'false' the server MUST behave as if the annotation is not 272 present."; 273 } 275 md:annotation "type" { 276 description 277 "This annotation is used for indicating the actual type for a 278 value of a leaf with the 'union' type, or a type derived from 279 'union' (henceforth denoted as 'a union type'). 281 The value of this annotation can be 282 - the name of a YANG built-in type, 284 - the name of a derived type prepended with the name of the 285 YANG module where the type is defined and the colon 286 character (':'). 288 If a server advertises support for this annotation, then: 290 - A client MAY attach this annotation to a leaf of a union 291 type when creating or modifying the value of this leaf in a 292 configuration datastore, or when such a leaf is contained in 293 RPC request parameters. The server MUST take this 294 information into account when interpreting the type of the 295 received value. 297 - If a client doesn't do so, the server SHOULD attach this 298 annotation to a leaf of a union type upon its creation or 299 modification in a configuration datastore. 301 - The server SHOULD attach this annotation to all leafs of a 302 union type that are sent to a client as state data, in an 303 RPC reply, or in a notification. 305 In all cases mentioned above, the receiving party SHALL ignore 306 this annotation if it is attached to an instance of a data 307 node that is not a leaf of a union type. 309 A server supporting this annotation SHALL report an error if 311 - the type specified in the annotation is not among member 312 types of the annotated leaf's type, 314 - the value of the annotated leaf is not valid for the type 315 specified by the annotation."; 316 } 317 } 319 321 5. IANA Considerations 323 RFC Ed.: In this section, replace all occurrences of 'XXXX' with the 324 actual RFC number (and remove this note). 326 This document registers the following namespace URI in the IETF XML 327 registry [RFC3688]: 329 ---------------------------------------------------------- 330 URI: urn:ietf:params:xml:ns:yang:ietf-yang-annotations 332 Registrant Contact: The IESG. 334 XML: N/A, the requested URI is an XML namespace. 335 ---------------------------------------------------------- 337 This document registers the following YANG modules in the YANG Module 338 Names registry [RFC6020]: 340 ------------------------------------------------------------------- 341 name: ietf-yang-annotations 342 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-annotations 343 prefix: yann 344 reference: RFC XXXX 345 ------------------------------------------------------------------- 347 6. Security Considerations 349 TBD 351 7. References 353 7.1. Normative References 355 [I-D.lhotka-netmod-yang-metadata] 356 Lhotka, L., "Defining and Using Metadata with YANG", 357 draft-lhotka-netmod-yang-metadata-00 (work in progress), 358 September 2014. 360 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 361 Requirement Levels", BCP 14, RFC 2119, March 1997. 363 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 364 January 2004. 366 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 367 Network Configuration Protocol (NETCONF)", RFC 6020, 368 October 2010. 370 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 371 Bierman, "Network Configuration Protocol (NETCONF)", RFC 372 6241, June 2011. 374 7.2. Informative References 376 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 377 Management", RFC 7223, May 2014. 379 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 380 System Management", RFC 7317, August 2014. 382 Author's Address 384 Ladislav Lhotka 385 CZ.NIC 387 Email: lhotka@nic.cz