| < draft-boucadair-netmod-iana-registries-02.txt | draft-boucadair-netmod-iana-registries-03.txt > | |||
|---|---|---|---|---|
| netmod M. Boucadair | netmod M. Boucadair | |||
| Internet-Draft Orange | Internet-Draft Orange | |||
| Updates: 8407 (if approved) 25 March 2022 | Updates: 8407 (if approved) 29 March 2022 | |||
| Intended status: Standards Track | Intended status: Standards Track | |||
| Expires: 26 September 2022 | Expires: 30 September 2022 | |||
| Recommendations for Creating IANA-Maintained YANG Modules | Recommendations for Creating IANA-Maintained YANG Modules | |||
| draft-boucadair-netmod-iana-registries-02 | draft-boucadair-netmod-iana-registries-03 | |||
| Abstract | Abstract | |||
| This document provides a set of guidelines for YANG module authors | This document provides a set of guidelines for YANG module authors | |||
| related to the design of IANA-maintained modules. These guidelines | related to the design of IANA-maintained modules. These guidelines | |||
| are meant to leverage existing IANA registries and use YANG as just | are meant to leverage existing IANA registries and use YANG as | |||
| another format to present the content of these registries. | another format to present the content of these registriesn when | |||
| appropriate. | ||||
| This document updates RFC 8407 by providing additional guidelines for | This document updates RFC 8407 by providing additional guidelines for | |||
| IANA-maintained modules. It does not change anything written in RFC | IANA-maintained modules. It does not change anything written in RFC | |||
| 8407. | 8407. | |||
| Status of This Memo | Status of This Memo | |||
| This Internet-Draft is submitted in full conformance with the | This Internet-Draft is submitted in full conformance with the | |||
| provisions of BCP 78 and BCP 79. | provisions of BCP 78 and BCP 79. | |||
| Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
| Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
| working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
| Drafts is at https://datatracker.ietf.org/drafts/current/. | Drafts is at https://datatracker.ietf.org/drafts/current/. | |||
| Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
| and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
| time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
| material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
| This Internet-Draft will expire on 26 September 2022. | This Internet-Draft will expire on 30 September 2022. | |||
| Copyright Notice | Copyright Notice | |||
| Copyright (c) 2022 IETF Trust and the persons identified as the | Copyright (c) 2022 IETF Trust and the persons identified as the | |||
| document authors. All rights reserved. | document authors. All rights reserved. | |||
| This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
| Provisions Relating to IETF Documents (https://trustee.ietf.org/ | Provisions Relating to IETF Documents (https://trustee.ietf.org/ | |||
| license-info) in effect on the date of publication of this document. | license-info) in effect on the date of publication of this document. | |||
| Please review these documents carefully, as they describe your rights | Please review these documents carefully, as they describe your rights | |||
| and restrictions with respect to this document. Code Components | and restrictions with respect to this document. Code Components | |||
| extracted from this document must include Revised BSD License text as | extracted from this document must include Revised BSD License text as | |||
| described in Section 4.e of the Trust Legal Provisions and are | described in Section 4.e of the Trust Legal Provisions and are | |||
| provided without warranty as described in the Revised BSD License. | provided without warranty as described in the Revised BSD License. | |||
| Table of Contents | Table of Contents | |||
| 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 | |||
| 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 | 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 | |||
| 3. Guidelines for IANA-Maintained Registries . . . . . . . . . . 3 | 3. Guidelines for IANA-Maintained Modules . . . . . . . . . . . 3 | |||
| 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 | 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 | |||
| 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4 | 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4 | |||
| 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 4 | 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 4 | |||
| 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 4 | 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
| 7.1. Normative References . . . . . . . . . . . . . . . . . . 4 | 7.1. Normative References . . . . . . . . . . . . . . . . . . 4 | |||
| 7.2. Informative References . . . . . . . . . . . . . . . . . 5 | 7.2. Informative References . . . . . . . . . . . . . . . . . 5 | |||
| Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 | Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 | |||
| 1. Introduction | 1. Introduction | |||
| skipping to change at page 2, line 39 ¶ | skipping to change at page 2, line 40 ¶ | |||
| merely additional formats in which the "Interface Types (ifType)" and | merely additional formats in which the "Interface Types (ifType)" and | |||
| "Tunnel Types (tunnelType)" registries are available. The MIB | "Tunnel Types (tunnelType)" registries are available. The MIB | |||
| [RFC2863] and YANG modules [RFC7224][RFC8675] are not separate | [RFC2863] and YANG modules [RFC7224][RFC8675] are not separate | |||
| registries, and the same values are always present in all formats of | registries, and the same values are always present in all formats of | |||
| the same registry. | the same registry. | |||
| Also, some YANG modules include parameters and values directly in a | Also, some YANG modules include parameters and values directly in a | |||
| module that is not maintained by IANA while these are populated in an | module that is not maintained by IANA while these are populated in an | |||
| IANA registry. Such a design is suboptimal as it creates another | IANA registry. Such a design is suboptimal as it creates another | |||
| source of information that may deviate from the IANA registry as new | source of information that may deviate from the IANA registry as new | |||
| values are assigned. | values are assigned or some values are deprecated. | |||
| For the sake of consistency, better flexibility to support new | For the sake of consistency, better flexibility to support new | |||
| values, and maintaining IANA registries as the unique authoritative | values, and maintaining IANA registries as the unique authoritative | |||
| source of information, when such an information is maintained in a | source of information, when such an information is maintained in a | |||
| registry, this document encourages the use of IANA-maintained | registry, this document encourages the use of IANA-maintained | |||
| modules. | modules. | |||
| Section 3 updates the guidelines in [RFC8407]. | Section 3 updates the guidelines in [RFC8407]. | |||
| 2. Terminology | 2. Terminology | |||
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | |||
| "OPTIONAL" in this document are to be interpreted as described in BCP | "OPTIONAL" in this document are to be interpreted as described in BCP | |||
| 14 [RFC2119][RFC8174] when, and only when, they appear in all | 14 [RFC2119][RFC8174] when, and only when, they appear in all | |||
| capitals, as shown here. | capitals, as shown here. | |||
| This document makes use of the terms defined in Section 2 of | This document makes use of the terms defined in Section 2 of | |||
| [RFC8407]. | [RFC8407]. | |||
| 3. Guidelines for IANA-Maintained Registries | 3. Guidelines for IANA-Maintained Modules | |||
| When designing a YANG module for a functionality governed by a | When designing a YANG module for a functionality governed by a | |||
| protocol for which IANA maintains a registry, it is RECOMMENDED to | protocol for which IANA maintains a registry, it is RECOMMENDED to | |||
| specify an IANA-maintained module that echoes the content of that | specify an IANA-maintained module that echoes the content of that | |||
| registry. This is superior to including that content in an IETF- | registry. This is superior to including that content in an IETF- | |||
| maintained module. | maintained module. | |||
| When one or multiple sub-registries are available under the same | When one or multiple sub-registries are available under the same | |||
| registry, it is RECOMMENDED to define an IANA-maintained module for | registry, it is RECOMMENDED to define an IANA-maintained module for | |||
| each sub-registry. However, module designers MAY consider defining | each sub-registry. However, module designers MAY consider defining | |||
| one single IANA-maintained module that covers all sub-registries if | one single IANA-maintained module that covers all sub-registries if | |||
| maintaining that single module is manageable (e.g., very few values | maintaining that single module is manageable (e.g., very few values | |||
| are present or expected to be present for each sub-registry). An | are present or expected to be present for each sub-registry). An | |||
| example of such a module is documented in Section 5.2 of [RFC9132]. | example of such a module is documented in Section 5.2 of [RFC9132]. | |||
| An IANA-maintained module MAY use identities (e.g., [RFC8675]) or | An IANA-maintained module may use identities (e.g., [RFC8675]) or | |||
| enumerations (e.g., [RFC9108]). The final decision is left to the | enumerations (e.g., [RFC9108]). The decision about which type to use | |||
| module designers and should be made based upon specifics related to | is left to the module designers and should be made based upon | |||
| the intended use of the module. It is worth mentioning that | specifics related to the intended use of the IANA-maintained module. | |||
| identities are useful if the registry entries are organized | For example, identities are useful if the registry entries are | |||
| hierarchically, possibly including multiple inheritances. It is | organized hierarchically, possibly including multiple inheritances. | |||
| RECOMMENDED that the reasoning for the design choice is documented in | It is RECOMMENDED that the reasoning for the design choice is | |||
| the companion specification document that registers the module. For | documented in the companion specification that registers an IANA- | |||
| example, [I-D.ietf-dots-telemetry] defines an IANA-maintained module | maintained module. For example, [I-D.ietf-dots-telemetry] defines an | |||
| that uses enumerations for the following reason: | IANA-maintained module that uses enumerations for the following | |||
| reason: | ||||
| "The DOTS telemetry module (Section 10.1) uses "enumerations" rather | "The DOTS telemetry module (Section 10.1) uses "enumerations" rather | |||
| than "identities" to define units, samples, and intervals because | than "identities" to define units, samples, and intervals because | |||
| otherwise the namespace identifier "ietf-dots-telemetry" must be | otherwise the namespace identifier "ietf-dots-telemetry" must be | |||
| included when a telemetry attribute is included (e.g., in a | included when a telemetry attribute is included (e.g., in a | |||
| mitigation efficacy update). The use of "identities" is thus | mitigation efficacy update). The use of "identities" is thus | |||
| suboptimal from a message compactness standpoint; one of the key | suboptimal from a message compactness standpoint; one of the key | |||
| requirements for DOTS messages." | requirements for DOTS messages." | |||
| Designers of IANA-maintained modules MAY supply the full Initial | Designers of IANA-maintained modules MAY supply the full initial | |||
| version of the module in a specification document that registers the | version of the module in a specification document that registers the | |||
| module or only a script to be used (including by IANA) for generating | module or only a script to be used (including by IANA) for generating | |||
| the module (e.g., an XSLT stylesheet as in Appendix A of [RFC9108]). | the module (e.g., an XSLT stylesheet as in Appendix A of [RFC9108]). | |||
| When a script is used, the Internet-Draft that defines an IANA- | When a script is used, the Internet-Draft that defines an IANA- | |||
| maintained module SHOULD include an appendix with the initial full | maintained module SHOULD include an appendix with the initial full | |||
| version of the module. Including such an appendix in pre-RFC | version of the module. Including such an appendix in pre-RFC | |||
| versions is meant to assess the correctness of the outcome of the | versions is meant to assess the correctness of the outcome of the | |||
| supplied script. The authors MUST include a note to the RFC Editor | supplied script. The authors MUST include a note to the RFC Editor | |||
| requesting that the appendix be removed before publication as RFC. | requesting that the appendix be removed before publication as RFC. | |||
| Initial versions of IANA-maintained modules that are published in | Initial versions of IANA-maintained modules that are published in | |||
| RFCs may be misused despite the appropriate language to refer to the | RFCs may be misused despite the appropriate language to refer to the | |||
| IANA registry to retrieve the up-to-date module. This is problematic | IANA registry to retrieve the up-to-date module. This is problematic | |||
| for interoperability (e.g., when values are deprecated or are | for interoperability, e.g., when values are deprecated or are | |||
| associated with a new meaning). | associated with a new meaning. | |||
| Note: [Style] provides XSLT 1.0 stylesheets and other tools for | Note: [Style] provides XSLT 1.0 stylesheets and other tools for | |||
| translating IANA registries to YANG modules. The tools can be | translating IANA registries to YANG modules. The tools can be | |||
| used to generate up-to-date revisions of an IANA-maintained module | used to generate up-to-date revisions of an IANA-maintained module | |||
| based upon the XML representation of an IANA registry. | based upon the XML representation of an IANA registry. | |||
| 4. IANA Considerations | 4. IANA Considerations | |||
| This document does not require any IANA action. | This document does not require any IANA action. | |||
| 5. Security Considerations | 5. Security Considerations | |||
| This document does not introduce new concerns other than those | This document does not introduce new concerns other than those | |||
| already discussed in Section 15 of [RFC8407]. | already discussed in Section 15 of [RFC8407]. | |||
| 6. Acknowledgements | 6. Acknowledgements | |||
| This document is triggered by a discussion the author had with Dhruv | This document is triggered by a discussion the author had with Dhruv | |||
| Dhody and Jensen Zhang. | Dhody and Jensen Zhang. | |||
| Thanks to Juergen Schoenwaelder and Ladislav Lhotka for the | Thanks to Juergen Schoenwaelder, Ladislav Lhotka, and Qin Wu for the | |||
| discussion and valuable comments. Special thanks to Ladislav Lhotka | discussion and valuable comments. Special thanks to Ladislav Lhotka | |||
| for sharing more context that led to the design documented in | for sharing more context that led to the design documented in | |||
| [RFC9108]. | [RFC9108]. | |||
| Thanks for Andy Bierman for the comments. | ||||
| 7. References | 7. References | |||
| 7.1. Normative References | 7.1. Normative References | |||
| [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
| Requirement Levels", BCP 14, RFC 2119, | Requirement Levels", BCP 14, RFC 2119, | |||
| DOI 10.17487/RFC2119, March 1997, | DOI 10.17487/RFC2119, March 1997, | |||
| <https://www.rfc-editor.org/info/rfc2119>. | <https://www.rfc-editor.org/info/rfc2119>. | |||
| [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | |||
| End of changes. 13 change blocks. | ||||
| 23 lines changed or deleted | 27 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ | ||||