idnits 2.17.1 draft-ietf-netconf-yang-library-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 == Line 176 has weird spacing: '...ormance boo...' == Line 180 has weird spacing: '...evision uni...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (January 30, 2015) is 3374 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Intended status: Standards Track M. Bjorklund 5 Expires: August 3, 2015 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 January 30, 2015 10 YANG Module Library 11 draft-ietf-netconf-yang-library-00 13 Abstract 15 This document describes a YANG library, which provides information 16 about all the YANG modules used by a device to represent management 17 and protocol information. A YANG library can be shared by multiple 18 protocols within the same device. Simple caching mechanisms are 19 needed to allow clients to minimize retrieval of this information. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on August 3, 2015. 38 Copyright Notice 40 Copyright (c) 2015 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1.3. Terms . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 3 61 2. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 4 62 2.1. modules . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 2.1.1. modules/module . . . . . . . . . . . . . . . . . . . 4 64 2.2. YANG Library Module . . . . . . . . . . . . . . . . . . . 5 65 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 66 3.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 9 67 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 68 5. Normative References . . . . . . . . . . . . . . . . . . . . 9 69 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 10 70 A.1. draft-ietf-netconf-restconf-03 to 00 . . . . . . . . . . 10 71 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 10 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 74 1. Introduction 76 There is a need for standard mechanisms to identify the YANG modules 77 and submodules that are in use by each server that utilizes YANG- 78 based data abstraction. If a large number of YANG modules are 79 utilized by the server, then the YANG library information needed can 80 be relatively large. This information changes very infrequently, so 81 it is important that clients be able to cache the YANG library and 82 easily identify if their cache is out-of-date. 84 YANG library information can be different on every server, and can 85 change at run-time or across a server reboot. Typically firmware 86 upgrades are required to change the set of YANG modules used by a 87 server. 89 The following information is needed by a client application (for each 90 YANG module in the library) to fully utilize the YANG data modeling 91 language. 93 o name: The mandatory YANG module name MUST be unique within a YANG 94 library. All modules and submodules share the same namespace, 95 including modules used for deviations. 97 o revision date: Each YANG module within the library MUST have a 98 revision date. This is derived from the most recent revision 99 statement within the module or submodule. 101 o submodule list: The name and revision date of each submodule used 102 by main module MUST be identified. 104 o feature list: The name of each YANG feature supported by the 105 server MUST be identified. 107 o deviation list: The name of each YANG module used for deviation 108 statements SHOULD be identified. 110 1.1. Terminology 112 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in BCP 115 14, [RFC2119]. 117 1.1.1. NETCONF 119 The following terms are defined in [RFC6241]: 121 o client 123 o server 125 1.1.2. YANG 127 The following terms are defined in [RFC6020]: 129 o module 131 o submodule 133 1.1.3. Terms 135 The following terms are used within this document: 137 o YANG library: a collection of YANG modules and submodules used by 138 a server 140 1.1.4. Tree Diagrams 142 A simplified graphical representation of the data model is used in 143 this document. The meaning of the symbols in these diagrams is as 144 follows: 146 o Brackets "[" and "]" enclose list keys. 148 o Abbreviations before data node names: "rw" means configuration 149 data (read-write) and "ro" state data (read-only). 151 o Symbols after data node names: "?" means an optional node, "!" 152 means a presence container, and "*" denotes a list and leaf-list. 154 o Parentheses enclose choice and case nodes, and case nodes are also 155 marked with a colon (":"). 157 o Ellipsis ("...") stands for contents of subtrees that are not 158 shown. 160 2. YANG Module Library 162 The "ietf-yang-library" module provides information about the YANG 163 library used by a server. 165 YANG Tree Diagram for "ietf-yang-library" module: 167 +--ro modules 168 +--ro module-set-id? string 169 +--ro module* [name revision] 170 +--ro name yang:yang-identifier 171 +--ro revision union 172 +--ro schema? inet:uri 173 +--ro namespace inet:uri 174 +--ro feature* yang:yang-identifier 175 +--ro deviation* yang:yang-identifier 176 +--ro conformance boolean 177 +--ro submodules 178 +--ro submodule* [name revision] 179 +--ro name yang:yang-identifier 180 +--ro revision union 181 +--ro schema? inet:uri 183 2.1. modules 185 This mandatory container holds the identifiers for the YANG data 186 model modules supported by the server. 188 2.1.1. modules/module 190 This mandatory list contains one entry for each YANG data model 191 module supported by the server. There MUST be an instance of this 192 list for every YANG module that is used by the server. 194 2.2. YANG Library Module 196 The "ietf-yang-library" module defines monitoring information for the 197 YANG modules used by a RESTCONF server. 199 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 200 are used by this module for some type definitions. 202 RFC Ed.: update the date below with the date of RFC publication and 203 remove this note. 205 file "ietf-yang-library@2015-01-30.yang" 207 module ietf-yang-library { 208 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library"; 209 prefix "yanglib"; 211 import ietf-yang-types { prefix yang; } 212 import ietf-inet-types { prefix inet; } 214 organization 215 "IETF NETCONF (Network Configuration) Working Group"; 217 contact 218 "WG Web: 219 WG List: 221 WG Chair: Mehmet Ersue 222 224 WG Chair: Mahesh Jethanandani 225 227 Editor: Andy Bierman 228 230 Editor: Martin Bjorklund 231 233 Editor: Kent Watsen 234 "; 236 description 237 "This module contains monitoring information about the YANG 238 modules and submodules that are used within a YANG-based 239 server. 241 Copyright (c) 2015 IETF Trust and the persons identified as 242 authors of the code. All rights reserved. 244 Redistribution and use in source and binary forms, with or 245 without modification, is permitted pursuant to, and subject 246 to the license terms contained in, the Simplified BSD License 247 set forth in Section 4.c of the IETF Trust's Legal Provisions 248 Relating to IETF Documents 249 (http://trustee.ietf.org/license-info). 251 This version of this YANG module is part of RFC XXXX; see 252 the RFC itself for full legal notices."; 254 // RFC Ed.: replace XXXX with actual RFC number and remove this 255 // note. 257 // RFC Ed.: remove this note 258 // Note: extracted from draft-ietf-netconf-yang-library-00.txt 260 // RFC Ed.: update the date below with the date of RFC publication 261 // and remove this note. 262 revision 2015-01-30 { 263 description 264 "Initial revision."; 265 reference 266 "RFC XXXX: YANG Module Library."; 267 } 269 typedef revision-identifier { 270 type string { 271 pattern '\d{4}-\d{2}-\d{2}'; 272 } 273 description 274 "Represents a specific date in YYYY-MM-DD format. 275 TBD: make pattern more precise to exclude leading zeros."; 276 } 278 grouping module { 279 description 280 "The module data structure is represented as a grouping 281 so it can be reused in configuration or another monitoring 282 data structure."; 284 grouping common-leafs { 285 description 286 "Common parameters for YANG modules and submodules."; 288 leaf name { 289 type yang:yang-identifier; 290 description "The YANG module or submodule name."; 291 } 292 leaf revision { 293 type union { 294 type revision-identifier; 295 type string { length 0; } 296 } 297 description 298 "The YANG module or submodule revision date. 299 An empty string is used if no revision statement 300 is present in the YANG module or submodule."; 301 } 302 leaf schema { 303 type inet:uri; 304 description 305 "Contains a URL that represents the YANG schema 306 resource for this module or submodule. 308 This leaf will only be present if there is a URL 309 available for retrieval of the schema for this entry."; 310 } 311 } 313 list module { 314 key "name revision"; 315 description 316 "Each entry represents one module currently 317 supported by the server."; 319 uses common-leafs; 321 leaf namespace { 322 type inet:uri; 323 mandatory true; 324 description 325 "The XML namespace identifier for this module."; 326 } 327 leaf-list feature { 328 type yang:yang-identifier; 329 description 330 "List of YANG feature names from this module that are 331 supported by the server."; 332 } 333 leaf-list deviation { 334 type yang:yang-identifier; 335 description 336 "List of YANG deviation module names used by this 337 server to modify the conformance of the module 338 associated with this entry."; 339 } 340 leaf conformance { 341 type boolean; 342 mandatory true; 343 description 344 "If 'true', then the server is claiming conformance to 345 the YANG module identified in this entry. 347 If 'false', then the server is not claiming any 348 conformance for the YANG module identified by this 349 entry. The module may be needed for reusable definitions 350 such as extensions, features, identifies, typedefs, 351 or groupings."; 352 } 353 container submodules { 354 description 355 "Contains information about all the submodules used 356 by the parent module entry"; 358 list submodule { 359 key "name revision"; 360 description 361 "Each entry represents one submodule within the 362 parent module."; 363 uses common-leafs; 364 } 365 } 366 } // list module 367 } // grouping module 369 container modules { 370 config false; 371 description 372 "Contains YANG module monitoring information."; 374 leaf module-set-id { 375 type string; 376 description 377 "Contains a server-specific identifier representing 378 the current set of modules and submodules. The 379 server MUST change the value of this leaf if the 380 information represented by the 'module' list instances 381 has changed."; 382 } 384 uses module; 386 } 388 } 390 392 3. IANA Considerations 394 3.1. YANG Module Registry 396 This document registers one URI in the IETF XML registry [RFC3688]. 397 Following the format in RFC 3688, the following registration is 398 requested to be made. 400 URI: urn:ietf:params:xml:ns:yang:ietf-yang-library 401 Registrant Contact: The NETMOD WG of the IETF. 402 XML: N/A, the requested URI is an XML namespace. 404 This document registers one YANG module in the YANG Module Names 405 registry [RFC6020]. 407 name: ietf-yang-library 408 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library 409 prefix: yanglib 410 // RFC Ed.: replace XXXX with RFC number and remove this note 411 reference: RFC XXXX 413 4. Security Considerations 415 This section provides security considerations for the information 416 that is defined by the "ietf-yang-library" module. 418 [FIXME: follow template for sec. considerations] 420 5. Normative References 422 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 423 Requirement Levels", BCP 14, RFC 2119, March 1997. 425 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 426 January 2004. 428 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 429 Network Configuration Protocol (NETCONF)", RFC 6020, 430 October 2010. 432 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 433 and A. Bierman, Ed., "Network Configuration Protocol 434 (NETCONF)", RFC 6241, June 2011. 436 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 437 July 2013. 439 Appendix A. Change Log 441 -- RFC Ed.: remove this section before publication. 443 A.1. draft-ietf-netconf-restconf-03 to 00 445 o moved ietf-yang-library from RESTCONF draft to new draft 447 Appendix B. Open Issues 449 -- RFC Ed.: remove this section before publication. 451 o conformance information: should 'conformance' leaf be removed and 452 let real YANG conformance module augment as needed? 454 o multi-protocol: should information be added to identify which 455 protocols use each module or should each protocol define their own 456 augmentations? 458 The YANG Library issue tracker can be found here: 460 https://github.com/netconf-wg/yang-library/issues 462 Authors' Addresses 464 Andy Bierman 465 YumaWorks 467 Email: andy@yumaworks.com 469 Martin Bjorklund 470 Tail-f Systems 472 Email: mbj@tail-f.com 474 Kent Watsen 475 Juniper Networks 477 Email: kwatsen@juniper.net