idnits 2.17.1 draft-rtgyangdt-netmod-module-tags-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 : ---------------------------------------------------------------------------- ** 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 511 has weird spacing: '... prefix des...' -- The document date (February 8, 2017) is 2627 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-10 ** 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 == Outdated reference: A later version (-02) exists of draft-ietf-rtgwg-device-model-01 Summary: 4 errors (**), 0 flaws (~~), 6 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: August 12, 2017 D. Bogdanovic 7 February 8, 2017 9 YANG Module Tags 10 draft-rtgyangdt-netmod-module-tags-00 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 August 12, 2017. 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. Adding Tags . . . . . . . . . . . . . . . . . . . . . 5 71 5.3.2. Removing Tags . . . . . . . . . . . . . . . . . . . . 5 72 5.3.3. Resetting Tags . . . . . . . . . . . . . . . . . . . 5 73 6. Tags Module Structure . . . . . . . . . . . . . . . . . . . . 6 74 6.1. Tags Module Tree . . . . . . . . . . . . . . . . . . . . 6 75 6.2. Tags Module . . . . . . . . . . . . . . . . . . . . . . . 6 76 7. Library Augmentation . . . . . . . . . . . . . . . . . . . . 8 77 7.1. Library Augmentation Module . . . . . . . . . . . . . . . 9 78 8. Other Classifications . . . . . . . . . . . . . . . . . . . . 10 79 9. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 11 80 9.1. Include Module Tags . . . . . . . . . . . . . . . . . . . 11 81 9.2. Define Standard Tags . . . . . . . . . . . . . . . . . . 12 82 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 83 10.1. YANG Module Tag Prefix Registry . . . . . . . . . . . . 12 84 10.2. YANG Module IETF Tag Registry . . . . . . . . . . . . . 12 85 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 86 11.1. Normative References . . . . . . . . . . . . . . . . . . 14 87 11.2. Informative References . . . . . . . . . . . . . . . . . 15 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 90 1. Introduction 92 The use of tags for classification and organization is fairly 93 ubiquitous not only within IETF protocols, but in the internet itself 94 (see #hashtags). Tags can be usefully standardized, but they can 95 also serve as a non-standardized mechanism available for users to 96 define themselves. Our solution provides for both cases allowing for 97 the most flexibility. In particular, tags may be standardized and 98 assigned during module definition; assigned by implementations; or 99 dynamically defined and set by users. 101 This document defines two modules that support the association of 102 tags with modules. The first module defines a grouping which 103 contains a list of tags as well as rpc statements for changing the 104 contents of the list. Tags are strings that are structured to enable 105 the differentiation of globally assigned and non-assigned tags based 106 on a fixed prefix. This document also defines an initial set of 107 globally assigned tags. 109 The second module defined in this document defines an augmentation to 110 YANG Library [RFC7895]. It uses (imports) the first module to 111 provide a well known location for tags. 113 Section 9 provides guidelines for authors of YANG data models. This 114 section updates [I-D.ietf-netmod-rfc6087bis]. 116 2. Conventions Used in This Document 118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 120 document are to be interpreted as described in [RFC2119]. 122 Note that lower case versions of these key words are used in section 123 Section 9 where guidance is provided to future document authors. 125 3. Tag Locations 127 Two tag list locations are defined. One location is within the 128 module itself, and the other location is in the yang library under 129 the modules entry. When a module includes tags, the same tag list 130 may also be presented in yang library. 132 To add tags to a module, the module definition includes a tag list 133 using the 'module-tags' grouping defined in this document. This list 134 MUST be added by a module author under container named "module-tags" 135 at the root of their module. 137 4. Tag Prefixes 139 All tags have a prefix indicating who owns their definition. An IANA 140 registry is used to support standardizing tag prefixes. Currently 2 141 prefixes are defined with all others reserved. 143 4.1. IETF Standard Tags 145 An IETF standard tag is a tag that has the prefix "ietf:". All IETF 146 standard tags are registered with IANA in a registry defined later in 147 this document. 149 4.2. Vendor Tags 151 A vendor tag is a tag that has the prefix "vendor:". These tags are 152 defined by the vendor that implements the module, and are not 153 standardized. 155 4.3. Local Tags 157 A local tag is any tag that has the prefix "local:". These tags are 158 defined by the local user/administrator, and will never be 159 standardized. 161 4.4. Reserved Tags 163 Any tag not starting with the prefix "ietf:", "vendor:" or "local:" 164 is reserved for future standardization. 166 5. Tag Management 168 Tags can become associated with a module in a number of ways. Tags 169 may be defined as associated at model design time, at implementation 170 time, or via user administrative control. As the main consumer of 171 tags are users, users may remove any tag, no matter how the tag 172 became associated with a module. 174 5.1. Module Definition Association 176 A module definition SHOULD indicate a set of standard tags to be 177 automatically added by the module implementer. These tags MUST be 178 standard tags (Section 4.1). This does imply that new modules may 179 also drive the addition of new standard tags to the IANA registry. 181 5.2. Implementation Association 183 An implementation MAY include additional tags associated with a 184 module. These tags may be standard or vendor specific tags. 186 5.3. Administrative Tagging 188 RPC statements are defined in this document to enable administrative 189 addition and removal of tags from a module by a user. An additional 190 rpc is defined to reset a module's tag list to the implementation 191 default. 193 Each rpc identifies the module on which the tag operation is to be 194 performed. This identifications reuses the format of the common- 195 leafs (sub) grouping defined in [RFC7895]. The grouping itself is 196 refined in Section 6 so that it is a stand-alone grouping. 198 Implementations that support the rpc statements defined in this 199 document MUST ensure that a specific module's tags leaf list is 200 consistent across any location from which the list is available. 201 Specifically this includes in the module itself, per Section 9.1, or 202 in yang library, per Section 7. 204 Implementations that do not support the defined rpc statements 205 (whether at all, or just for a particular rpc or module) MUST respond 206 with an YANG transport protocol-appropriate rpc layer error when such 207 a statement is received. 209 5.3.1. Adding Tags 211 The "add-tags" rpc statement is defined to support the addition of 212 tags. This rpc statement takes as input module identification 213 information and the list of tags to add. 215 No restriction is placed on the tag values to add. 217 5.3.2. Removing Tags 219 The "remove-tags" rpc statement is defined to remove tags. This rpc 220 statement takes as input module identification information and the 221 list of tags to remove. 223 No restriction is placed on the tag values to remove. This means 224 that tags associated based on a module's definition or implementation 225 MUST be removable. 227 5.3.3. Resetting Tags 229 The "reset-tags" rpc statement is defined to reset a module's tag 230 list to the implementation default, i.e. the tags that are present 231 based on module definition and any that are added during 232 implementation time. This rpc statement takes module identification 233 information as input, and provides the list of list of tags that are 234 present after the reset. 236 6. Tags Module Structure 238 6.1. Tags Module Tree 240 The tree associated with the tags module is: 242 module: ietf-module-tags 243 rpcs: 244 +---x add-tags 245 | +---w input 246 | +---w name yang:yang-identifier 247 | +---w revision? union 248 | +---w tags* string 249 +---x remove-tags 250 | +---w input 251 | +---w name yang:yang-identifier 252 | +---w revision? union 253 | +---w tags* string 254 +---x reset-tags 255 +---w input 256 | +---w name yang:yang-identifier 257 | +---w revision? union 258 +--ro output 259 +--ro tags* string 261 6.2. Tags Module 263 file "ietf-module-tags@2017-02-08.yang" 264 module ietf-module-tags { 265 yang-version "1.1"; 266 namespace "urn:ietf:params:xml:ns:yang:ietf-module-tags"; 267 prefix "mtags"; 269 import ietf-yang-types { 270 prefix yang; 271 } 273 import ietf-yang-library { 274 prefix yanglib; 275 } 277 // meta 278 organization "IETF NetMod Working Group (NetMod)"; 280 contact 281 "NetMod Working Group - "; 283 description 284 "This module describes a tagging mechanism for yang module. 285 Tags may be IANA assigned or privately defined types."; 287 revision "2017-02-08" { 288 description 289 "Initial revision."; 290 reference "TBD"; 291 } 293 grouping module-tags { 294 description 295 "A grouping that may be used to classify a module."; 297 leaf-list tags { 298 type string; 300 config false; 302 description 303 "The module associated tags. See the IANA 'YANG Module Tag 304 Prefix' registry for reserved prefixes and the IANA 'YANG 305 Module IETF Tag' registry for IETF standard tags"; 306 } 307 } 309 grouping yanglib-common-leafs { 310 description 311 "Common parameters for YANG modules and submodules. 312 This definition extract from RFC7895 as it is defined as 313 a grouping within a grouping. 315 TBD is there a legal way to use a grouping defined wuthin 316 another grouping without using the parent? If so, should change 317 to that."; 319 leaf name { 320 type yang:yang-identifier; 321 mandatory true; 322 description 323 "The YANG module or submodule name."; 324 } 325 leaf revision { 326 type union { 327 type yanglib:revision-identifier; 328 type string { length 0; } 329 } 330 description 331 "The YANG module or submodule revision date. 333 A zero-length string is used if no revision statement 334 is present in the YANG module or submodule."; 335 } 336 } 338 rpc add-tags { 339 description 340 "Add a list of tags to a given module."; 342 input { 343 uses yanglib-common-leafs; 344 uses module-tags; 345 } 346 } 348 rpc remove-tags { 349 description 350 "Remove a list of tags, if present, from a given module."; 352 input { 353 uses yanglib-common-leafs; 354 uses module-tags; 355 } 356 } 358 rpc reset-tags { 359 description 360 "Reset a list of tags for a given module to the list of module 361 and implementation time defiend tags. It provides the list of 362 tags associated with the module post reset."; 364 input { 365 uses yanglib-common-leafs; 366 } 368 output { 369 uses module-tags; 370 } 371 } 372 } 373 375 7. Library Augmentation 377 Tags can also be associated with a module using the yang library 378 [RFC7895]. When a server supports both yang library and the 379 augmentation defined below, a user can add, remove and search for 380 tags for any module on the server regardless of whether the specific 381 module included tag support in its definition or not. If a server 382 supports ietf-module-tags and the yang library it SHOULD also support 383 the ietf-library-tags module. 385 The tree associated with the defined augmentation is: 387 module: ietf-library-tags 388 augment /yanglib:modules-state/yanglib:module: 389 +--ro tags* string 391 7.1. Library Augmentation Module 392 file "ietf-library-tags@2017-02-08.yang" 393 module ietf-library-tags { 394 // namespace 395 namespace "urn:ietf:params:xml:ns:yang:ietf-library-tags"; 397 prefix ylibtags; 399 import ietf-yang-library { 400 prefix yanglib; 401 } 402 import ietf-module-tags { 403 prefix mtags; 404 } 406 // meta 407 organization "IETF NetMod Working Group (NetMod)"; 409 contact 410 "NetMod Working Group - "; 412 description 413 "This module augments ietf-yang-library with searchable 414 classfication tags. Tags may be IANA or privately defined 415 types."; 417 revision "2017-02-06" { 418 description 419 "Initial revision."; 420 reference "RFC TBD"; 421 } 423 augment "/yanglib:modules-state/yanglib:module" { 424 description 425 "The yang library structure is augmented with a module tags 426 list. This allows operators to tag modules regardless of 427 whether the modules included tag support or not"; 429 uses mtags:module-tags; 431 } 432 } 433 435 8. Other Classifications 437 It's worth noting that a different yang module classification 438 document exists [I-D.ietf-netmod-yang-model-classification]. That 439 document is classifying modules in only a logical manner and does not 440 define tagging or any other mechanisms. It divides yang modules into 441 2 categories (service or entity) and then into one of 3 origins: 442 standard, vendor or user. It does provide a good way to discuss and 443 identify modules in general. This document defines standard tags to 444 support [I-D.ietf-netmod-yang-model-classification] style 445 classification. 447 9. Guidelines to Model Writers 449 This section updates [I-D.ietf-netmod-rfc6087bis]. This document 450 makes two recommendations to model writers, 452 9.1. Include Module Tags 454 The correct way to use the module-tags grouping is to include it in a 455 standard location at the top level of your module, specifically 456 contained within a container named "module-tags". This standard 457 location allows searching module using a well-known xpath wilcard 458 path. For example: 460 module sample-module { 461 ... 462 import ietf-module-tags { 463 prefix mtags; 464 } 465 ... 466 container module-tags { 467 description 468 "A list of classification tags associated with this 469 module. The following predefined tags 470 be included by an implementation: 471 - ietf:foo 472 - ietf:bar 473 - ... 474 "; 475 uses mtags:module-tags; 476 } 477 ... 478 } 480 The associated tree will look like: 482 module: sample-module 483 +--rw module-tags 484 | +--ro tags* string 485 +--... 487 9.2. Define Standard Tags 489 A module should indicate, in the description of the "module-tags" 490 container, the set of tags that are to be populated in the leaf-list 491 for any implementation of the module. This description should also 492 include the appropriate conformance statement or statements, using 493 [RFC2119] language, for each tag. 495 The module writer may use existing standard tags, or use new tags 496 defined in the model definition, as appropriate. New tags should be 497 assigned in the IANA registry defined below, see Section 10.2 below. 499 10. IANA Considerations 501 10.1. YANG Module Tag Prefix Registry 503 This registry allocates tag prefixes. All YANG module tags must 504 begin with one of the prefixes in this registry. 506 The allocation policy for this registry is Specification Required 507 [RFC5226]. 509 The initial values for this registry are as follows. 511 prefix description 512 -------- --------------------------------------------------- 513 ietf: IETF Standard Tag allocated in the IANA YANG Module 514 IETF Tag Registry. 515 vendor: Non-standardized tags allocated by the module implementer. 516 local: Non-standardized tags allocated by and for the user. 518 10.2. YANG Module IETF Tag Registry 520 This registry allocates prefixes that have the standard prefix 521 "ietf:". New values should be well considered and not achievable 522 through a combination of already existing standard tags. 524 The allocation policy for this registry is IETF Review [RFC5226]. 526 The initial values for this registry are as follows. 528 [Editor's note: some of these tags are expected to move to 529 [I-D.ietf-rtgwg-device-model] if/when this document becomes a WG 530 document and that document is refactored to use tags.] 532 +---------------------------------+---------------------+-----------+ 533 | Tag | Description | Reference | 534 +---------------------------------+---------------------+-----------+ 535 | ietf:area:art | Applications and | [This | 536 | | Real-Time Area | document] | 537 | | module. | | 538 | | | | 539 | ietf:area:gen | General Area | [This | 540 | | module. | document] | 541 | | | | 542 | ietf:area:int | Internet Area | [This | 543 | | module. | document] | 544 | | | | 545 | ietf:area:ops | Operations and | [This | 546 | | Management Area | document] | 547 | | module. | | 548 | | | | 549 | ietf:area:rtg | Routing Area | [This | 550 | | module. | document] | 551 | | | | 552 | ietf:area:sec | Security Area | [This | 553 | | module. | document] | 554 | | | | 555 | ietf:area:tsv | Transport Area | [This | 556 | | module. | document] | 557 | | | | 558 | ietf:entity | A module for an | [This | 559 | | entity (*). | document] | 560 | | | | 561 | ietf:service | A module for a | [This | 562 | | service (*). | document] | 563 | | | | 564 | ietf:hardware | A module for | [This | 565 | | hardware. | document] | 566 | | | | 567 | ietf:software | A module for | [This | 568 | | software. | document] | 569 | | | | 570 | ietf:protocol | A module | [This | 571 | | representing a | document] | 572 | | protocol. | | 573 | | | | 574 | ietf:protocol:system-management | A module | [This | 575 | | representing a | document] | 576 | | system management | | 577 | | protocol. | | 578 | | | | 579 | ietf:protocol:network-service | A module | [This | 580 | | representing a | document] | 581 | | network service | | 582 | | protocol. | | 583 | | | | 584 | ietf:protocol:routing | A module | [This | 585 | | representing a | document] | 586 | | control plane | | 587 | | routing protocol. | | 588 | | | | 589 | ietf:protocol:signaling | A module | [This | 590 | | representing a | document] | 591 | | control plane | | 592 | | signaling protocol. | | 593 | | | | 594 | ietf:protocol:oam | A module | [This | 595 | | representing a | document] | 596 | | Operations, | | 597 | | Administration, and | | 598 | | Maintenance | | 599 | | protocol. | | 600 | | | | 601 | ietf:protocol:lmp | A module | [This | 602 | | representing a link | document] | 603 | | management | | 604 | | protocol. | | 605 | | | | 606 | ietf:protocol:routing:igp | An IGP protocol | [This | 607 | | module. | document] | 608 | | | | 609 | ietf:protocol:routing:egp | An EGP protocol | [This | 610 | | module. | document] | 611 +---------------------------------+---------------------+-----------+ 613 (*) - see [I-D.ietf-netmod-yang-model-classification] 615 Table 1: IETF Module Tag Registry 617 11. References 619 11.1. Normative References 621 [I-D.ietf-netmod-rfc6087bis] 622 Bierman, A., "Guidelines for Authors and Reviewers of YANG 623 Data Model Documents", draft-ietf-netmod-rfc6087bis-10 624 (work in progress), January 2017. 626 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 627 Requirement Levels", BCP 14, RFC 2119, 628 DOI 10.17487/RFC2119, March 1997, 629 . 631 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 632 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 633 DOI 10.17487/RFC5226, May 2008, 634 . 636 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 637 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 638 . 640 11.2. Informative References 642 [I-D.ietf-netmod-yang-model-classification] 643 Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 644 Classification", draft-ietf-netmod-yang-model- 645 classification-04 (work in progress), October 2016. 647 [I-D.ietf-rtgwg-device-model] 648 Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps, 649 "Network Device YANG Organizational Models", draft-ietf- 650 rtgwg-device-model-01 (work in progress), October 2016. 652 Authors' Addresses 654 Christan Hopps 655 Deutsche Telekom 657 Email: chopps@chopps.org 659 Lou Berger 660 LabN Consulting, L.L.C. 662 Email: lberger@labn.net 664 Dean Bogdanovic 666 Email: ivandean@gmail.com