Recommendations for Creating
IANA-Maintained YANG ModulesOrangeRennes35000Francemohamed.boucadair@orange.comnetmodThis 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.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 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 and YANG modules 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.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. updates the guidelines in . Also, updates and by providing
guidance for writing the IANA considerations for RFCs that specify
IANA-maintained modules.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
when, and
only when, they appear in all capitals, as shown here.This document makes use of the terms defined in Section 2 of .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 .An IANA-maintained module may use identities (e.g., ) or enumerations (e.g., ). 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, defines an IANA-maintained
module that uses enumerations for the following reason: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 ). 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: 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).In addition to the IANA considerations in Section 3.8 of , 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 for IANA-maintained modules with identities and
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 .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 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:Contains
'name-base-identity-defined-in-foo'.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".Replicates the description
from the registry.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" must
be updated as defined in RFCXXXX.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 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:Replicates a name from the
registry.Contains the decimal value of the
IANA-assigned value.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".Replicates the description
from the registry.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" must
be updated as defined in RFCXXXX.This document does not require any IANA action.This document does not introduce new concerns other than those
already discussed in Section 15 of .This document is triggered by a discussion the author had with Dhruv
Dhody and Jensen Zhang.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
.Thanks to Andy Bierman for the comments. Lou Berger suggested to
include more details about IANA considerations.IANA YANGIANA YANGYANG ParametersIANA