idnits 2.17.1 draft-rtgyangdt-netmod-module-tags-02.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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The abstract seems to contain references ([I-D.ietf-netmod-RFC6087bis]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == The 'Updates: ' line in the draft header should list only the _numbers_ of the RFCs which will be updated by this document (if approved); it should not include the word 'RFC' in the list. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 438 has weird spacing: '... prefix des...' -- The document date (October 24, 2017) is 2369 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 (-20) exists of draft-ietf-netmod-rfc6087bis-14 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) ** Downref: Normative reference to an Informational RFC: RFC 8199 Summary: 5 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 C. Hopps 3 Internet-Draft Deutsche Telekom 4 Updates: rfc6087bis (if approved) L. Berger 5 Intended status: Standards Track LabN Consulting, L.L.C. 6 Expires: April 27, 2018 D. Bogdanovic 7 October 24, 2017 9 YANG Module Tags 10 draft-rtgyangdt-netmod-module-tags-02 12 Abstract 14 This document provides for the association of tags with YANG modules. 15 The expectation is for such tags to be used to help classify and 16 organize modules. A method for defining, reading and writing a 17 modules tags is provided, as well as an augmentation to YANG library. 18 Tags may be standardized and assigned during module definition; 19 assigned by implementations; or dynamically defined and set by users. 20 This document provides guidance to future model writers and, as such, 21 this document updates [I-D.ietf-netmod-rfc6087bis]. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on April 27, 2018. 40 Copyright Notice 42 Copyright (c) 2017 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 59 3. Tag Locations . . . . . . . . . . . . . . . . . . . . . . . . 3 60 4. Tag Prefixes . . . . . . . . . . . . . . . . . . . . . . . . 3 61 4.1. IETF Standard Tags . . . . . . . . . . . . . . . . . . . 3 62 4.2. Vendor Tags . . . . . . . . . . . . . . . . . . . . . . . 3 63 4.3. Local Tags . . . . . . . . . . . . . . . . . . . . . . . 4 64 4.4. Reserved Tags . . . . . . . . . . . . . . . . . . . . . . 4 65 5. Tag Management . . . . . . . . . . . . . . . . . . . . . . . 4 66 5.1. Module Definition Association . . . . . . . . . . . . . . 4 67 5.2. Implementation Association . . . . . . . . . . . . . . . 4 68 5.3. Administrative Tagging . . . . . . . . . . . . . . . . . 4 69 5.3.1. Resetting Tags . . . . . . . . . . . . . . . . . . . 5 70 6. Tags Module Structure . . . . . . . . . . . . . . . . . . . . 5 71 6.1. Tags Module Tree . . . . . . . . . . . . . . . . . . . . 5 72 6.2. Tags Module . . . . . . . . . . . . . . . . . . . . . . . 5 73 7. Library Augmentation . . . . . . . . . . . . . . . . . . . . 7 74 7.1. Library Augmentation Module . . . . . . . . . . . . . . . 8 75 8. Other Classifications . . . . . . . . . . . . . . . . . . . . 9 76 9. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 9 77 9.1. Define Standard Tags . . . . . . . . . . . . . . . . . . 9 78 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 79 10.1. YANG Module Tag Prefix Registry . . . . . . . . . . . . 10 80 10.2. YANG Module IETF Tag Registry . . . . . . . . . . . . . 10 81 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 82 11.1. Normative References . . . . . . . . . . . . . . . . . . 12 83 11.2. Informative References . . . . . . . . . . . . . . . . . 12 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 86 1. Introduction 88 The use of tags for classification and organization is fairly 89 ubiquitous not only within IETF protocols, but in the internet itself 90 (e.g., #hashtags). Tags can be usefully standardized, but they can 91 also serve as a non-standardized mechanism available for users to 92 define themselves. Our solution provides for both cases allowing for 93 the most flexibility. In particular, tags may be standardized as 94 well as assigned during module definition; assigned by 95 implementations; or dynamically defined and set by users. 97 This document defines two modules. The first module defines a list 98 of module entries to allow for adding or removing of tags. It also 99 defines an RPC to reset a modules tags to the original values. The 100 second module defines an augmentation to YANG Library [RFC7895] to 101 allow for reading a modules tags. 103 This document also defines an IANA registry for tag prefixes as well 104 as a set of globally assigned tags. 106 Section 9 provides guidelines for authors of YANG data models. This 107 section updates [I-D.ietf-netmod-rfc6087bis]. 109 2. Conventions Used in This Document 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in [RFC2119]. 115 Note that lower case versions of these key words are used in section 116 Section 9 where guidance is provided to future document authors. 118 3. Tag Locations 120 Each module has only one logical tag list; however, that tag list may 121 be accessed from multiple locations. 123 We define two tag list locations. The first location is used for 124 configuration and is a top level list of module entries where each 125 entry contain the list of tags. The second read-only location is 126 through the yang library under the module entry. 128 4. Tag Prefixes 130 All tags have a prefix indicating who owns their definition. An IANA 131 registry is used to support standardizing tag prefixes. Currently 3 132 prefixes are defined with all others reserved. 134 4.1. IETF Standard Tags 136 An IETF standard tag is a tag that has the prefix "ietf:". All IETF 137 standard tags are registered with IANA in a registry defined later in 138 this document. 140 4.2. Vendor Tags 142 A vendor tag is a tag that has the prefix "vendor:". These tags are 143 defined by the vendor that implements the module, and are not 144 standardized; however, it is recommended that the vendor consider 145 including extra identification in the tag name to avoid collisions 146 (e.g., vendor:super-duper-company:...). 148 4.3. Local Tags 150 A local tag is any tag that has the prefix "local:". These tags are 151 defined by the local user/administrator and will never be 152 standardized. 154 4.4. Reserved Tags 156 Any tag not starting with the prefix "ietf:", "vendor:" or "local:" 157 is reserved for future standardization. 159 5. Tag Management 161 Tags can become associated with a module in a number of ways. Tags 162 may be defined and associated at model design time, at implementation 163 time, or via user administrative control. As the main consumer of 164 tags are users, users may also remove any tag, no matter how the tag 165 became associated with a module. 167 5.1. Module Definition Association 169 A module definition SHOULD indicate a set of tags to be automatically 170 added by the module implementer. These tags MUST be standard tags 171 (Section 4.1). This does imply that new modules may also drive the 172 addition of new standard tags to the IANA registry. 174 5.2. Implementation Association 176 An implementation MAY include additional tags associated with a 177 module. These tags may be standard or vendor specific tags. 179 5.3. Administrative Tagging 181 Tags of any kind can be assigned and removed with normal 182 configuration mechanisms. Additionally we define an RPC to reset a 183 module's tag list to the implementation default. 185 Implementations MUST ensure that a modules tag list is consistent 186 across any location from which the list is accessible. So if a user 187 adds a tag through configuration that tag should also be seen when 188 using the yang library augmentation. 190 Implementations that do not support the reset rpc statement (whether 191 at all, or just for a particular rpc or module) MUST respond with an 192 YANG transport protocol-appropriate rpc layer error when such a 193 statement is received. 195 5.3.1. Resetting Tags 197 The "reset-tags" rpc statement is defined to reset a module's tag 198 list to the implementation default, i.e. the tags that are present 199 based on module definition and any that are added during 200 implementation time. This rpc statement takes module identification 201 information as input, and provides the list of tags that are present 202 after the reset. 204 6. Tags Module Structure 206 6.1. Tags Module Tree 208 The tree associated with the tags module is: 210 module: ietf-module-tags 211 rpcs: 212 +---x reset-tags 213 +---w input 214 | +---w name yang:yang-identifier 215 | +---w revision? union 216 +--ro output 217 +--ro tags* string 219 6.2. Tags Module 221 file "ietf-module-tags@2017-10-25.yang" 222 module ietf-module-tags { 223 yang-version "1"; 224 namespace "urn:ietf:params:xml:ns:yang:ietf-module-tags"; 225 prefix "mtags"; 227 import ietf-yang-types { 228 prefix yang; 229 } 231 import ietf-yang-library { 232 prefix yanglib; 233 } 235 // meta 236 organization "IETF NetMod Working Group (NetMod)"; 238 contact 239 "NetMod Working Group - "; 241 description 242 "This module describes a tagging mechanism for yang module. 243 Tags may be IANA assigned or privately defined types."; 245 revision "2017-10-25" { 246 description 247 "Initial revision."; 248 reference "TBD"; 249 } 251 grouping module-tags { 252 description 253 "A grouping that may be used to classify a module."; 255 leaf-list tags { 256 type string; 258 description 259 "The module associated tags. See the IANA 'YANG Module Tag 260 Prefix' registry for reserved prefixes and the IANA 'YANG 261 Module IETF Tag' registry for IETF standard tags"; 262 } 263 } 265 grouping yanglib-common-leafs { 266 description 267 "Common parameters for YANG modules and submodules. 268 This definition extract from RFC7895 as it is defined as 269 a grouping within a grouping. 271 TBD is there a legal way to use a grouping defined within 272 another grouping without using the parent? If so, should change 273 to that."; 275 leaf name { 276 type yang:yang-identifier; 277 mandatory true; 278 description 279 "The YANG module or submodule name."; 280 } 281 leaf revision { 282 type union { 283 type yanglib:revision-identifier; 284 type string { length 0; } 285 } 286 mandatory true; 287 description 288 "The YANG module or submodule revision date. 290 A zero-length string is used if no revision statement 291 is present in the YANG module or submodule."; 292 } 293 } 295 list module-tags { 296 key "name revision"; 297 description 298 "A list of modules and their tags"; 299 uses yanglib-common-leafs; // uses yanglib:common-leafs; 300 uses module-tags; 301 } 303 rpc reset-tags { 304 description 305 "Reset a list of tags for a given module to the list of module 306 and implementation time defiend tags. It provides the list of 307 tags associated with the module post reset."; 309 input { 310 uses yanglib-common-leafs; // uses yanglib:common-leafs; 311 } 313 output { 314 uses module-tags; 315 } 316 } 317 } 318 320 7. Library Augmentation 322 A modules tags can also be read using the yang library [RFC7895] if a 323 server supports both YANG library and the augmentation defined below. 324 If a server supports ietf-module-tags and the YANG library it SHOULD 325 also support the ietf-library-tags module. 327 The tree associated with the defined augmentation is: 329 module: ietf-library-tags 330 augment /yanglib:modules-state/yanglib:module: 331 +--ro tags* string 333 7.1. Library Augmentation Module 335 file "ietf-library-tags@2017-08-12.yang" 336 module ietf-library-tags { 337 // namespace 338 namespace "urn:ietf:params:xml:ns:yang:ietf-library-tags"; 340 prefix ylibtags; 342 import ietf-yang-library { 343 prefix yanglib; 344 } 345 import ietf-module-tags { 346 prefix mtags; 347 } 349 // meta 350 organization "IETF NetMod Working Group (NetMod)"; 352 contact 353 "NetMod Working Group - "; 355 description 356 "This module augments ietf-yang-library with searchable 357 classfication tags. Tags may be IANA or privately defined 358 types."; 360 revision "2017-08-12" { 361 description 362 "Initial revision."; 363 reference "RFC TBD"; 364 } 366 augment "/yanglib:modules-state/yanglib:module" { 367 description 368 "The yang library structure is augmented with a module tags 369 list. This allows operators to tag modules regardless of 370 whether the modules included tag support or not"; 372 uses mtags:module-tags; 374 } 375 } 376 378 8. Other Classifications 380 It's worth noting that a different yang module classification 381 document exists [RFC8199]. That document is classifying modules in 382 only a logical manner and does not define tagging or any other 383 mechanisms. It divides yang modules into 2 categories (service or 384 element) and then into one of 3 origins: standard, vendor or user. 385 It does provide a good way to discuss and identify modules in 386 general. This document defines standard tags to support [RFC8199] 387 style classification. 389 9. Guidelines to Model Writers 391 This section updates [I-D.ietf-netmod-rfc6087bis]. 393 9.1. Define Standard Tags 395 A module SHOULD indicate, in the description statement of the module, 396 a set of tags that are to be associated with it. This description 397 should also include the appropriate conformance statement or 398 statements, using [RFC2119] language for each tag. 400 module sample-module { 401 ... 402 description 403 "[Text describing the module...] 405 RFC TAGS: 406 The following tags MUST be included by an implementation: 407 - ietf:some-required-tag:foo 408 - ... 409 The following tags SHOULD be included by an implementation: 410 - ietf:some-recommended-tag:bar 411 - ... 412 The following tags MAY be included by an implementation: 413 - ietf:some-optional-tag:baz 414 - ... 415 "; 416 ... 417 } 419 One SHOULD only include conformance text if there will be tags listed 420 (i.e., there's no need to indicate an empty set). 422 The module writer may use existing standard tags, or use new tags 423 defined in the model definition, as appropriate. New tags should be 424 assigned in the IANA registry defined below, see Section 10.2 below. 426 10. IANA Considerations 428 10.1. YANG Module Tag Prefix Registry 430 This registry allocates tag prefixes. All YANG module tags SHOULD 431 begin with one of the prefixes in this registry. 433 The allocation policy for this registry is Specification Required 434 [RFC5226]. 436 The initial values for this registry are as follows. 438 prefix description 439 -------- --------------------------------------------------- 440 ietf: IETF Standard Tag allocated in the IANA YANG Module 441 IETF Tag Registry. 442 vendor: Non-standardized tags allocated by the module implementer. 443 local: Non-standardized tags allocated by and for the user. 445 Other SDOs (standard organizations) wishing to standardize their own 446 set of tags could allocate a top level prefix from this registry. 448 10.2. YANG Module IETF Tag Registry 450 This registry allocates prefixes that have the standard prefix 451 "ietf:". New values should be well considered and not achievable 452 through a combination of already existing standard tags. 454 The allocation policy for this registry is IETF Review [RFC5226]. 456 The initial values for this registry are as follows. 458 [Editor's note: many of these tags may move to 459 [I-D.ietf-rtgwg-device-model] if/when that document is refactored to 460 use tags.] 462 +------------------------+------------------------------+-----------+ 463 | Tag | Description | Reference | 464 +------------------------+------------------------------+-----------+ 465 | ietf:rfc8199:element | A module for a network | [RFC8199] | 466 | | element. | | 467 | | | | 468 | ietf:rfc8199:service | A module for a network | [RFC8199] | 469 | | service. | | 470 | | | | 471 | ietf:rfc8199:standard | A module defined by a | [RFC8199] | 472 | | standards organization. | | 473 | | | | 474 | ietf:rfc8199:vendor | A module defined by a | [RFC8199] | 475 | | vendor. | | 476 | | | | 477 | ietf:rfc8199:user | A module defined by the | [RFC8199] | 478 | | user. | | 479 | | | | 480 | ietf:device:hardware | A module relating to device | [This | 481 | | hardware (e.g., inventory). | document] | 482 | | | | 483 | ietf:device:software | A module relating to device | [This | 484 | | software (e.g., installed | document] | 485 | | OS). | | 486 | | | | 487 | ietf:device:qos | A module for managing | [This | 488 | | quality of service. | document] | 489 | | | | 490 | ietf:protocol | A module representing a | [This | 491 | | protocol. | document] | 492 | | | | 493 | ietf:system-management | A module relating to system | [This | 494 | | management (e.g., a system | document] | 495 | | management protocol). | | 496 | | | | 497 | ietf:network-service | A module relating to network | [This | 498 | | service (e.g., a network | document] | 499 | | service protocol). | | 500 | | | | 501 | ietf:oam | A module representing | [This | 502 | | Operations, Administration, | document] | 503 | | and Maintenance. | | 504 | | | | 505 | ietf:routing | A module related to routing. | [This | 506 | | | document] | 507 | | | | 508 | ietf:routing:rib | A module related to routing | [This | 509 | | information bases. | document] | 510 | | | | 511 | ietf:routing:igp | An interior gateway protocol | [This | 512 | | module. | document] | 513 | | | | 514 | ietf:routing:egp | An exterior gateway protocol | [This | 515 | | module. | document] | 516 | | | | 517 | ietf:signaling | A module representing | [This | 518 | | control plane signaling. | document] | 519 | | | | 520 | ietf:lmp | A module representing a link | [This | 521 | | management protocol. | document] | 522 +------------------------+------------------------------+-----------+ 524 Table 1: IETF Module Tag Registry 526 11. References 528 11.1. Normative References 530 [I-D.ietf-netmod-rfc6087bis] 531 Bierman, A., "Guidelines for Authors and Reviewers of YANG 532 Data Model Documents", draft-ietf-netmod-rfc6087bis-14 533 (work in progress), September 2017. 535 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 536 Requirement Levels", BCP 14, RFC 2119, 537 DOI 10.17487/RFC2119, March 1997, 538 . 540 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 541 IANA Considerations Section in RFCs", RFC 5226, 542 DOI 10.17487/RFC5226, May 2008, 543 . 545 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 546 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 547 . 549 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 550 Classification", RFC 8199, DOI 10.17487/RFC8199, July 551 2017, . 553 11.2. Informative References 555 [I-D.ietf-rtgwg-device-model] 556 Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps, 557 "Network Device YANG Logical Organization", draft-ietf- 558 rtgwg-device-model-02 (work in progress), March 2017. 560 Authors' Addresses 562 Christan Hopps 563 Deutsche Telekom 565 Email: chopps@chopps.org 566 Lou Berger 567 LabN Consulting, L.L.C. 569 Email: lberger@labn.net 571 Dean Bogdanovic 573 Email: ivandean@gmail.com