Internet DRAFT - draft-boucadair-netmod-iana-registries
draft-boucadair-netmod-iana-registries
netmod M. Boucadair
Internet-Draft Orange
Updates: 8407, 8126 (if approved) 20 January 2023
Intended status: Standards Track
Expires: 24 July 2023
Recommendations for Creating IANA-Maintained YANG Modules
draft-boucadair-netmod-iana-registries-07
Abstract
This document provides a set of guidelines for YANG module authors
related to the design of IANA-maintained modules. These guidelines
are meant to leverage existing IANA registries and use YANG as
another format to present the content of these registries when
appropriate.
This document updates RFC 8407 by providing additional guidelines for
IANA-maintained modules. Also, this document updates RFC 8126 by
providing additional guidelines for writing the IANA considerations
for RFCs that specify IANA-maintained modules. This document does
not change anything written in RFC 8407 and RFC 8126.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 24 July 2023.
Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the
document authors. All rights reserved.
Boucadair Expires 24 July 2023 [Page 1]
Internet-Draft IANA-Maintained YANG Modules January 2023
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Guidelines for IANA-Maintained Modules . . . . . . . . . . . 3
4. Guidance for Writing the IANA Considerations for RFCs Defining
IANA-Maintained Modules . . . . . . . . . . . . . . . . . 5
4.1. Template for IANA-Maintained Modules with Identities . . 6
4.2. Template for IANA-Maintained Modules with Enumerations . 6
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
6. Security Considerations . . . . . . . . . . . . . . . . . . . 7
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
8.1. Normative References . . . . . . . . . . . . . . . . . . 8
8.2. Informative References . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9
1. Introduction
IANA maintains a set of registries that are key for interoperability.
The content of these registries are usually available using various
formats (e.g., plain text, XML). However, there were some confusion
in the past about whether the content of some registries is dependent
on a specific representation format. For example, Section 5 of
[RFC8892] was published to clarify that MIB and YANG modules are
merely additional formats in which the "Interface Types (ifType)" and
"Tunnel Types (tunnelType)" registries are available. The MIB
[RFC2863] and YANG modules [RFC7224][RFC8675] are not separate
registries, and the same values are always present in all formats of
the same registry.
Also, some YANG modules include parameters and values directly in a
module that is not maintained by IANA while these are populated in an
IANA registry. Such a design is suboptimal as it creates another
source of information that may deviate from the IANA registry as new
values are assigned or some values are deprecated.
Boucadair Expires 24 July 2023 [Page 2]
Internet-Draft IANA-Maintained YANG Modules January 2023
For the sake of consistency, better flexibility to support new
values, and maintaining IANA registries as the unique authoritative
source of information, when such an information is maintained in a
registry, this document encourages the use of IANA-maintained
modules.
Section 3 updates the guidelines in [RFC8407]. Also, Section 4
updates [RFC8407] and [RFC8126] by providing guidance for writing the
IANA considerations for RFCs that specify IANA-maintained modules.
2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
This document makes use of the terms defined in Section 2 of
[RFC8407].
3. Guidelines for IANA-Maintained Modules
When designing a YANG module for a functionality governed by a
protocol for which IANA maintains a registry, it is RECOMMENDED to
specify an IANA-maintained module that echoes the content of that
registry. This is superior to including that content in an IETF-
maintained module.
When one or multiple sub-registries are available under the same
registry, it is RECOMMENDED to define an IANA-maintained module for
each sub-registry. However, module designers MAY consider defining
one single IANA-maintained module that covers all sub-registries if
maintaining that single module is manageable (e.g., very few values
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].
An IANA-maintained module may use identities (e.g., [RFC8675]) or
enumerations (e.g., [RFC9108]). The decision about which type to use
is left to the module designers and should be made based upon
specifics related to the intended use of the IANA-maintained module.
For example, identities are useful if the registry entries are
organized hierarchically, possibly including multiple inheritances.
It is RECOMMENDED that the reasoning for the design choice is
documented in the companion specification that registers an IANA-
maintained module. For example, [RFC9244] defines an IANA-maintained
module that uses enumerations for the following reason:
Boucadair Expires 24 July 2023 [Page 3]
Internet-Draft IANA-Maintained YANG Modules January 2023
"The DOTS telemetry module (Section 10.1) uses "enumerations" rather
than "identities" to define units, samples, and intervals because
otherwise the namespace identifier "ietf-dots-telemetry" must be
included when a telemetry attribute is included (e.g., in a
mitigation efficacy update). The use of "identities" is thus
suboptimal from a message compactness standpoint; one of the key
requirements for DOTS messages."
Designers of IANA-maintained modules MAY supply the full initial
version of the module in a specification document that registers the
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]).
For both cases, the document that defines an IANA-maintained module
MUST include a note indicating that the document is only documenting
the initial version of the module and that the authoritative version
is to be retrieved from the IANA registry. It is RECOMMENDED to
include the URL from where to retrieve the recent version of the
module. When a script is used, the Internet-Draft that defines an
IANA-maintained module SHOULD include an appendix with the initial
full version of the module. Including such an appendix in pre-RFC
versions is meant to assess the correctness of the outcome of the
supplied script. The authors MUST include a note to the RFC Editor
requesting that the appendix be removed before publication as RFC.
Initial versions of IANA-maintained modules that are published in
RFCs may be misused despite the appropriate language to refer to the
IANA registry to retrieve the up-to-date module. This is problematic
for interoperability, e.g., when values are deprecated or are
associated with a new meaning.
Note: [Style] provides XSLT 1.0 stylesheets and other tools for
translating IANA registries to YANG modules. The tools can be
used to generate up-to-date revisions of an IANA-maintained module
based upon the XML representation of an IANA registry.
If an IANA-maintained module is imported by another module, a
normative reference with the IANA URL from where to retrieve the
IANA-maintained module SHOULD be included. Although not encouraged,
referencing the RFC that defines the initial version of the IANA
module is acceptable in specific cases (e.g., the imported version is
specifically the initial version, the RFC includes useful description
about the usage of the module).
Examples of IANA URLs from where to retrieve the latest version of an
IANA-maintained module are: [IANA_BGP-L2_URL], [IANA_PW-Types_URL],
and [IANA_BFD_URL]. [IANA_FOO_URL] is used in the following to refer
to such URLs. These URLs are expected to be sufficiently permanent
and stable.
Boucadair Expires 24 July 2023 [Page 4]
Internet-Draft IANA-Maintained YANG Modules January 2023
4. Guidance for Writing the IANA Considerations for RFCs Defining IANA-
Maintained Modules
In addition to the IANA considerations in Section 3.8 of [RFC8407],
the IANA Considerations Section of an RFC that includes an IANA-
maintained module MUST provide the required instructions for IANA to
automatically perform the maintenance of that IANA module. These
instructions describe how to proceed with updates to the IANA-
maintained module that are triggered by a change to the authoritative
registry. Concretely, the IANA Considerations Section SHALL at least
provide the following information:
* An IANA request to add a note to the page displaying the
information about the IANA-maintained module that new values must
not be directly added to the module, but to an authoritative IANA
registry.
* An IANA request to add a note to the authoritative IANA registry
to indicate that any change to the registry must be reflected into
the corresponding IANA-maintained module.
* Details about the required actions (e.g., add a new "identity" or
"enum" statement) to update the IANA-maintained module to reflect
changes to an authoritative IANA registry. Typically, these
details have to include the procedure to create a new "identity"
statement name and sub-statements ("base", "status",
"description", and "reference") or a new "enum" statement and sub-
statements ("value", "status", "description", and "reference").
* A note that unassigned or reserved values must not be present in
the IANA-maintained module.
* An indication whether experimental values are included in the
IANA-maintained module. Absent such an indication, experimental
values MUST NOT be listed in the IANA-maintained module.
* An instruction about how to generate the "revision" statement.
A template for the IANA Considerations is provided in Section 4.1 for
IANA-maintained modules with identities and Section 4.2 for IANA-
maintained modules with enumerations. Authors may modify the
template to reflect specifics of their modules (e.g., Multiple
registries can be listed for a single IANA-maintained module, no
explicit description (or name) field is listed under the
authoritative IANA registry).
The following templates are to be considered in addition to the
required information that is provided in Section 3.8 of [RFC8407].
Boucadair Expires 24 July 2023 [Page 5]
Internet-Draft IANA-Maintained YANG Modules January 2023
4.1. Template for IANA-Maintained Modules with Identities
This document defines the initial version of the IANA-maintained
"iana-foo" YANG module. The most recent version of the YANG module
is available from the "YANG Parameters" registry
[IANA-YANG-PARAMETERS].
IANA is requested to add this note to the registry:
New values must not be directly added to the "iana-foo" YANG
module. They must instead be added to the "foo" registry.
When a value is added to the "foo" registry, a new "identity"
statement must be added to the "iana-foo" YANG module. The name of
the "identity" is the lower-case of the name provided in the
registry. The "identity" statement should have the following sub-
statements defined:
"base": Contains 'name-base-identity-defined-in-foo'.
"status": Include only if a registration has been deprecated or
obsoleted. IANA "deprecated" maps to YANG status
"deprecated", and IANA "obsolete" maps to YANG status
"obsolete".
"description": Replicates the description from the registry.
"reference": Replicates the reference(s) from the registry with the
title of the document(s) added.
Unassigned or reserved values are not present in the module.
When the "iana-foo" YANG module is updated, a new "revision"
statement with a unique revision date must be added in front of the
existing revision statements.
IANA is requested to add this note to [reference-to-the-iana-foo-
registry]:
When this registry is modified, the YANG module "iana-foo"
[IANA_FOO_URL] must be updated as defined in RFCXXXX.
4.2. Template for IANA-Maintained Modules with Enumerations
This document defines the initial version of the IANA-maintained
"iana-foo" YANG module. The most recent version of the YANG module
is available from the "YANG Parameters" registry
[IANA-YANG-PARAMETERS].
Boucadair Expires 24 July 2023 [Page 6]
Internet-Draft IANA-Maintained YANG Modules January 2023
IANA is requested to add this note to the registry:
New values must not be directly added to the "iana-foo" YANG
module. They must instead be added to the "foo" registry.
When a value is added to the "foo" registry, a new "enum" statement
must be added to the "iana-foo" YANG module. The "enum" statement,
and sub-statements thereof, should be defined:
"enum": Replicates a name from the registry.
"value": Contains the decimal value of the IANA-assigned value.
"status": Is included only if a registration has been deprecated
or obsoleted. IANA "deprecated" maps to YANG status
"deprecated", and IANA "obsolete" maps to YANG status
"obsolete".
"description": Replicates the description from the registry.
"reference": Replicates the reference(s) from the registry with the
title of the document(s) added.
Unassigned or reserved values are not present in the module.
When the "iana-foo" YANG module is updated, a new "revision"
statement with a unique revision date must be added in front of the
existing revision statements.
IANA is requested to add this note to [reference-to-the-iana-foo-
registry]:
When this registry is modified, the YANG module "iana-foo"
[IANA_FOO_URL] must be updated as defined in RFCXXXX.
5. IANA Considerations
This document does not require any IANA action.
6. Security Considerations
This document does not introduce new concerns other than those
already discussed in Section 15 of [RFC8407].
7. Acknowledgements
This document is triggered by a discussion the author had with Dhruv
Dhody and Jensen Zhang.
Boucadair Expires 24 July 2023 [Page 7]
Internet-Draft IANA-Maintained YANG Modules January 2023
Thanks to Jürgen Schönwälder, Ladislav Lhotka, and Qin Wu for the
discussion and valuable comments. Special thanks to Ladislav Lhotka
for sharing more context that led to the design documented in
[RFC9108].
Thanks to Andy Bierman, Italo Busi, Benoit Claise, Tom Petch, and
Randy Presuhn for the comments. Lou Berger suggested to include more
details about IANA considerations.
8. References
8.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of
Documents Containing YANG Data Models", BCP 216, RFC 8407,
DOI 10.17487/RFC8407, October 2018,
<https://www.rfc-editor.org/info/rfc8407>.
8.2. Informative References
[IANA-YANG-PARAMETERS]
IANA, "YANG Parameters",
<https://www.iana.org/assignments/yang-parameters>.
[IANA_BFD_URL]
"iana-bfd-types YANG Module",
<https://www.iana.org/assignments/iana-bfd-types/iana-bfd-
types.xhtml>.
[IANA_BGP-L2_URL]
"iana-bgp-l2-encaps YANG Module",
<https://www.iana.org/assignments/iana-bgp-l2-encaps/iana-
bgp-l2-encaps.xhtml>.
Boucadair Expires 24 July 2023 [Page 8]
Internet-Draft IANA-Maintained YANG Modules January 2023
[IANA_PW-Types_URL]
"iana-pseudowire-types YANG Module",
<https://www.iana.org/assignments/iana-pseudowire-types/
iana-pseudowire-types.xhtml>.
[RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group
MIB", RFC 2863, DOI 10.17487/RFC2863, June 2000,
<https://www.rfc-editor.org/info/rfc2863>.
[RFC7224] Bjorklund, M., "IANA Interface Type YANG Module",
RFC 7224, DOI 10.17487/RFC7224, May 2014,
<https://www.rfc-editor.org/info/rfc7224>.
[RFC8675] Boucadair, M., Farrer, I., and R. Asati, "A YANG Data
Model for Tunnel Interface Types", RFC 8675,
DOI 10.17487/RFC8675, November 2019,
<https://www.rfc-editor.org/info/rfc8675>.
[RFC8892] Thaler, D. and D. Romascanu, "Guidelines and Registration
Procedures for Interface Types and Tunnel Types",
RFC 8892, DOI 10.17487/RFC8892, August 2020,
<https://www.rfc-editor.org/info/rfc8892>.
[RFC9108] Lhotka, L. and P. Špaček, "YANG Types for DNS Classes and
Resource Record Types", RFC 9108, DOI 10.17487/RFC9108,
September 2021, <https://www.rfc-editor.org/info/rfc9108>.
[RFC9132] Boucadair, M., Ed., Shallow, J., and T. Reddy.K,
"Distributed Denial-of-Service Open Threat Signaling
(DOTS) Signal Channel Specification", RFC 9132,
DOI 10.17487/RFC9132, September 2021,
<https://www.rfc-editor.org/info/rfc9132>.
[RFC9244] Boucadair, M., Ed., Reddy.K, T., Ed., Doron, E., Chen, M.,
and J. Shallow, "Distributed Denial-of-Service Open Threat
Signaling (DOTS) Telemetry", RFC 9244,
DOI 10.17487/RFC9244, June 2022,
<https://www.rfc-editor.org/info/rfc9244>.
[Style] IANA YANG, "IANA YANG",
<https://github.com/llhotka/iana-yang>.
Author's Address
Mohamed Boucadair
Orange
35000 Rennes
France
Boucadair Expires 24 July 2023 [Page 9]
Internet-Draft IANA-Maintained YANG Modules January 2023
Email: mohamed.boucadair@orange.com
Boucadair Expires 24 July 2023 [Page 10]
