Recommendations for Creating IANA-Maintained YANG Modules

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 25 September 2022.¶

Copyright Notice

Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶

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

IANA maintains a set of registries that are key for inexorability. 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.¶

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].¶

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 Registries

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.¶

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, 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 IANA-maintained module may use identities (e.g., [RFC8675]) or typedefs (e.g., [RFC9108]). Such a decision is left to the module designers and should be made based upon specifics related to the intended use of the module. It is RECOMMENDED that the reasoning for the design choice is documented in the companion specification document. For example, [I-D.ietf-dots-telemetry] define IANA-maintained module that use typedefs for the following reason:¶

  "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."

This recommendation takes precedence over the behavior in Section 4.11.1 of [RFC8407] for IANA-maintained modules because the extensibility concern is not applicable for such modules.¶

Designers of IANA-maintained modules MAY supply the full Initial version of the module in the specification document or only a script to be used by IANA (e.g., XSLT 1.0 stylesheet in Appendix A of [RFC9108]).¶

4. IANA Considerations

This document does not require any IANA action.¶

5. Security Considerations

This document does not introduce new concerns other than those already discussed in Section 15 of [RFC8407].¶

6. Acknowledgements

This document is triggered by a discusison the author had with Dhruv Dhody and Jensen Zhang.¶

Author's Address