< 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/