idnits 2.17.1 draft-ietf-netmod-module-tags-04.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. ** There is 1 instance of too long lines in the document, the longest one being 14 characters in excess of 72. ** The abstract seems to contain references ([RFC8407]), 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. -- The abstract seems to indicate that this document updates RFC8407, but the header doesn't have an 'Updates:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 383 has weird spacing: '... prefix des...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (January 29, 2019) is 1914 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) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Downref: Normative reference to an Informational RFC: RFC 8199 Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Hopps 3 Internet-Draft L. Berger 4 Updates: RFC8407 (if approved) LabN Consulting, L.L.C. 5 Intended status: Standards Track D. Bogdanovic 6 Expires: August 2, 2019 Volta Networks 7 January 29, 2019 9 YANG Module Tags 10 draft-ietf-netmod-module-tags-04 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. Tags may be standardized and assigned 18 during module definition; assigned by implementations; or dynamically 19 defined and set by users. This document provides guidance to future 20 model writers and, as such, this document updates [RFC8407]. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on August 2, 2019. 39 Copyright Notice 41 Copyright (c) 2019 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Some possible use cases of YANG module tags . . . . . . . 3 58 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 59 3. Tag Values . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3.1. IETF Standard Tags . . . . . . . . . . . . . . . . . . . 4 61 3.2. Vendor Tags . . . . . . . . . . . . . . . . . . . . . . . 4 62 3.3. User Tags . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3.4. Reserved Tags . . . . . . . . . . . . . . . . . . . . . . 4 64 4. Tag Management . . . . . . . . . . . . . . . . . . . . . . . 4 65 4.1. Module Definition Association . . . . . . . . . . . . . . 5 66 4.2. Implementation Association . . . . . . . . . . . . . . . 5 67 4.3. Administrative Tagging . . . . . . . . . . . . . . . . . 5 68 5. Tags Module Structure . . . . . . . . . . . . . . . . . . . . 5 69 5.1. Tags Module Tree . . . . . . . . . . . . . . . . . . . . 5 70 5.2. Tags Module . . . . . . . . . . . . . . . . . . . . . . . 5 71 6. Other Classifications . . . . . . . . . . . . . . . . . . . . 8 72 7. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 8 73 7.1. Define Standard Tags . . . . . . . . . . . . . . . . . . 8 74 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 75 8.1. YANG Module Tag Prefix Registry . . . . . . . . . . . . . 8 76 8.2. YANG Module IETF Tag Registry . . . . . . . . . . . . . . 9 77 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 78 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 79 10.1. Normative References . . . . . . . . . . . . . . . . . . 10 80 10.2. Informative References . . . . . . . . . . . . . . . . . 11 81 Appendix A. Example . . . . . . . . . . . . . . . . . . . . . . 11 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 84 1. Introduction 86 The use of tags for classification and organization is fairly 87 ubiquitous not only within IETF protocols, but in the internet itself 88 (e.g., #hashtags). One benefit of using tags for organization over a 89 rigid structure is that it is more flexible and can more easily adapt 90 over time as technologies evolve. Tags can be usefully standardized, 91 but they can also serve as a non-standardized mechanism available for 92 users to define themselves. This document provides a mechanism to 93 define tags and associate them with YANG modules in a flexible 94 manner. In particular, tags may be standardized as well as assigned 95 during module definition; assigned by implementations; or dynamically 96 defined and set by users. 98 This document defines a YANG module [RFC6020] which provides a list 99 of module entries to allow for adding or removing of tags as well as 100 viewing the set of tags associated with a module. 102 This document defines an extension statement to be used to indicate 103 tags that SHOULD be added by the module implementation automatically 104 (i.e., outside of configuration). 106 This document also defines an IANA registry for tag prefixes as well 107 as a set of globally assigned tags. 109 Section 7 provides guidelines for authors of YANG data models. This 110 section updates [RFC8407]. 112 1.1. Some possible use cases of YANG module tags 114 During this documents progression there were requests for example 115 uses of module tags. The following are a few example use cases for 116 tags. This list is certainly not exhaustive. 118 One example use of tags would be to help filter different discrete 119 categories of YANG modules supported by a device. E.g., if modules 120 are suitably tagged, then an XPath query can be used to list all of 121 the vendor modules supported by a device. 123 Tags can also be used to help coordination when multiple semi- 124 independent clients are interacting with the same devices. E.g., one 125 management client could mark that some modules should not be used 126 because they have not been verified to behave correctly, so that 127 other management clients avoid querying the data associated with 128 those modules. 130 Tag classification is useful for users searching module repositories 131 (e.g. YANG catalog). A query restricted to the 'ietf:routing' 132 module tag could be used to return only the IETF YANG modules 133 associated with routing. Without tags, a user would need to know the 134 name of all the IETF routing protocol YANG modules. 136 Future management protocol extensions could allow for filtering 137 queries of configuration or operational state on a server based on 138 tags. E.g., return all operational state related to system- 139 management. 141 2. Conventions Used in This Document 143 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 144 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 145 "OPTIONAL" in this document are to be interpreted as described in 147 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, 148 as shown here. 150 3. Tag Values 152 All tags begin with a prefix indicating who owns their definition. 153 An IANA registry is used to support standardizing tag prefixes. 154 Currently 3 prefixes are defined with all others reserved. No 155 further structure is imposed by this document on the value following 156 the standard prefix, and the value can contain any yang type 'string' 157 characters except carriage-returns, newlines and tabs. 159 3.1. IETF Standard Tags 161 An IETF standard tag is a tag that has the prefix "ietf:". All IETF 162 standard tags are registered with IANA in a registry defined later in 163 this document. 165 3.2. Vendor Tags 167 A vendor tag is a tag that has the prefix "vendor:". These tags are 168 defined by the vendor that implements the module, and are not 169 standardized; however, it is RECOMMENDED that the vendor include 170 extra identification in the tag to avoid collisions such as using the 171 enterpise or organization name follwing the "vendor:" prefix (e.g., 172 vendor:example.com:vendor-defined-classifier). 174 3.3. User Tags 176 A user tag is any tag that has the prefix "user:". These tags are 177 defined by the user/administrator and will never be standardized. 179 3.4. Reserved Tags 181 Any tag not starting with the prefix "ietf:", "vendor:" or "user:" is 182 reserved for future standardization. 184 4. Tag Management 186 Tags can become associated with a module in a number of ways. Tags 187 may be defined and associated at module design time, at 188 implementation time, or via user administrative control. As the main 189 consumer of tags are users, users may also remove any tag, no matter 190 how the tag became associated with a module. 192 4.1. Module Definition Association 194 A module definition can indicate a set of tags to be added by the 195 module implementer. These design time tags are indicated using the 196 module-tag extension statement. If the module definition will be 197 IETF standards track, the tags MUST also be IETF standard tags 198 (Section 3.1). Thus, new modules can drive the addition of new 199 standard tags to the IANA registry, and the IANA registry can serve 200 as a check against duplication. 202 4.2. Implementation Association 204 An implementation MAY include additional tags associated with a 205 module. These tags may be standard or vendor specific tags. 207 4.3. Administrative Tagging 209 Tags of any kind can be assigned and removed with using normal 210 configuration mechanisms. 212 5. Tags Module Structure 214 5.1. Tags Module Tree 216 The tree associated with the "ietf-module-tags" module follows. The 217 meaning of the symbols can be found in [RFC8340]. 219 module: ietf-module-tags 220 +--rw module-tags 221 +--rw module* [name] 222 +--rw name yang:yang-identifier 223 +--rw tag* tag 224 +--rw masked-tag* tag 226 5.2. Tags Module 228 file "ietf-module-tags@2018-10-17.yang" 229 module ietf-module-tags { 230 yang-version 1.1; 231 namespace "urn:ietf:params:xml:ns:yang:ietf-module-tags"; 232 prefix tags; 234 import ietf-yang-types { 235 prefix yang; 236 } 238 organization 239 "IETF NetMod Working Group (NetMod)"; 241 contact 242 "NetMod Working Group - "; 244 // RFC Ed.: replace XXXX with actual RFC number and 245 // remove this note. 247 description 248 "This module describes a mechanism associating tags with YANG 249 modules. Tags may be IANA assigned or privately defined. 251 Copyright (c) 2018 IETF Trust and the persons identified as 252 authors of the code. All rights reserved. 254 Redistribution and use in source and binary forms, with or 255 without modification, is permitted pursuant to, and subject to 256 the license terms contained in, the Simplified BSD License set 257 forth in Section 4.c of the IETF Trust's Legal Provisions 258 Relating to IETF Documents 259 (https://trustee.ietf.org/license-info). 261 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 262 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 263 'OPTIONAL' in the module text are to be interpreted as described 264 in RFC 2119 (https://tools.ietf.org/html/rfc2119). 266 This version of this YANG module is part of RFC XXXX 267 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 268 full legal notices."; 270 // RFC Ed.: update the date below with the date of RFC publication 271 // and RFC number and remove this note. 273 revision 2018-10-17 { 274 description 275 "Initial revision."; 276 reference "RFC XXXX: YANG Module Tags"; 277 } 279 typedef tag { 280 type string { 281 length "1..max"; 282 pattern '[a-zA-Z_][a-zA-Z0-9\-_]*:[\S ]+'; 283 } 284 description 285 "A tag value is composed of a standard prefix followed by any type 286 'string' value that does not include carriage return, newline or 287 tab characters."; 288 } 289 extension module-tag { 290 argument tag; 291 description 292 "The argument 'tag' is of type 'tag'. This extension statement is 293 used by module authors to indicate the tags that SHOULD be added 294 automatically by the system. As such the origin of the value 295 for the pre-defined tags should be set to 'system'."; 296 } 298 container module-tags { 299 description 300 "Contains the list of modules and their associated tags"; 301 list module { 302 key "name"; 303 description 304 "A list of modules and their associated tags"; 305 leaf name { 306 type yang:yang-identifier; 307 mandatory true; 308 description 309 "The YANG module name."; 310 } 311 leaf-list tag { 312 type tag; 313 description 314 "Tags associated with the module. See the IANA 'YANG Module 315 Tag Prefix' registry for reserved prefixes and the IANA 'YANG 316 Module IETF Tag' registry for IETF standard tags. 318 The operational view of this list is constructed using the following steps: 320 1) System added tags are added. 321 2) User configured tags are added. 322 3) Any tag that is equal to a masked-tag is removed."; 323 } 324 leaf-list masked-tag { 325 type tag; 326 description 327 "The list of tags that should not be associated with this 328 module. This user can remove (mask) tags by adding 329 them to this list. It is not an error to add tags to this 330 list that are not associated with the module."; 331 } 332 } 333 } 334 } 335 336 6. Other Classifications 338 It's worth noting that a different YANG module classification 339 document exists [RFC8199]. That document is classifying modules in 340 only a logical manner and does not define tagging or any other 341 mechanisms. It divides YANG modules into 2 categories (service or 342 element) and then into one of 3 origins: standard, vendor or user. 343 It does provide a good way to discuss and identify modules in 344 general. This document defines standard tags to support [RFC8199] 345 style classification. 347 7. Guidelines to Model Writers 349 This section updates [RFC8407]. 351 7.1. Define Standard Tags 353 A module can indicate using module-tag extension statements a set of 354 tags that are to be automatically associated with it (i.e., not added 355 through configuration). 357 module example-module { 358 ... 359 import module-tags { prefix tags; } 361 tags:module-tag "ietf:some-new-tag"; 362 tags:module-tag "ietf:some-other-tag"; 363 ... 364 } 366 The module writer can use existing standard tags, or use new tags 367 defined in the model definition, as appropriate. For standardized 368 modules new tags MUST be assigned in the IANA registry defined below, 369 see Section 8.2 below. 371 8. IANA Considerations 373 8.1. YANG Module Tag Prefix Registry 375 This registry allocates tag prefixes. All YANG module tags SHOULD 376 begin with one of the prefixes in this registry. 378 The allocation policy for this registry is Specification Required 379 [RFC5226]. 381 The initial values for this registry are as follows. 383 prefix description 384 -------- --------------------------------------------------- 385 ietf: IETF Standard Tag allocated in the IANA YANG Module 386 IETF Tag Registry. 387 vendor: Non-standardized tags allocated by the module implementer. 388 user: Non-standardized tags allocated by and for the user. 390 Other SDOs (standard organizations) wishing to standardize their own 391 set of tags could allocate a top level prefix from this registry. 393 8.2. YANG Module IETF Tag Registry 395 This registry allocates prefixes that have the standard prefix 396 "ietf:". New values should be well considered and not achievable 397 through a combination of already existing standard tags. 399 The allocation policy for this registry is IETF Review [RFC5226]. 401 The initial values for this registry are as follows. 403 +------------------------+------------------------------+-----------+ 404 | Tag | Description | Reference | 405 +------------------------+------------------------------+-----------+ 406 | ietf:rfc8199-element | A module for a network | [RFC8199] | 407 | | element. | | 408 | | | | 409 | ietf:rfc8199-service | A module for a network | [RFC8199] | 410 | | service. | | 411 | | | | 412 | ietf:rfc8199-standard | A module defined by a | [RFC8199] | 413 | | standards organization. | | 414 | | | | 415 | ietf:rfc8199-vendor | A module defined by a | [RFC8199] | 416 | | vendor. | | 417 | | | | 418 | ietf:rfc8199-user | A module defined by the | [RFC8199] | 419 | | user. | | 420 | | | | 421 | ietf:hardware | A module relating to | [This | 422 | | hardware (e.g., inventory). | document] | 423 | | | | 424 | ietf:software | A module relating to | [This | 425 | | software (e.g., installed | document] | 426 | | OS). | | 427 | | | | 428 | ietf:qos | A module for managing | [This | 429 | | quality of service. | document] | 430 | | | | 431 | ietf:protocol | A module representing a | [This | 432 | | protocol. | document] | 433 | | | | 434 | ietf:system-management | A module relating to system | [This | 435 | | management (e.g., a system | document] | 436 | | management protocol such as | | 437 | | syslog, TACAC+, SNMP, | | 438 | | netconf, ...). | | 439 | | | | 440 | ietf:network-service | A module relating to network | [This | 441 | | service (e.g., a network | document] | 442 | | service protocol such as an | | 443 | | NTP server, DNS server, DHCP | | 444 | | server, etc). | | 445 | | | | 446 | ietf:oam | A module representing | [This | 447 | | Operations, Administration, | document] | 448 | | and Maintenance (e.g., BFD). | | 449 | | | | 450 | ietf:routing | A module related to routing. | [This | 451 | | | document] | 452 | | | | 453 | ietf:signaling | A module representing | [This | 454 | | control plane signaling. | document] | 455 | | | | 456 | ietf:lmp | A module representing a link | [This | 457 | | management protocol. | document] | 458 +------------------------+------------------------------+-----------+ 460 Table 1: IETF Module Tag Registry 462 9. Acknowledgements 464 Special thanks to Robert Wilton for his help improving the 465 introduction and providing the example use cases. 467 10. References 469 10.1. Normative References 471 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 472 Requirement Levels", BCP 14, RFC 2119, 473 DOI 10.17487/RFC2119, March 1997, 474 . 476 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 477 IANA Considerations Section in RFCs", RFC 5226, 478 DOI 10.17487/RFC5226, May 2008, 479 . 481 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 482 the Network Configuration Protocol (NETCONF)", RFC 6020, 483 DOI 10.17487/RFC6020, October 2010, 484 . 486 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 487 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 488 May 2017, . 490 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 491 Classification", RFC 8199, DOI 10.17487/RFC8199, July 492 2017, . 494 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 495 Documents Containing YANG Data Models", BCP 216, RFC 8407, 496 DOI 10.17487/RFC8407, October 2018, 497 . 499 10.2. Informative References 501 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 502 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 503 . 505 Appendix A. Example 507 The following is a fictional example result from a query of the 508 module tags list. For the sake of brevity only a few module results 509 are imagined. 511 { 512 "ietf-module-tags:module-tags": { 513 "module": [ 514 { 515 "name": "ietf-bfd", 516 "tag": [ 517 "ietf:protocol", 518 "ietf:oam", 519 "ietf:rfc8199-element", 520 "ietf:rfc8199-standard" 521 ] 522 }, 523 { 524 "name": "ietf-isis", 525 "tag": [ 526 "ietf:protocol", 527 "ietf:rfc8199-element", 528 "ietf:rfc8199-standard", 529 "ietf:routing" 530 ] 531 }, 532 { 533 "name": "ietf-ssh-server", 534 "tag": [ 535 "ietf:protocol", 536 "ietf:rfc8199-element", 537 "ietf:rfc8199-standard", 538 "ietf:system-management" 539 ] 540 } 541 ] 542 } 543 } 545 Authors' Addresses 547 Christan Hopps 548 LabN Consulting, L.L.C. 550 Email: chopps@chopps.org 552 Lou Berger 553 LabN Consulting, L.L.C. 555 Email: lberger@labn.net 556 Dean Bogdanovic 557 Volta Networks 559 Email: ivandean@gmail.com