idnits 2.17.1 draft-boucadair-netmod-iana-registries-03.txt: -(230): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (29 March 2022) is 760 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 netmod M. Boucadair 3 Internet-Draft Orange 4 Updates: 8407 (if approved) 29 March 2022 5 Intended status: Standards Track 6 Expires: 30 September 2022 8 Recommendations for Creating IANA-Maintained YANG Modules 9 draft-boucadair-netmod-iana-registries-03 11 Abstract 13 This document provides a set of guidelines for YANG module authors 14 related to the design of IANA-maintained modules. These guidelines 15 are meant to leverage existing IANA registries and use YANG as 16 another format to present the content of these registriesn when 17 appropriate. 19 This document updates RFC 8407 by providing additional guidelines for 20 IANA-maintained modules. It does not change anything written in RFC 21 8407. 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 30 September 2022. 40 Copyright Notice 42 Copyright (c) 2022 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 (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Revised BSD License text as 51 described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Revised BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Guidelines for IANA-Maintained Modules . . . . . . . . . . . 3 59 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 60 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4 61 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 4 62 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 7.1. Normative References . . . . . . . . . . . . . . . . . . 4 64 7.2. Informative References . . . . . . . . . . . . . . . . . 5 65 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 67 1. Introduction 69 IANA maintains a set of registries that are key for interoperability. 70 The content of these registries are usually available using various 71 formats (e.g., plain text, XML). However, there were some confusion 72 in the past about whether the content of some registries is dependent 73 on a specific representation format. For example, Section 5 of 74 [RFC8892] was published to clarify that MIB and YANG modules are 75 merely additional formats in which the "Interface Types (ifType)" and 76 "Tunnel Types (tunnelType)" registries are available. The MIB 77 [RFC2863] and YANG modules [RFC7224][RFC8675] are not separate 78 registries, and the same values are always present in all formats of 79 the same registry. 81 Also, some YANG modules include parameters and values directly in a 82 module that is not maintained by IANA while these are populated in an 83 IANA registry. Such a design is suboptimal as it creates another 84 source of information that may deviate from the IANA registry as new 85 values are assigned or some values are deprecated. 87 For the sake of consistency, better flexibility to support new 88 values, and maintaining IANA registries as the unique authoritative 89 source of information, when such an information is maintained in a 90 registry, this document encourages the use of IANA-maintained 91 modules. 93 Section 3 updates the guidelines in [RFC8407]. 95 2. Terminology 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 99 "OPTIONAL" in this document are to be interpreted as described in BCP 100 14 [RFC2119][RFC8174] when, and only when, they appear in all 101 capitals, as shown here. 103 This document makes use of the terms defined in Section 2 of 104 [RFC8407]. 106 3. Guidelines for IANA-Maintained Modules 108 When designing a YANG module for a functionality governed by a 109 protocol for which IANA maintains a registry, it is RECOMMENDED to 110 specify an IANA-maintained module that echoes the content of that 111 registry. This is superior to including that content in an IETF- 112 maintained module. 114 When one or multiple sub-registries are available under the same 115 registry, it is RECOMMENDED to define an IANA-maintained module for 116 each sub-registry. However, module designers MAY consider defining 117 one single IANA-maintained module that covers all sub-registries if 118 maintaining that single module is manageable (e.g., very few values 119 are present or expected to be present for each sub-registry). An 120 example of such a module is documented in Section 5.2 of [RFC9132]. 122 An IANA-maintained module may use identities (e.g., [RFC8675]) or 123 enumerations (e.g., [RFC9108]). The decision about which type to use 124 is left to the module designers and should be made based upon 125 specifics related to the intended use of the IANA-maintained module. 126 For example, identities are useful if the registry entries are 127 organized hierarchically, possibly including multiple inheritances. 128 It is RECOMMENDED that the reasoning for the design choice is 129 documented in the companion specification that registers an IANA- 130 maintained module. For example, [I-D.ietf-dots-telemetry] defines an 131 IANA-maintained module that uses enumerations for the following 132 reason: 134 "The DOTS telemetry module (Section 10.1) uses "enumerations" rather 135 than "identities" to define units, samples, and intervals because 136 otherwise the namespace identifier "ietf-dots-telemetry" must be 137 included when a telemetry attribute is included (e.g., in a 138 mitigation efficacy update). The use of "identities" is thus 139 suboptimal from a message compactness standpoint; one of the key 140 requirements for DOTS messages." 142 Designers of IANA-maintained modules MAY supply the full initial 143 version of the module in a specification document that registers the 144 module or only a script to be used (including by IANA) for generating 145 the module (e.g., an XSLT stylesheet as in Appendix A of [RFC9108]). 146 When a script is used, the Internet-Draft that defines an IANA- 147 maintained module SHOULD include an appendix with the initial full 148 version of the module. Including such an appendix in pre-RFC 149 versions is meant to assess the correctness of the outcome of the 150 supplied script. The authors MUST include a note to the RFC Editor 151 requesting that the appendix be removed before publication as RFC. 152 Initial versions of IANA-maintained modules that are published in 153 RFCs may be misused despite the appropriate language to refer to the 154 IANA registry to retrieve the up-to-date module. This is problematic 155 for interoperability, e.g., when values are deprecated or are 156 associated with a new meaning. 158 Note: [Style] provides XSLT 1.0 stylesheets and other tools for 159 translating IANA registries to YANG modules. The tools can be 160 used to generate up-to-date revisions of an IANA-maintained module 161 based upon the XML representation of an IANA registry. 163 4. IANA Considerations 165 This document does not require any IANA action. 167 5. Security Considerations 169 This document does not introduce new concerns other than those 170 already discussed in Section 15 of [RFC8407]. 172 6. Acknowledgements 174 This document is triggered by a discussion the author had with Dhruv 175 Dhody and Jensen Zhang. 177 Thanks to Juergen Schoenwaelder, Ladislav Lhotka, and Qin Wu for the 178 discussion and valuable comments. Special thanks to Ladislav Lhotka 179 for sharing more context that led to the design documented in 180 [RFC9108]. 182 Thanks for Andy Bierman for the comments. 184 7. References 186 7.1. Normative References 188 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 189 Requirement Levels", BCP 14, RFC 2119, 190 DOI 10.17487/RFC2119, March 1997, 191 . 193 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 194 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 195 May 2017, . 197 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 198 Documents Containing YANG Data Models", BCP 216, RFC 8407, 199 DOI 10.17487/RFC8407, October 2018, 200 . 202 7.2. Informative References 204 [I-D.ietf-dots-telemetry] 205 Boucadair, M., Reddy.K, T., Doron, E., Chen, M., and J. 206 Shallow, "Distributed Denial-of-Service Open Threat 207 Signaling (DOTS) Telemetry", Work in Progress, Internet- 208 Draft, draft-ietf-dots-telemetry-25, 21 March 2022, 209 . 212 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 213 MIB", RFC 2863, DOI 10.17487/RFC2863, June 2000, 214 . 216 [RFC7224] Bjorklund, M., "IANA Interface Type YANG Module", 217 RFC 7224, DOI 10.17487/RFC7224, May 2014, 218 . 220 [RFC8675] Boucadair, M., Farrer, I., and R. Asati, "A YANG Data 221 Model for Tunnel Interface Types", RFC 8675, 222 DOI 10.17487/RFC8675, November 2019, 223 . 225 [RFC8892] Thaler, D. and D. Romascanu, "Guidelines and Registration 226 Procedures for Interface Types and Tunnel Types", 227 RFC 8892, DOI 10.17487/RFC8892, August 2020, 228 . 230 [RFC9108] Lhotka, L. and P. Špaček, "YANG Types for DNS Classes and 231 Resource Record Types", RFC 9108, DOI 10.17487/RFC9108, 232 September 2021, . 234 [RFC9132] Boucadair, M., Ed., Shallow, J., and T. Reddy.K, 235 "Distributed Denial-of-Service Open Threat Signaling 236 (DOTS) Signal Channel Specification", RFC 9132, 237 DOI 10.17487/RFC9132, September 2021, 238 . 240 [Style] IANA YANG, "IANA YANG", 241 . 243 Author's Address 245 Mohamed Boucadair 246 Orange 247 35000 Rennes 248 France 249 Email: mohamed.boucadair@orange.com