idnits 2.17.1 draft-rtgyangdt-netmod-module-tags-01.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 455 has weird spacing: '... prefix des...' -- The document date (August 12, 2017) is 2448 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-13 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) == Outdated reference: A later version (-08) exists of draft-ietf-netmod-yang-model-classification-04 Summary: 4 errors (**), 0 flaws (~~), 5 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: February 13, 2018 D. Bogdanovic 7 August 12, 2017 9 YANG Module Tags 10 draft-rtgyangdt-netmod-module-tags-01 12 Abstract 14 This document defines two modules that support the association of 15 tags with modules. Tags may be included in a module or associated 16 with a module through the use of an augmentation to YANG library that 17 is defined in this document. The expectation is for such tags to be 18 used to help classify and organize modules. Tags may be standardized 19 and assigned during module definition; assigned by implementations; 20 or dynamically defined and set by users. This document provides 21 guidance to future model writers and, as such, this document updates 22 [I-D.ietf-netmod-rfc6087bis]. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on February 13, 2018. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 60 3. Tag Locations . . . . . . . . . . . . . . . . . . . . . . . . 3 61 4. Tag Prefixes . . . . . . . . . . . . . . . . . . . . . . . . 3 62 4.1. IETF Standard Tags . . . . . . . . . . . . . . . . . . . 4 63 4.2. Vendor Tags . . . . . . . . . . . . . . . . . . . . . . . 4 64 4.3. Local Tags . . . . . . . . . . . . . . . . . . . . . . . 4 65 4.4. Reserved Tags . . . . . . . . . . . . . . . . . . . . . . 4 66 5. Tag Management . . . . . . . . . . . . . . . . . . . . . . . 4 67 5.1. Module Definition Association . . . . . . . . . . . . . . 4 68 5.2. Implementation Association . . . . . . . . . . . . . . . 4 69 5.3. Administrative Tagging . . . . . . . . . . . . . . . . . 4 70 5.3.1. Resetting Tags . . . . . . . . . . . . . . . . . . . 5 71 6. Tags Module Structure . . . . . . . . . . . . . . . . . . . . 5 72 6.1. Tags Module Tree . . . . . . . . . . . . . . . . . . . . 5 73 6.2. Tags Module . . . . . . . . . . . . . . . . . . . . . . . 5 74 7. Library Augmentation . . . . . . . . . . . . . . . . . . . . 7 75 7.1. Library Augmentation Module . . . . . . . . . . . . . . . 8 76 8. Other Classifications . . . . . . . . . . . . . . . . . . . . 9 77 9. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 9 78 9.1. Include Module Tags . . . . . . . . . . . . . . . . . . . 9 79 9.2. Define Standard Tags . . . . . . . . . . . . . . . . . . 10 80 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 81 10.1. YANG Module Tag Prefix Registry . . . . . . . . . . . . 10 82 10.2. YANG Module IETF Tag Registry . . . . . . . . . . . . . 10 83 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 84 11.1. Normative References . . . . . . . . . . . . . . . . . . 12 85 11.2. Informative References . . . . . . . . . . . . . . . . . 13 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 88 1. Introduction 90 The use of tags for classification and organization is fairly 91 ubiquitous not only within IETF protocols, but in the internet itself 92 (see #hashtags). Tags can be usefully standardized, but they can 93 also serve as a non-standardized mechanism available for users to 94 define themselves. Our solution provides for both cases allowing for 95 the most flexibility. In particular, tags may be standardized and 96 assigned during module definition; assigned by implementations; or 97 dynamically defined and set by users. 99 This document defines two modules that support the association of 100 tags with modules. The first module defines a grouping which 101 contains a list of tags as well as rpc statements for changing the 102 contents of the list. Tags are strings that are structured to enable 103 the differentiation of globally assigned and non-assigned tags based 104 on a fixed prefix. This document also defines an initial set of 105 globally assigned tags. 107 The second module defined in this document defines an augmentation to 108 YANG Library [RFC7895]. It uses (imports) the first module to 109 provide a well known location for tags. 111 Section 9 provides guidelines for authors of YANG data models. This 112 section updates [I-D.ietf-netmod-rfc6087bis]. 114 2. Conventions Used in This Document 116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 118 document are to be interpreted as described in [RFC2119]. 120 Note that lower case versions of these key words are used in section 121 Section 9 where guidance is provided to future document authors. 123 3. Tag Locations 125 Two tag list locations are defined. One location is within the 126 module itself, and the other location is in the yang library under 127 the modules entry. When a module includes tags, the same tag list 128 may also be presented in yang library. 130 To add tags to a module, the module definition includes a tag list 131 using the 'module-tags' grouping defined in this document. This list 132 MUST be added by a module author under container named "module-tags" 133 at the root of their module. 135 4. Tag Prefixes 137 All tags have a prefix indicating who owns their definition. An IANA 138 registry is used to support standardizing tag prefixes. Currently 2 139 prefixes are defined with all others reserved. 141 4.1. IETF Standard Tags 143 An IETF standard tag is a tag that has the prefix "ietf:". All IETF 144 standard tags are registered with IANA in a registry defined later in 145 this document. 147 4.2. Vendor Tags 149 A vendor tag is a tag that has the prefix "vendor:". These tags are 150 defined by the vendor that implements the module, and are not 151 standardized. 153 4.3. Local Tags 155 A local tag is any tag that has the prefix "local:". These tags are 156 defined by the local user/administrator, and will never be 157 standardized. 159 4.4. Reserved Tags 161 Any tag not starting with the prefix "ietf:", "vendor:" or "local:" 162 is reserved for future standardization. 164 5. Tag Management 166 Tags can become associated with a module in a number of ways. Tags 167 may be defined as associated at model design time, at implementation 168 time, or via user administrative control. As the main consumer of 169 tags are users, users may remove any tag, no matter how the tag 170 became associated with a module. 172 5.1. Module Definition Association 174 A module definition SHOULD indicate a set of standard tags to be 175 automatically added by the module implementer. These tags MUST be 176 standard tags (Section 4.1). This does imply that new modules may 177 also drive the addition of new standard tags to the IANA registry. 179 5.2. Implementation Association 181 An implementation MAY include additional tags associated with a 182 module. These tags may be standard or vendor specific tags. 184 5.3. Administrative Tagging 186 Tags can be assigned and removed with normal configuration 187 mechanisms. Additionally we define an RPC to reset a module's tag 188 list to the implementation default. 190 Implementations MUST ensure that a specific module's tags leaf list 191 is consistent across any location from which the list is available. 192 Specifically this includes in the module itself, per Section 9.1, or 193 in yang library, per Section 7. 195 Implementations that do not support the reset rpc statement (whether 196 at all, or just for a particular rpc or module) MUST respond with an 197 YANG transport protocol-appropriate rpc layer error when such a 198 statement is received. 200 5.3.1. Resetting Tags 202 The "reset-tags" rpc statement is defined to reset a module's tag 203 list to the implementation default, i.e. the tags that are present 204 based on module definition and any that are added during 205 implementation time. This rpc statement takes module identification 206 information as input, and provides the list of list of tags that are 207 present after the reset. 209 6. Tags Module Structure 211 6.1. Tags Module Tree 213 The tree associated with the tags module is: 215 module: ietf-module-tags 216 rpcs: 217 +---x reset-tags 218 +---w input 219 | +---w name yang:yang-identifier 220 | +---w revision? union 221 +--ro output 222 +--ro tags* string 224 6.2. Tags Module 226 file "ietf-module-tags@2017-08-12.yang" 227 module ietf-module-tags { 228 yang-version "1.1"; 229 namespace "urn:ietf:params:xml:ns:yang:ietf-module-tags"; 230 prefix "mtags"; 232 import ietf-yang-types { 233 prefix yang; 234 } 236 import ietf-yang-library { 237 prefix yanglib; 239 } 241 // meta 242 organization "IETF NetMod Working Group (NetMod)"; 244 contact 245 "NetMod Working Group - "; 247 description 248 "This module describes a tagging mechanism for yang module. 249 Tags may be IANA assigned or privately defined types."; 251 revision "2017-08-12" { 252 description 253 "Initial revision."; 254 reference "TBD"; 255 } 257 grouping module-tags { 258 description 259 "A grouping that may be used to classify a module."; 261 leaf-list tags { 262 type string; 264 config false; 266 description 267 "The module associated tags. See the IANA 'YANG Module Tag 268 Prefix' registry for reserved prefixes and the IANA 'YANG 269 Module IETF Tag' registry for IETF standard tags"; 270 } 271 } 273 grouping yanglib-common-leafs { 274 description 275 "Common parameters for YANG modules and submodules. 276 This definition extract from RFC7895 as it is defined as 277 a grouping within a grouping. 279 TBD is there a legal way to use a grouping defined wuthin 280 another grouping without using the parent? If so, should change 281 to that."; 283 leaf name { 284 type yang:yang-identifier; 285 mandatory true; 286 description 287 "The YANG module or submodule name."; 288 } 289 leaf revision { 290 type union { 291 type yanglib:revision-identifier; 292 type string { length 0; } 293 } 294 description 295 "The YANG module or submodule revision date. 296 A zero-length string is used if no revision statement 297 is present in the YANG module or submodule."; 298 } 299 } 301 rpc reset-tags { 302 description 303 "Reset a list of tags for a given module to the list of module 304 and implementation time defiend tags. It provides the list of 305 tags associated with the module post reset."; 307 input { 308 uses yanglib-common-leafs; 309 } 311 output { 312 uses module-tags; 313 } 314 } 315 } 316 318 7. Library Augmentation 320 Tags can also be associated with a module using the yang library 321 [RFC7895]. When a server supports both yang library and the 322 augmentation defined below, a user can add, remove and search for 323 tags for any module on the server regardless of whether the specific 324 module included tag support in its definition or not. If a server 325 supports ietf-module-tags and the yang library it SHOULD also support 326 the ietf-library-tags module. 328 The tree associated with the defined augmentation is: 330 module: ietf-library-tags 331 augment /yanglib:modules-state/yanglib:module: 332 +--ro tags* string 334 7.1. Library Augmentation Module 336 file "ietf-library-tags@2017-08-12.yang" 337 module ietf-library-tags { 338 // namespace 339 namespace "urn:ietf:params:xml:ns:yang:ietf-library-tags"; 341 prefix ylibtags; 343 import ietf-yang-library { 344 prefix yanglib; 345 } 346 import ietf-module-tags { 347 prefix mtags; 348 } 350 // meta 351 organization "IETF NetMod Working Group (NetMod)"; 353 contact 354 "NetMod Working Group - "; 356 description 357 "This module augments ietf-yang-library with searchable 358 classfication tags. Tags may be IANA or privately defined 359 types."; 361 revision "2017-08-12" { 362 description 363 "Initial revision."; 364 reference "RFC TBD"; 365 } 367 augment "/yanglib:modules-state/yanglib:module" { 368 description 369 "The yang library structure is augmented with a module tags 370 list. This allows operators to tag modules regardless of 371 whether the modules included tag support or not"; 373 uses mtags:module-tags; 375 } 376 } 377 379 8. Other Classifications 381 It's worth noting that a different yang module classification 382 document exists [I-D.ietf-netmod-yang-model-classification]. That 383 document is classifying modules in only a logical manner and does not 384 define tagging or any other mechanisms. It divides yang modules into 385 2 categories (service or element) and then into one of 3 origins: 386 standard, vendor or user. It does provide a good way to discuss and 387 identify modules in general. This document defines standard tags to 388 support [I-D.ietf-netmod-yang-model-classification] style 389 classification. 391 9. Guidelines to Model Writers 393 This section updates [I-D.ietf-netmod-rfc6087bis]. This document 394 makes two recommendations to model writers, 396 9.1. Include Module Tags 398 The correct way to use the module-tags grouping is to include it in a 399 standard location at the top level of your module, specifically 400 contained within a container named "module-tags". This standard 401 location allows searching module using a well-known xpath wilcard 402 path. For example: 404 module sample-module { 405 ... 406 import ietf-module-tags { 407 prefix mtags; 408 } 409 ... 410 container module-tags { 411 description 412 "A list of classification tags associated with this 413 module. The following predefined tags 414 be included by an implementation: 415 - ietf:foo 416 - ietf:bar 417 - ... 418 "; 419 uses mtags:module-tags; 420 } 421 ... 422 } 424 The associated tree will look like: 426 module: sample-module 427 +--rw module-tags 428 | +--ro tags* string 429 +--... 431 9.2. Define Standard Tags 433 A module should indicate, in the description of the "module-tags" 434 container, the set of tags that are to be populated in the leaf-list 435 for any implementation of the module. This description should also 436 include the appropriate conformance statement or statements, using 437 [RFC2119] language, for each tag. 439 The module writer may use existing standard tags, or use new tags 440 defined in the model definition, as appropriate. New tags should be 441 assigned in the IANA registry defined below, see Section 10.2 below. 443 10. IANA Considerations 445 10.1. YANG Module Tag Prefix Registry 447 This registry allocates tag prefixes. All YANG module tags must 448 begin with one of the prefixes in this registry. 450 The allocation policy for this registry is Specification Required 451 [RFC5226]. 453 The initial values for this registry are as follows. 455 prefix description 456 -------- --------------------------------------------------- 457 ietf: IETF Standard Tag allocated in the IANA YANG Module 458 IETF Tag Registry. 459 vendor: Non-standardized tags allocated by the module implementer. 460 local: Non-standardized tags allocated by and for the user. 462 10.2. YANG Module IETF Tag Registry 464 This registry allocates prefixes that have the standard prefix 465 "ietf:". New values should be well considered and not achievable 466 through a combination of already existing standard tags. 468 The allocation policy for this registry is IETF Review [RFC5226]. 470 The initial values for this registry are as follows. 472 [Editor's note: some of these tags are expected to move to 473 [I-D.ietf-rtgwg-device-model] if/when this document becomes a WG 474 document and that document is refactored to use tags.] 476 +---------------------------------+---------------------+-----------+ 477 | Tag | Description | Reference | 478 +---------------------------------+---------------------+-----------+ 479 | ietf:area:art | Applications and | [This | 480 | | Real-Time Area | document] | 481 | | module. | | 482 | | | | 483 | ietf:area:gen | General Area | [This | 484 | | module. | document] | 485 | | | | 486 | ietf:area:int | Internet Area | [This | 487 | | module. | document] | 488 | | | | 489 | ietf:area:ops | Operations and | [This | 490 | | Management Area | document] | 491 | | module. | | 492 | | | | 493 | ietf:area:rtg | Routing Area | [This | 494 | | module. | document] | 495 | | | | 496 | ietf:area:sec | Security Area | [This | 497 | | module. | document] | 498 | | | | 499 | ietf:area:tsv | Transport Area | [This | 500 | | module. | document] | 501 | | | | 502 | ietf:element | A module for an | [This | 503 | | element (*). | document] | 504 | | | | 505 | ietf:service | A module for a | [This | 506 | | service (*). | document] | 507 | | | | 508 | ietf:hardware | A module for | [This | 509 | | hardware. | document] | 510 | | | | 511 | ietf:software | A module for | [This | 512 | | software. | document] | 513 | | | | 514 | ietf:protocol | A module | [This | 515 | | representing a | document] | 516 | | protocol. | | 517 | | | | 518 | ietf:protocol:system-management | A module | [This | 519 | | representing a | document] | 520 | | system management | | 521 | | protocol. | | 522 | | | | 523 | ietf:protocol:network-service | A module | [This | 524 | | representing a | document] | 525 | | network service | | 526 | | protocol. | | 527 | | | | 528 | ietf:protocol:routing | A module | [This | 529 | | representing a | document] | 530 | | control plane | | 531 | | routing protocol. | | 532 | | | | 533 | ietf:protocol:signaling | A module | [This | 534 | | representing a | document] | 535 | | control plane | | 536 | | signaling protocol. | | 537 | | | | 538 | ietf:protocol:oam | A module | [This | 539 | | representing a | document] | 540 | | Operations, | | 541 | | Administration, and | | 542 | | Maintenance | | 543 | | protocol. | | 544 | | | | 545 | ietf:protocol:lmp | A module | [This | 546 | | representing a link | document] | 547 | | management | | 548 | | protocol. | | 549 | | | | 550 | ietf:protocol:routing:igp | An IGP protocol | [This | 551 | | module. | document] | 552 | | | | 553 | ietf:protocol:routing:egp | An EGP protocol | [This | 554 | | module. | document] | 555 +---------------------------------+---------------------+-----------+ 557 (*) - see [I-D.ietf-netmod-yang-model-classification] 559 Table 1: IETF Module Tag Registry 561 11. References 563 11.1. Normative References 565 [I-D.ietf-netmod-rfc6087bis] 566 Bierman, A., "Guidelines for Authors and Reviewers of YANG 567 Data Model Documents", draft-ietf-netmod-rfc6087bis-13 568 (work in progress), June 2017. 570 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 571 Requirement Levels", BCP 14, RFC 2119, 572 DOI 10.17487/RFC2119, March 1997, 573 . 575 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 576 IANA Considerations Section in RFCs", RFC 5226, 577 DOI 10.17487/RFC5226, May 2008, 578 . 580 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 581 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 582 . 584 11.2. Informative References 586 [I-D.ietf-netmod-yang-model-classification] 587 Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 588 Classification", draft-ietf-netmod-yang-model- 589 classification-04 (work in progress), October 2016. 591 [I-D.ietf-rtgwg-device-model] 592 Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps, 593 "Network Device YANG Logical Organization", draft-ietf- 594 rtgwg-device-model-02 (work in progress), March 2017. 596 Authors' Addresses 598 Christan Hopps 599 Deutsche Telekom 601 Email: chopps@chopps.org 603 Lou Berger 604 LabN Consulting, L.L.C. 606 Email: lberger@labn.net 608 Dean Bogdanovic 610 Email: ivandean@gmail.com