idnits 2.17.00 (12 Aug 2021) /tmp/idnits43131/draft-ietf-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 315 has weird spacing: '... prefix des...' -- The document date (June 30, 2018) is 1420 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: draft-ietf-netmod-rfc6087bis has been published as RFC 8407 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Downref: Normative reference to an Informational RFC: RFC 8199 Summary: 4 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: January 1, 2019 D. Bogdanovic 7 June 30, 2018 9 YANG Module Tags 10 draft-ietf-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. 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 21 [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 January 1, 2019. 40 Copyright Notice 42 Copyright (c) 2018 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 Prefixes . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3.1. IETF Standard Tags . . . . . . . . . . . . . . . . . . . 3 61 3.2. Vendor Tags . . . . . . . . . . . . . . . . . . . . . . . 3 62 3.3. Local Tags . . . . . . . . . . . . . . . . . . . . . . . 3 63 3.4. Reserved Tags . . . . . . . . . . . . . . . . . . . . . . 3 64 4. Tag Management . . . . . . . . . . . . . . . . . . . . . . . 4 65 4.1. Module Definition Association . . . . . . . . . . . . . . 4 66 4.2. Implementation Association . . . . . . . . . . . . . . . 4 67 4.3. Administrative Tagging . . . . . . . . . . . . . . . . . 4 68 5. Tags Module Structure . . . . . . . . . . . . . . . . . . . . 4 69 5.1. Tags Module Tree . . . . . . . . . . . . . . . . . . . . 4 70 5.2. Tags Module . . . . . . . . . . . . . . . . . . . . . . . 5 71 6. Other Classifications . . . . . . . . . . . . . . . . . . . . 6 72 7. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 6 73 7.1. Define Standard Tags . . . . . . . . . . . . . . . . . . 6 74 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 75 8.1. YANG Module Tag Prefix Registry . . . . . . . . . . . . . 7 76 8.2. YANG Module IETF Tag Registry . . . . . . . . . . . . . . 8 77 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 78 9.1. Normative References . . . . . . . . . . . . . . . . . . 9 79 9.2. Informative References . . . . . . . . . . . . . . . . . 10 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 82 1. Introduction 84 The use of tags for classification and organization is fairly 85 ubiquitous not only within IETF protocols, but in the internet itself 86 (e.g., #hashtags). Tags can be usefully standardized, but they can 87 also serve as a non-standardized mechanism available for users to 88 define themselves. Our solution provides for both cases allowing for 89 the most flexibility. In particular, tags may be standardized as 90 well as assigned during module definition; assigned by 91 implementations; or dynamically defined and set by users. 93 This document defines a module which provides a list of module 94 entries to allow for adding or removing of tags as well as viewing 95 the set of tags associated with a module. 97 This document also defines an IANA registry for tag prefixes as well 98 as a set of globally assigned tags. 100 Section 7 provides guidelines for authors of YANG data models. This 101 section updates [I-D.ietf-netmod-rfc6087bis]. 103 2. Conventions Used in This Document 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 107 document are to be interpreted as described in [RFC2119]. 109 Note that lower case versions of these key words are used in section 110 Section 7 where guidance is provided to future document authors. 112 3. Tag Prefixes 114 All tags have a prefix indicating who owns their definition. An IANA 115 registry is used to support standardizing tag prefixes. Currently 3 116 prefixes are defined with all others reserved. 118 3.1. IETF Standard Tags 120 An IETF standard tag is a tag that has the prefix "ietf:". All IETF 121 standard tags are registered with IANA in a registry defined later in 122 this document. 124 3.2. Vendor Tags 126 A vendor tag is a tag that has the prefix "vendor:". These tags are 127 defined by the vendor that implements the module, and are not 128 standardized; however, it is RECOMMENDED that the vendor include 129 extra identification in the tag name to avoid collisions such as 130 using the enterpise or organization name in the second field (e.g., 131 vendor:example.com:system-management:...). 133 3.3. Local Tags 135 A local tag is any tag that has the prefix "local:". These tags are 136 defined by the local user/administrator and will never be 137 standardized. 139 3.4. Reserved Tags 141 Any tag not starting with the prefix "ietf:", "vendor:" or "local:" 142 is reserved for future standardization. 144 4. Tag Management 146 Tags can become associated with a module in a number of ways. Tags 147 may be defined and associated at model design time, at implementation 148 time, or via user administrative control. As the main consumer of 149 tags are users, users may also remove any tag, no matter how the tag 150 became associated with a module. 152 4.1. Module Definition Association 154 A module definition SHOULD indicate a set of tags to be automatically 155 added by the module implementer. If the module definition will be 156 standard the tags MUST also be standard tags (Section 3.1). Thus, 157 new modules can drive the addition of new standard tags to the IANA 158 registry, and the IANA registry can serve as a check against 159 duplication. 161 4.2. Implementation Association 163 An implementation MAY include additional tags associated with a 164 module. These tags may be standard or vendor specific tags. 166 4.3. Administrative Tagging 168 Tags of any kind can be assigned and removed with normal 169 configuration mechanisms. 171 Implementations MUST ensure that a modules tag list is consistent 172 across any location from which the list is accessible. So if a user 173 adds a tag through configuration that tag should also be seen when 174 using any augmentation that exposes the modules tag list. 176 5. Tags Module Structure 178 5.1. Tags Module Tree 180 The tree associated with the tags module is: 182 module: ietf-module-tags 183 +--rw module-tags* [name] 184 +--rw name yang:yang-identifier 185 +--rw tag* string 186 +--rw masked-tag* string 188 5.2. Tags Module 190 file "ietf-module-tags@2018-03-06.yang" 191 module ietf-module-tags { 192 yang-version "1"; 193 namespace "urn:ietf:params:xml:ns:yang:ietf-module-tags"; 194 prefix "mtags"; 196 import ietf-yang-types { 197 prefix yang; 198 } 200 organization "IETF NetMod Working Group (NetMod)"; 202 contact 203 "NetMod Working Group - "; 205 description 206 "This module describes a tagging mechanism for yang module. 207 Tags may be IANA assigned or privately defined types."; 209 revision "2018-03-06" { 210 description 211 "Initial revision."; 212 reference "TBD"; 213 } 215 list module-tags { 216 key "name"; 218 description 219 "A list of modules and their associated tags"; 221 leaf name { 222 type yang:yang-identifier; 223 mandatory true; 224 description 225 "The YANG module or submodule name."; 226 } 228 leaf-list tag { 229 type string; 231 description 232 "A tag associated with the module. See the IANA 'YANG Module 233 Tag Prefix' registry for reserved prefixes and the IANA 234 'YANG Module IETF Tag' registry for IETF standard tags. 236 The operational view of this list will contain all 237 user-configured tags as well as any predefined tags that 238 have not been masked by the user using the masked-tag leaf 239 list below."; 240 } 242 leaf-list masked-tag { 243 type string; 245 description 246 "The list of tags that should not be associated with this 247 module. This user can remove (mask) predefined tags by 248 adding them to this list. It is not an error to add tags to 249 this list that are not predefined for the module."; 250 } 251 } 252 } 253 255 6. Other Classifications 257 It's worth noting that a different yang module classification 258 document exists [RFC8199]. That document is classifying modules in 259 only a logical manner and does not define tagging or any other 260 mechanisms. It divides yang modules into 2 categories (service or 261 element) and then into one of 3 origins: standard, vendor or user. 262 It does provide a good way to discuss and identify modules in 263 general. This document defines standard tags to support [RFC8199] 264 style classification. 266 7. Guidelines to Model Writers 268 This section updates [I-D.ietf-netmod-rfc6087bis]. 270 7.1. Define Standard Tags 272 A module SHOULD indicate, in the description statement of the module, 273 a set of tags that are to be associated with it. This description 274 should also include the appropriate conformance statement or 275 statements, using [RFC2119] language for each tag. 277 module example-module { 278 ... 279 description 280 "[Text describing the module...] 282 RFC TAGS: 283 The following tags MUST be included by an implementation: 284 - ietf:some-required-tag:foo 285 - ... 286 The following tags SHOULD be included by an implementation: 287 - ietf:some-recommended-tag:bar 288 - ... 289 The following tags MAY be included by an implementation: 290 - ietf:some-optional-tag:baz 291 - ... 292 "; 293 ... 294 } 296 One SHOULD only include conformance text if there will be tags listed 297 (i.e., there's no need to indicate an empty set). 299 The module writer may use existing standard tags, or use new tags 300 defined in the model definition, as appropriate. New tags should be 301 assigned in the IANA registry defined below, see Section 8.2 below. 303 8. IANA Considerations 305 8.1. YANG Module Tag Prefix Registry 307 This registry allocates tag prefixes. All YANG module tags SHOULD 308 begin with one of the prefixes in this registry. 310 The allocation policy for this registry is Specification Required 311 [RFC5226]. 313 The initial values for this registry are as follows. 315 prefix description 316 -------- --------------------------------------------------- 317 ietf: IETF Standard Tag allocated in the IANA YANG Module 318 IETF Tag Registry. 319 vendor: Non-standardized tags allocated by the module implementer. 320 local: Non-standardized tags allocated by and for the user. 322 Other SDOs (standard organizations) wishing to standardize their own 323 set of tags could allocate a top level prefix from this registry. 325 8.2. YANG Module IETF Tag Registry 327 This registry allocates prefixes that have the standard prefix 328 "ietf:". New values should be well considered and not achievable 329 through a combination of already existing standard tags. 331 The allocation policy for this registry is IETF Review [RFC5226]. 333 The initial values for this registry are as follows. 335 [Editor's note: many of these tags may move to 336 [I-D.ietf-rtgwg-device-model] if/when that document is refactored to 337 use tags.] 339 +------------------------+------------------------------+-----------+ 340 | Tag | Description | Reference | 341 +------------------------+------------------------------+-----------+ 342 | ietf:rfc8199:element | A module for a network | [RFC8199] | 343 | | element. | | 344 | | | | 345 | ietf:rfc8199:service | A module for a network | [RFC8199] | 346 | | service. | | 347 | | | | 348 | ietf:rfc8199:standard | A module defined by a | [RFC8199] | 349 | | standards organization. | | 350 | | | | 351 | ietf:rfc8199:vendor | A module defined by a | [RFC8199] | 352 | | vendor. | | 353 | | | | 354 | ietf:rfc8199:user | A module defined by the | [RFC8199] | 355 | | user. | | 356 | | | | 357 | ietf:device:hardware | A module relating to device | [This | 358 | | hardware (e.g., inventory). | document] | 359 | | | | 360 | ietf:device:software | A module relating to device | [This | 361 | | software (e.g., installed | document] | 362 | | OS). | | 363 | | | | 364 | ietf:device:qos | A module for managing | [This | 365 | | quality of service. | document] | 366 | | | | 367 | ietf:protocol | A module representing a | [This | 368 | | protocol. | document] | 369 | | | | 370 | ietf:system-management | A module relating to system | [This | 371 | | management (e.g., a system | document] | 372 | | management protocol). | | 373 | | | | 374 | ietf:network-service | A module relating to network | [This | 375 | | service (e.g., a network | document] | 376 | | service protocol). | | 377 | | | | 378 | ietf:oam | A module representing | [This | 379 | | Operations, Administration, | document] | 380 | | and Maintenance. | | 381 | | | | 382 | ietf:routing | A module related to routing. | [This | 383 | | | document] | 384 | | | | 385 | ietf:routing:rib | A module related to routing | [This | 386 | | information bases. | document] | 387 | | | | 388 | ietf:routing:igp | An interior gateway protocol | [This | 389 | | module. | document] | 390 | | | | 391 | ietf:routing:egp | An exterior gateway protocol | [This | 392 | | module. | document] | 393 | | | | 394 | ietf:signaling | A module representing | [This | 395 | | control plane signaling. | document] | 396 | | | | 397 | ietf:lmp | A module representing a link | [This | 398 | | management protocol. | document] | 399 +------------------------+------------------------------+-----------+ 401 Table 1: IETF Module Tag Registry 403 9. References 405 9.1. Normative References 407 [I-D.ietf-netmod-rfc6087bis] 408 Bierman, A., "Guidelines for Authors and Reviewers of YANG 409 Data Model Documents", draft-ietf-netmod-rfc6087bis-20 410 (work in progress), March 2018. 412 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 413 Requirement Levels", BCP 14, RFC 2119, 414 DOI 10.17487/RFC2119, March 1997, 415 . 417 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 418 IANA Considerations Section in RFCs", RFC 5226, 419 DOI 10.17487/RFC5226, May 2008, 420 . 422 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 423 Classification", RFC 8199, DOI 10.17487/RFC8199, July 424 2017, . 426 9.2. Informative References 428 [I-D.ietf-rtgwg-device-model] 429 Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps, 430 "Network Device YANG Logical Organization", draft-ietf- 431 rtgwg-device-model-02 (work in progress), March 2017. 433 Authors' Addresses 435 Christan Hopps 436 Deutsche Telekom 438 Email: chopps@chopps.org 440 Lou Berger 441 LabN Consulting, L.L.C. 443 Email: lberger@labn.net 445 Dean Bogdanovic 447 Email: ivandean@gmail.com