Recommendations for Creating IANA-Maintained YANG Modules

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.