idnits 2.17.1 draft-ietf-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 311 has weird spacing: '... prefix des...' -- The document date (March 6, 2018) is 2243 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-18 ** 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: September 7, 2018 D. Bogdanovic 7 March 6, 2018 9 YANG Module Tags 10 draft-ietf-netmod-module-tags-01 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 September 7, 2018. 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 . . . . . . . . . . . . . . . . . . . . . . . 4 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 consider 129 including extra identification in the tag name to avoid collisions 130 (e.g., vendor:super-duper-company:...). 132 3.3. Local Tags 134 A local tag is any tag that has the prefix "local:". These tags are 135 defined by the local user/administrator and will never be 136 standardized. 138 3.4. Reserved Tags 140 Any tag not starting with the prefix "ietf:", "vendor:" or "local:" 141 is reserved for future standardization. 143 4. Tag Management 145 Tags can become associated with a module in a number of ways. Tags 146 may be defined and associated at model design time, at implementation 147 time, or via user administrative control. As the main consumer of 148 tags are users, users may also remove any tag, no matter how the tag 149 became associated with a module. 151 4.1. Module Definition Association 153 A module definition SHOULD indicate a set of tags to be automatically 154 added by the module implementer. These tags MUST be standard tags 155 (Section 3.1). This does imply that new modules may also drive the 156 addition of new standard tags to the IANA registry. 158 4.2. Implementation Association 160 An implementation MAY include additional tags associated with a 161 module. These tags may be standard or vendor specific tags. 163 4.3. Administrative Tagging 165 Tags of any kind can be assigned and removed with normal 166 configuration mechanisms. 168 Implementations MUST ensure that a modules tag list is consistent 169 across any location from which the list is accessible. So if a user 170 adds a tag through configuration that tag should also be seen when 171 using any augmentation that exposes the modules tag list. 173 5. Tags Module Structure 175 5.1. Tags Module Tree 177 The tree associated with the tags module is: 179 module: ietf-module-tags 180 +--rw module-tags* [name] 181 +--rw name yang:yang-identifier 182 +--rw tag* string 183 +--rw masked-tag* string 185 5.2. Tags Module 187 file "ietf-module-tags@2018-03-06.yang" 188 module ietf-module-tags { 189 yang-version "1"; 190 namespace "urn:ietf:params:xml:ns:yang:ietf-module-tags"; 191 prefix "mtags"; 193 import ietf-yang-types { 194 prefix yang; 195 } 197 organization "IETF NetMod Working Group (NetMod)"; 199 contact 200 "NetMod Working Group - "; 202 description 203 "This module describes a tagging mechanism for yang module. 204 Tags may be IANA assigned or privately defined types."; 206 revision "2018-03-06" { 207 description 208 "Initial revision."; 209 reference "TBD"; 210 } 212 list module-tags { 213 key "name"; 215 description 216 "A list of modules and their associated tags"; 218 leaf name { 219 type yang:yang-identifier; 220 mandatory true; 221 description 222 "The YANG module or submodule name."; 223 } 225 leaf-list tag { 226 type string; 228 description 229 "A tag associated with the module. See the IANA 'YANG Module 230 Tag Prefix' registry for reserved prefixes and the IANA 231 'YANG Module IETF Tag' registry for IETF standard tags. 233 The operational view of this list will contain all 234 user-configured tags as well as any predefined tags that 235 have not been masked by the user using the masked-tag leaf 236 list below."; 237 } 238 leaf-list masked-tag { 239 type string; 241 description 242 "The list of tags that should not be associated with this 243 module. This user can remove (mask) predefined tags by 244 adding them to this list. It is not an error to add tags to 245 this list that are not predefined for the module."; 246 } 247 } 248 } 249 251 6. Other Classifications 253 It's worth noting that a different yang module classification 254 document exists [RFC8199]. That document is classifying modules in 255 only a logical manner and does not define tagging or any other 256 mechanisms. It divides yang modules into 2 categories (service or 257 element) and then into one of 3 origins: standard, vendor or user. 258 It does provide a good way to discuss and identify modules in 259 general. This document defines standard tags to support [RFC8199] 260 style classification. 262 7. Guidelines to Model Writers 264 This section updates [I-D.ietf-netmod-rfc6087bis]. 266 7.1. Define Standard Tags 268 A module SHOULD indicate, in the description statement of the module, 269 a set of tags that are to be associated with it. This description 270 should also include the appropriate conformance statement or 271 statements, using [RFC2119] language for each tag. 273 module example-module { 274 ... 275 description 276 "[Text describing the module...] 278 RFC TAGS: 279 The following tags MUST be included by an implementation: 280 - ietf:some-required-tag:foo 281 - ... 282 The following tags SHOULD be included by an implementation: 283 - ietf:some-recommended-tag:bar 284 - ... 285 The following tags MAY be included by an implementation: 286 - ietf:some-optional-tag:baz 287 - ... 288 "; 289 ... 290 } 292 One SHOULD only include conformance text if there will be tags listed 293 (i.e., there's no need to indicate an empty set). 295 The module writer may use existing standard tags, or use new tags 296 defined in the model definition, as appropriate. New tags should be 297 assigned in the IANA registry defined below, see Section 8.2 below. 299 8. IANA Considerations 301 8.1. YANG Module Tag Prefix Registry 303 This registry allocates tag prefixes. All YANG module tags SHOULD 304 begin with one of the prefixes in this registry. 306 The allocation policy for this registry is Specification Required 307 [RFC5226]. 309 The initial values for this registry are as follows. 311 prefix description 312 -------- --------------------------------------------------- 313 ietf: IETF Standard Tag allocated in the IANA YANG Module 314 IETF Tag Registry. 315 vendor: Non-standardized tags allocated by the module implementer. 316 local: Non-standardized tags allocated by and for the user. 318 Other SDOs (standard organizations) wishing to standardize their own 319 set of tags could allocate a top level prefix from this registry. 321 8.2. YANG Module IETF Tag Registry 323 This registry allocates prefixes that have the standard prefix 324 "ietf:". New values should be well considered and not achievable 325 through a combination of already existing standard tags. 327 The allocation policy for this registry is IETF Review [RFC5226]. 329 The initial values for this registry are as follows. 331 [Editor's note: many of these tags may move to 332 [I-D.ietf-rtgwg-device-model] if/when that document is refactored to 333 use tags.] 335 +------------------------+------------------------------+-----------+ 336 | Tag | Description | Reference | 337 +------------------------+------------------------------+-----------+ 338 | ietf:rfc8199:element | A module for a network | [RFC8199] | 339 | | element. | | 340 | | | | 341 | ietf:rfc8199:service | A module for a network | [RFC8199] | 342 | | service. | | 343 | | | | 344 | ietf:rfc8199:standard | A module defined by a | [RFC8199] | 345 | | standards organization. | | 346 | | | | 347 | ietf:rfc8199:vendor | A module defined by a | [RFC8199] | 348 | | vendor. | | 349 | | | | 350 | ietf:rfc8199:user | A module defined by the | [RFC8199] | 351 | | user. | | 352 | | | | 353 | ietf:device:hardware | A module relating to device | [This | 354 | | hardware (e.g., inventory). | document] | 355 | | | | 356 | ietf:device:software | A module relating to device | [This | 357 | | software (e.g., installed | document] | 358 | | OS). | | 359 | | | | 360 | ietf:device:qos | A module for managing | [This | 361 | | quality of service. | document] | 362 | | | | 363 | ietf:protocol | A module representing a | [This | 364 | | protocol. | document] | 365 | | | | 366 | ietf:system-management | A module relating to system | [This | 367 | | management (e.g., a system | document] | 368 | | management protocol). | | 369 | | | | 370 | ietf:network-service | A module relating to network | [This | 371 | | service (e.g., a network | document] | 372 | | service protocol). | | 373 | | | | 374 | ietf:oam | A module representing | [This | 375 | | Operations, Administration, | document] | 376 | | and Maintenance. | | 377 | | | | 378 | ietf:routing | A module related to routing. | [This | 379 | | | document] | 380 | | | | 381 | ietf:routing:rib | A module related to routing | [This | 382 | | information bases. | document] | 383 | | | | 384 | ietf:routing:igp | An interior gateway protocol | [This | 385 | | module. | document] | 386 | | | | 387 | ietf:routing:egp | An exterior gateway protocol | [This | 388 | | module. | document] | 389 | | | | 390 | ietf:signaling | A module representing | [This | 391 | | control plane signaling. | document] | 392 | | | | 393 | ietf:lmp | A module representing a link | [This | 394 | | management protocol. | document] | 395 +------------------------+------------------------------+-----------+ 397 Table 1: IETF Module Tag Registry 399 9. References 401 9.1. Normative References 403 [I-D.ietf-netmod-rfc6087bis] 404 Bierman, A., "Guidelines for Authors and Reviewers of YANG 405 Data Model Documents", draft-ietf-netmod-rfc6087bis-18 406 (work in progress), February 2018. 408 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 409 Requirement Levels", BCP 14, RFC 2119, 410 DOI 10.17487/RFC2119, March 1997, 411 . 413 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 414 IANA Considerations Section in RFCs", RFC 5226, 415 DOI 10.17487/RFC5226, May 2008, 416 . 418 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 419 Classification", RFC 8199, DOI 10.17487/RFC8199, July 420 2017, . 422 9.2. Informative References 424 [I-D.ietf-rtgwg-device-model] 425 Lindem, A., Berger, L., Bogdanovic, D., and C. Hopps, 426 "Network Device YANG Logical Organization", draft-ietf- 427 rtgwg-device-model-02 (work in progress), March 2017. 429 Authors' Addresses 431 Christan Hopps 432 Deutsche Telekom 434 Email: chopps@chopps.org 436 Lou Berger 437 LabN Consulting, L.L.C. 439 Email: lberger@labn.net 441 Dean Bogdanovic 443 Email: ivandean@gmail.com