Guidance for Managing YANG Modules in RFCs and IANA Registries
draft-ietf-netmod-iana-yang-guidance-02
| Document | Type | Active Internet-Draft (netmod WG) | |
|---|---|---|---|
| Author | Robert Wilton | ||
| Last updated | 2026-04-14 | ||
| Replaces | draft-verdt-iana-yang-guidance | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | WG Document | |
| Document shepherd | (None) | ||
| IESG | IESG state | I-D Exists | |
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-ietf-netmod-iana-yang-guidance-02
NETMOD R. Wilton
Internet-Draft Cisco
Intended status: Informational 14 April 2026
Expires: 16 October 2026
Guidance for Managing YANG Modules in RFCs and IANA Registries
draft-ietf-netmod-iana-yang-guidance-02
Abstract
This document provides guidance to the RFC Editor and IANA on
managing YANG modules in RFCs and IANA registries, ensuring
consistent application of YANG Semantic Versioning rules.
About This Document
This note is to be removed before publishing as an RFC.
The latest revision of this draft can be found at
https://rgwilton.github.io/iana-yang-guidance/draft-ietf-iana-yang-
guidance.html. Status information for this document may be found at
https://datatracker.ietf.org/doc/draft-ietf-netmod-iana-yang-
guidance/.
Discussion of this document takes place on the Network Modelling
Working Group mailing list (mailto:netmod@ietf.org), which is
archived at https://mailarchive.ietf.org/arch/browse/netmod/.
Subscribe at https://www.ietf.org/mailman/listinfo/netmod/.
Source for this draft and an issue tracker can be found at
https://github.com/rgwilton/iana-yang-guidance.
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."
Wilton Expires 16 October 2026 [Page 1]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
This Internet-Draft will expire on 16 October 2026.
Copyright Notice
Copyright (c) 2026 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. For Reviewers of this document . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Conventions and Definitions . . . . . . . . . . . . . . . . . 5
4. Background on YANG Versioning . . . . . . . . . . . . . . . . 6
4.1. YANG Semantic Versioning . . . . . . . . . . . . . . . . 6
4.2. Backwards Compatibility Rules . . . . . . . . . . . . . . 7
4.3. The rev:non-backwards-compatible Extension . . . . . . . 8
4.4. Module Immutability . . . . . . . . . . . . . . . . . . . 9
5. YANG Modules in Documents Being Published as RFCs . . . . . . 9
5.1. Core Requirements . . . . . . . . . . . . . . . . . . . . 9
5.2. Workflow Steps . . . . . . . . . . . . . . . . . . . . . 10
5.2.1. Step 1: IESG Approval with Pre-Release Version . . . 10
5.2.2. Step 2: RFC Editor Processing . . . . . . . . . . . . 10
5.2.3. Step 3: Finalizing the Module Version . . . . . . . . 11
5.2.4. Step 4: Validate the Module . . . . . . . . . . . . . 12
5.2.5. Step 5: IANA Delay of Publication . . . . . . . . . . 12
5.2.6. Step 6: Coordinated Publication . . . . . . . . . . . 12
6. IANA-Maintained YANG Modules . . . . . . . . . . . . . . . . 13
6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 13
6.2. Characteristics of IANA-Maintained Modules . . . . . . . 13
6.3. Rules Applicable to IANA-Maintained Modules . . . . . . . 14
6.3.1. Special YANG Considerations for Deprecated Registry
Entries . . . . . . . . . . . . . . . . . . . . . . . 15
6.4. Process for Updating IANA-Maintained YANG Modules . . . . 15
6.4.1. Step 1: Follow RFC-Defined Rules . . . . . . . . . . 15
6.4.2. Step 2: Identify the Registry Change . . . . . . . . 16
6.4.3. Step 3: Apply Equivalent Changes to the YANG
Module . . . . . . . . . . . . . . . . . . . . . . . 16
6.4.4. Step 4: Use Pyang Tooling to Check/Recommend Next
Version . . . . . . . . . . . . . . . . . . . . . . . 16
Wilton Expires 16 October 2026 [Page 2]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
6.4.5. Step 5: Validate the Module . . . . . . . . . . . . . 17
6.4.6. Step 6: Seek additional help if Needed . . . . . . . 17
6.4.7. Step 7: Publish the Updated Module . . . . . . . . . 17
6.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 17
7. Seeking Additional Guidance . . . . . . . . . . . . . . . . . 17
7.1. When to Seek Guidance . . . . . . . . . . . . . . . . . . 18
7.2. How to Seek Guidance . . . . . . . . . . . . . . . . . . 18
7.3. Example Request . . . . . . . . . . . . . . . . . . . . . 19
8. Operational Considerations . . . . . . . . . . . . . . . . . 19
9. Security Considerations . . . . . . . . . . . . . . . . . . . 20
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
11.1. Normative References . . . . . . . . . . . . . . . . . . 21
11.2. Informative References . . . . . . . . . . . . . . . . . 22
Appendix A. Available Tooling . . . . . . . . . . . . . . . . . 23
A.1. YANG Validation Tools . . . . . . . . . . . . . . . . . . 23
A.1.1. pyang . . . . . . . . . . . . . . . . . . . . . . . . 24
A.1.2. yanglint . . . . . . . . . . . . . . . . . . . . . . 27
A.1.3. YANG Catalog Tools . . . . . . . . . . . . . . . . . 28
A.2. Tool Limitations . . . . . . . . . . . . . . . . . . . . 28
Appendix B. Summary of IANA Registry Action Scenarios . . . . . 29
B.1. Quick Reference Table . . . . . . . . . . . . . . . . . . 29
B.2. Detailed Common Scenarios . . . . . . . . . . . . . . . . 31
B.2.1. Scenario 1: Adding a New Registry Entry . . . . . . . 32
B.2.2. Scenario 2: Updating References . . . . . . . . . . . 33
B.2.3. Scenario 3: Deprecating a Registry Entry . . . . . . 34
B.2.4. Scenario 4: Obsoleting a Registry Entry . . . . . . . 36
B.2.5. Scenario 5: Removing a Registry Entry Completely . . 38
B.2.6. Scenario 6: Renaming a Registry Entry . . . . . . . . 39
B.2.7. Scenario 7: Changing a Value Number . . . . . . . . . 40
B.2.8. Scenario 8: Updating Description (Clarification) . . 41
B.2.9. Scenario 9: Updating Description (Semantic Change) . 42
B.2.10. Scenario 10: Handling Errata . . . . . . . . . . . . 43
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 44
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 44
1. For Reviewers of this document
*RFC Editor - please delete this section before publication*
This draft should be carefully reviewed by:
* IANA and RFC Editor to check that they agree with the workflows
* OPS ADs & IESG (if needed) that they agree that the IETF should
delay publishing YANG modules in approved internet drafts until
after the RFC Editor has had the opportunity to review and amend
the text.
Wilton Expires 16 October 2026 [Page 3]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
* YANG Doctors and NETMOD to ensure that they are happy with the
requirements being placed upon them.
2. Introduction
YANG [RFC6020] [RFC7950] modules are used to model network management
data, protocol RPCs [RFC8526], and even abstract data structures
[RFC8791]. The IETF publishes YANG modules as part of RFCs, and the
Internet Assigned Numbers Authority (IANA) maintains YANG modules
that are derived from IANA registries (a.k.a. IANA-maintained YANG
modules [RFC9907]). Both processes require careful attention to
module versioning and the timing of publication to ensure that
implementations can correctly assess module version compatibility
when modules are updated.
This document provides informational guidance to both the RFC Editor
and IANA for managing YANG modules in two distinct scenarios:
1. *Managing YANG Modules in RFCs*: When documents containing
normative YANG modules are approved by the IESG and processed for
publication as RFCs, both the RFC Editor and IANA have
responsibilities to ensure that modules are correctly versioned
and published.
2. *Managing IANA-Maintained YANG Modules*: When IANA registries are
updated, any YANG modules derived from those registries must be
updated accordingly with proper versioning.
This document describes recommended practices and procedures that
reflect current consensus within the NETMOD working group and the
IETF operations and management community. While following this
guidance will help ensure consistent and correct handling of YANG
modules, specific situations may require consultation with the YANG
Doctors (as described in Section 7).
*Note:* In addition to the guidance detailed in this document,
there is a broader, ongoing discussion within the IETF community
around the processes and responsibilities for managing YANG
modules in RFCs. For further information and the latest
proposals, see [I-D.boucadair-veloce-yang]. The recommendations
and operational practices described here may be revised in the
future to reflect outcomes from that work.
The procedures and classifications in this document are drawn from
text and general guidance on the following IETF specifications:
* [RFC9907] - Provides general guidelines for IETF YANG module
authors. It also includes guidance for IANA.
Wilton Expires 16 October 2026 [Page 4]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
* [I-D.ietf-netmod-yang-module-versioning] - Defines updated YANG
module revision handling, including rules for backwards-compatible
and non-backwards-compatible changes.
* [I-D.ietf-netmod-yang-semver] - Defines YANG Semantic Versioning
(YANG Semver) for YANG modules.
* [I-D.ietf-netmod-yang-module-filename] - Defines filename
conventions for YANG modules versioned using YANG Semver.
3. Conventions and Definitions
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 uses the following terminology from
[I-D.ietf-netmod-yang-module-versioning]:
*Backwards-Compatible (BC) Change* A change to a YANG module that
conforms to the backwards-compatible update rules defined in
Section 3.1.1 of [I-D.ietf-netmod-yang-module-versioning]. BC
changes require incrementing the MINOR version number.
*Non-Backwards-Compatible (NBC) Change* A change to a YANG module
that does not conform to the backwards-compatible update rules
defined in Section 3.1.2 of
[I-D.ietf-netmod-yang-module-versioning]. NBC changes require
incrementing the MAJOR version number and adding the rev:non-
backwards-compatible extension statement within the revision
statement in the YANG module.
This document uses the following terminology from
[I-D.ietf-netmod-yang-semver]:
*YANG Semver* YANG Semantic Versioning - a version identifier in the
format _MAJOR.MINOR.PATCH_COMPAT_ that indicates the compatibility
level of a YANG module, as defined in
[I-D.ietf-netmod-yang-semver].
*Editorial Change* A change to a YANG module that does not affect
the semantic meaning or functionality of the module. Editorial
changes only require incrementing the PATCH version number, as
described in section 4.4 of [I-D.ietf-netmod-yang-semver].
In addition, this document uses this terms from [RFC9907]:
Wilton Expires 16 October 2026 [Page 5]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
*IANA-maintained module* A YANG module that is maintained by IANA
and has an IANA registry associated with it (e.g., "iana-tunnel-
type" [RFC8675] or "iana-pseudowire-types" [RFC9291]).
Once an IANA-maintained YANG module is initialized, new values are
not directly added to the module. These values are instead added
to the companion registry, a new version of the IANA-maintained is
generated based on the changes made to the registry.
*IETF module* A YANG module that is published by the IETF and that
is not maintained by IANA.
4. Background on YANG Versioning
4.1. YANG Semantic Versioning
YANG Semantic Versioning (YANG Semver) [I-D.ietf-netmod-yang-semver]
uses a version identifier in the format MAJOR.MINOR.PATCH (with an
optional _COMPAT suffix for branched development):
* *MAJOR* version increments indicate non-backwards-compatible (NBC)
changes, with _MINOR_ and _PATCH_ fields reset to 0.
* *MINOR* version increments indicate backwards-compatible (BC)
additions, with the _PATCH_ field reset to 0.
* *PATCH* version increments indicate editorial or documentation-
only changes.
* *_COMPAT* is used for branched development trees and is not
applicable to normative modules published by the IETF or IANA-
maintained modules.
If an update to a YANG module contains a mix of changes, then the
version number is updated as per the most impactful change. For
example, if a change included both backwards-compatible feature
additions and editorial changes then the _MINOR_ version field is
incremented and the _PATCH_ version field is set to 0, e.g., as per
the second example below. If in doubt as to which category a
particular change fits into, it is always better to err on the side
of caution and choose the more significant version change.
For example, if a published IETF YANG module is at version _1.2.3_:
* An editorial only change would update it to _1.2.4_
* A backwards-compatible addition would update it to _1.3.0_
Wilton Expires 16 October 2026 [Page 6]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
* A non-backwards-compatible change would update it to _2.0.0_.
Pre-release versions (versions with MAJOR = 0, e.g., "0.2.0", or with
a pre-release suffix, e.g., "1.3.0-04") indicate modules that have
not completed the IETF standardization process and whose revision
content is subject to change in non-backwards-compatible ways without
corresponding changes to the major version number. Published IETF
and IANA-maintained YANG modules should always be at version "1.0.0"
or later, and should never include a pre-release suffix. The initial
published version should be "1.0.0".
4.2. Backwards Compatibility Rules
The rules that determine whether a change to a YANG module is
backwards-compatible or non-backwards-compatible are defined in
Section 3.1 of [I-D.ietf-netmod-yang-module-versioning]. These rules
refine and extend the update rules specified in Section 11 of
[RFC7950].
Section 3.1.1 of [I-D.ietf-netmod-yang-module-versioning] defines
backwards-compatible changes; examples include:
* Adding new schema nodes (e.g., new enum values, identities, leafs,
containers)
* Adding or updating "description" and "reference" statements
(provided the semantic meaning is unchanged)
* Changing the status of a schema node from "current" to
"deprecated" (e.g., by adding a status deprecated; statement)
Section 3.1.2 of [I-D.ietf-netmod-yang-module-versioning] defines
non-backwards-compatible changes; examples include:
* Removing schema nodes (unless they already have status "obsolete")
* Changing the status of a schema node from "current" or
"deprecated" to "obsolete"
* Renaming schema nodes or changing their identifiers
* Changing data types in ways that alter syntax or semantics
* Changing numeric values assigned to enumerations
* Modifying "description" statements in ways that change semantic
meaning or behavior
Wilton Expires 16 October 2026 [Page 7]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
In addition, Section 4.4 of [I-D.ietf-netmod-yang-semver] defines
editorial changes as the subset of backwards-compatible changes that
have no impact on the semantics or syntax of a YANG module, such as:
* Corrections to comments, descriptions, or references that do not
change the semantic meaning
* Formatting improvements such as whitespace or indentation changes
* Updates to contact information or copyright statements
4.3. The rev:non-backwards-compatible Extension
The YANG module versioning framework
[I-D.ietf-netmod-yang-module-versioning] defines the "rev:non-
backwards-compatible" extension statement. This extension MUST be
added as a substatement of a revision statement whenever that
revision contains non-backwards-compatible changes relative to the
previous revision.
The following example illustrates this extension in use. In the
example, an identity 'foo' was added in version 1.3.0, but was
subsequently renamed to 'bar' in version 2.0.0. Since renaming is a
non-backwards-compatible change, the major version number is
incremented and the rev:non-backwards-compatible extension is
included in the revision statement in version 2.0.0 of the YANG
module:
revision 2025-11-15 {
ysv:version "2.0.0";
rev:non-backwards-compatible;
description
"Renamed identity 'foo' to 'bar'.";
}
revision 2025-06-01 {
ysv:version "1.3.0";
description
"Added identity 'foo'.";
}
...
Figure 1: Revision history example from a YANG module
Wilton Expires 16 October 2026 [Page 8]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
4.4. Module Immutability
A fundamental principle of YANG module versioning is that once a
module revision is published with a specific revision date and
version number, its content is immutable (much like an RFC is). The
published content of that revision MUST NOT change. Any change to
the module content requires publishing a new revision with a new
revision date and an updated YANG Semver.
This immutability principle has important implications:
* Modules in Internet-Drafts MUST use pre-release versions (e.g.,
0.1.0 or 2.0.0-draft-name) to indicate that the content may still
change.
* Once a document is approved by the IESG and has been processed by
the RFC Editor, then the module version MUST be updated to the
correct release version (e.g., 1.0.0 or 2.0.0) before publication
in an RFC or made available in the IANA YANG Module Names registry
[IANA-YANG-PARAMETERS].
* IANA-maintained YANG modules MUST publish a new YANG module
revision any time IANA registry changes require YANG module
updates.
5. YANG Modules in Documents Being Published as RFCs
This section describes the workflow and responsibilities for managing
YANG modules in documents that have been approved by the IESG and are
being processed for publication as RFCs. Both the RFC Editor and
IANA have roles in this process.
5.1. Core Requirements
All new normative YANG modules published by the RFC Editor or
maintained by IANA MUST meet the following requirements:
1. *YANG Semver Version*: Every normative module MUST include a
semantic version number using the ysv:version statement in its
most recent revision. The version MUST be correct relative to
any previous version of the same module published either by the
RFC editor or on the IANA website.
2. *NBC Extension for NBC Changes*: If the normative module contains
non-backwards-compatible changes relative to the previously
published version, the revision statement MUST include the
rev:non-backwards-compatible extension.
Wilton Expires 16 October 2026 [Page 9]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
In current tooling, general enforcement of this rule is performed
by update comparison checks such as the --check-update-from
option to pyang. Please also note, the pyang checks provided by
the --ietf option only provide a narrower validation based on
revision-to-revision YANG Semver major-version changes.
3. *Revision Immutability*: A published YANG module with a specific
revision date and version number is immutable. Its content MUST
NOT change without also changing the revision date and version
number. For this reason, modules in Internet-Drafts use pre-
release versions (e.g., versions with MAJOR = 0 such as 0.1.0, or
versions with a pre-release suffix such as 2.0.0-05, where the
-05 is the Internet Draft number where the YANG module was
updated) to indicate that content may still change before final
publication.
4. *RFC Code Markers*: Normative YANG modules in RFCs MUST be
properly marked with <CODE BEGINS> and <CODE ENDS> markers (or
equivalent in the source format) to enable automated extraction
per Section 3.2 of [RFC9907]. The markers MUST include the
filename following the conventions in
[I-D.ietf-netmod-yang-module-filename].
5.2. Workflow Steps
The following steps describe the coordinated process between the RFC
Editor and IANA for handling YANG modules during RFC publication:
5.2.1. Step 1: IESG Approval with Pre-Release Version
When a document is approved by the IESG, any normative YANG modules
it contains typically have pre-release version numbers (e.g., 0.4.0,
1.1.0-03, or 2.0.0-07). These pre-release versions indicate that the
module content may still be subject to editorial changes during RFC
Editor processing.
5.2.2. Step 2: RFC Editor Processing
During RFC Editor processing, the RFC Editor may make editorial
changes to the YANG module, such as:
* Improving description text for clarity without changing semantic
meaning
* Updating references to use final RFC numbers instead of draft
names
* Correcting typographical errors
Wilton Expires 16 October 2026 [Page 10]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
* Standardizing formatting and style
These editorial changes are appropriate and expected. Consistent
with the editing practices when preparing edited RFCs, the RFC Editor
SHOULD:
* Coordinate with document authors regarding any substantive
changes.
* Ensure that only editorial changes (as defined in Section 4) are
made without author consultation.
* For modules that have previously been published, e.g., updated
YANG modules in -bis documents:
- If more significant changes are needed that might be backwards-
compatible or non-backwards-compatible, consult with the
authors to determine the correct version number and whether the
rev:non-backwards-compatible extension is required.
* Ensure that the final module is correctly formatted (e.g., by
running Appendix A.1.1.2).
5.2.3. Step 3: Finalizing the Module Version
Before publication, the module version MUST be updated from the pre-
release version to a release version. The RFC Editor, in
coordination with the document authors:
* Updates the revision date to reflect the date of the final
revision.
* Updates the version to remove pre-release indicators (e.g., 0.1.0
→ 1.0.0, or 1.1.0-<draft-num> → 1.1.0).
* For modules that have previously been published, e.g., updated
YANG modules in -bis documents:
- Uses pyang (Appendix A.1.1.3) to compare the candidate module
against the previously published version and obtain a
recommended next YANG Semver, subject to the tool limitations
described in Appendix A.1.1.3 and Appendix A.2. Tooling is not
infallible, so if the suggested version from the tooling is
unexpected then please reach out for additional guidance, as
per Section 7.
Wilton Expires 16 October 2026 [Page 11]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
- Checks, and if necessary adds, the rev:non-backwards-compatible
extension if NBC changes have occurred since the previous
publication.
5.2.4. Step 4: Validate the Module
Normative YANG modules are expected to be provided to the RFC Editor
for publication already passing validation (pyang and yanglint).
However, it is possible that mistakes could be introduced when
editing a YANG module so validation should be re-run to ensure that
IETF does not publish invalid YANG modules.
After all updates are completed, or as updates are made, and after
any formatting, then validation tools MUST be run over the resultant
module to ensure that there are no warnings or errors. pyang
validation (Appendix A.1.1.1) MUST be performed, and it is
RECOMMENDED that yanglint (Appendix A.1.2) validation is also
performed.
If the tools return any warnings or errors then the authors should
help fix them, potentially seeking additional guidance if required,
as per Section 7.
If further changes are made, then for previously published modules,
the step 3 versioning check MUST be re-run to ensure that the module
version is still correct.
5.2.5. Step 5: IANA Delay of Publication
IANA SHOULD delay publishing a normative YANG module to the IANA YANG
Parameters registry until the RFC Editor has completed editing the
module. This coordination ensures that:
* The IANA-published version matches the RFC-published version
exactly
* No discrepancies exist between the two authoritative sources
* The module reference to the RFC (if present) is correct
5.2.6. Step 6: Coordinated Publication
Once the RFC Editor has finalized the module:
* The RFC is published with the final module content
* IANA publishes the module to the IANA YANG Parameters registry at
approximately the same time
Wilton Expires 16 October 2026 [Page 12]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
* The module filename follows the conventions in
[I-D.ietf-netmod-yang-module-filename]
* IANA registers the module in the "YANG Module Names" registry if
it is not already registered
6. IANA-Maintained YANG Modules
This section describes the process for IANA to update and publish
YANG modules that are maintained by IANA and derived from IANA
registries.
6.1. Overview
Some IANA registries have corresponding YANG modules that represent
registry contents in a machine-readable format, and that are
published at [IANA-YANG-PARAMETERS]. Examples include:
* *iana-if-type.yang* - derived from the Interface Types (ifType)
registry [iana-iftype-registry]
* *iana-routing-types.yang* - derived from Address Family Numbers
[iana-afnum-registry] and SAFI Parameters [iana-safi-registry]
registries
* *iana-bgp-types.yang* - derived from BGP Parameters registries
[iana-bgp-parameters]
When these registries are updated, the corresponding YANG modules
MUST be updated accordingly by IANA, following the same versioning
rules described in Section 4.
6.2. Characteristics of IANA-Maintained Modules
IANA-maintained YANG modules typically:
* Have names starting with "iana-"
* Contain primarily enumeration typedefs or identity definitions
that are derived from registry entries
* Are updated more frequently than IETF-defined modules
* Follow a linear version history without branching
* Have a much simpler structure than general-purpose YANG modules,
which simplifies classification of changes
Wilton Expires 16 October 2026 [Page 13]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
Because IANA-maintained YANG modules are always expected to follow a
linear version history without branching, the __COMPAT_ modifier
defined in [I-D.ietf-netmod-yang-semver] is not needed or used for
these modules. The __COMPAT_ modifier is only required for non-
linear branched histories of YANG module versions. Therefore, only
the _MAJOR.MINOR.PATCH_ elements of YANG Semver need be considered
for IANA-maintained modules.
6.3. Rules Applicable to IANA-Maintained Modules
IANA-maintained YANG modules typically contain only enumerations
(enum) and identity definitions, as they represent simple registry
mappings. Hence, the most relevant compatibility rules for these
modules are:
*Editorial Changes:*
* Clarifying "description" statements without changing meaning
* Adding or updating "reference" statements
* Fixing typographical errors in description text
* Updating contact information
* Formatting improvements
*Backwards-Compatible Changes:*
* Adding a new enum value or identity
* Changing status from "current" to "deprecated"
* Removing schema nodes that already have status "obsolete"
*Non-Backwards-Compatible Changes:*
* Removing an enum value or identity (unless status is "obsolete")
* Changing status from "current" or "deprecated" to "obsolete"
* Renaming an enum or identity
* Changing the numeric value assigned to an enum
* Modifying "description" statements in a way that changes the
semantic meaning
Wilton Expires 16 October 2026 [Page 14]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
*Important*: If multiple updates to the registry are made at the same
time resulting in a single update to the IANA maintained YANG module
then the new module version number is decided by the impact of the
most significant change.
6.3.1. Special YANG Considerations for Deprecated Registry Entries
IANA registries and YANG modules use the term _deprecated_
differently:
* In IANA registries, deprecated generally means the value SHOULD
NOT be used for new deployments.
* In YANG modules, status deprecated means the definition is still
supported (including for new deployments) but it is expected to be
obsoleted (or removed) in a future module version.
To avoid confusion, when an IANA registry entry is marked deprecated,
the corresponding enum or identity description SHOULD include
indicate that the base IANA registry entry is deprecated and
therefore the entry SHOULD NOT be used. I.e., the following sentence
SHOULD be added to the end of the enum/identity description: This
value is deprecated in the base IANA registry which means that its
use is NOT RECOMMENDED.
6.4. Process for Updating IANA-Maintained YANG Modules
When a change is made to an IANA registry that has a corresponding
YANG module, it is recommended that IANA update the module following
these steps:
6.4.1. Step 1: Follow RFC-Defined Rules
First, consult the RFC that defines the IANA registry and its
associated YANG module. That RFC may specify:
* Specific rules for how registry entries map to YANG constructs
* Guidance on when and how to update the module
* Contact information for expert reviewers
* Special considerations for the particular registry
Always follow the specific guidance in the RFC that created the
registry and module.
Wilton Expires 16 October 2026 [Page 15]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
6.4.2. Step 2: Identify the Registry Change
Determine exactly what changed in the registry:
* Was a new entry added?
* Was an existing entry modified (description, reference, status)?
* Was an entry deprecated or obsoleted?
* Was an entry removed?
* Were multiple changes made simultaneously?
6.4.3. Step 3: Apply Equivalent Changes to the YANG Module
Update the YANG module to reflect the registry changes. For IANA-
maintained modules, this typically involves:
* Adding a new enum value or identity for new registry entries
* Updating description or reference statements for modified entries
* Changing status statements for deprecated or obsoleted entries
* Removing entries only if they are obsolete or if the defining RFC
specifies removal
* Add a revision statement (using the current date) describing the
change, and a reference, if appropriate.
* _(Optional) include a version statement with the anticipated new
version and a rev:non-backwards-compatible statement if it is a
non-backwards-compatible change._
* _(Optional) Use tooling to format the YANG module, as described in
Appendix A.1.1.2._
6.4.4. Step 4: Use Pyang Tooling to Check/Recommend Next Version
Use the tools described in Appendix A.1.1.3 to recommend or check (if
provided in step 3) the next module version. Be aware of the tooling
limitations, as per Appendix A.2, and sanity check that the version
recommended by the tooling is what is expected based on the changes.
* Add or update the version statement with the correct version
Wilton Expires 16 October 2026 [Page 16]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
* Add rev:non-backwards-compatible extension if NBC changes have
occurred
6.4.5. Step 5: Validate the Module
Use validation tools, as per Appendix A.1.1.1, to ensure the updated
module is syntactically correct. Since these modules are simple,
just checking with the pyang tool is sufficient but
yanglint(Appendix A.1.2) may be used as an alternative.
6.4.6. Step 6: Seek additional help if Needed
In most cases, the classification will be straightforward. However,
if any of the following apply, IANA should seek additional guidance
as described in Section 7:
* The change classification is unclear
* The tool output is unexpected or contradictory
* Description changes, where it is not obvious if they change
semantic meaning
* Any situation not covered by the guidance above, or examples in
Appendix B
6.4.7. Step 7: Publish the Updated Module
Once the module is validated and the version is confirmed:
* Publish the updated module to the IANA website
* Publish the module using two URLs, one using the version and one
using the revision date: <module-name>#<version>.yang and <module-
name>@<revision-date>.yang, as per
[I-D.ietf-netmod-yang-module-filename].
* Update any relevant registries or indexes
* Ensure the new version is discoverable and accessible
6.5. Examples
Detailed examples of common scenarios (adding entries, updating
references, deprecating entries, etc.) are given in Appendix B.
7. Seeking Additional Guidance
Wilton Expires 16 October 2026 [Page 17]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
7.1. When to Seek Guidance
The RFC Editor and IANA should contact the YANG Doctors in the
following situations:
1. *Classification Uncertainty* - When it's unclear whether a change
is NBC, BC, or Editorial
2. *Tool Disagreement* - When validation tools give unexpected or
contradictory results
3. *Description Changes* - When it is unclear whether a description
update alters semantic meaning
4. *Unusual Situations* - Any scenario not clearly covered in this
document
5. *Registry Restructuring* - Major changes to how a registry is
organized
6. *RFC Editor Processing* - When RFC Editor changes may go beyond
editorial scope
7.2. How to Seek Guidance
Email the YANG Doctors mailing list and the Operations and Management
Area Directors (OPS ADs):
* *Email*: yang-doctors@ietf.org & ops-ads@ietf.org
* *Purpose*: Technical review and guidance on YANG module
versioning.
* *Response Time*: Typically 1-2 weeks
When emailing, please include:
* Description of the change or situation
* The affected YANG module and relevant excerpts
* Your proposed classification and version change
* Specific questions or concerns
* Any relevant tool output
* An indication if an urgent reply is required.
Wilton Expires 16 October 2026 [Page 18]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
The expectation is that the YANG Doctors should reply to the request
within the time frame given above, but if a reply isn't forthcoming
then please escalate via the OPS ADs.
7.3. Example Request
<BEGIN TEMPLATE TEXT>
Subject: YANG Versioning Question - iana-if-type Update
Dear YANG Doctors,
I need guidance on classifying a change to the iana-if-type module.
Change Description:
The Interface Types registry has updated the description for
interface type 6 (ethernet) to clarify that it includes both
10BASE-T and 100BASE-T variants.
Proposed YANG Change:
Update the description statement for the "ethernet" enum to
include the clarification.
Question:
Should this be classified as Editorial (PATCH increment) since
it's clarifying existing behavior, or as BC (MINOR increment)
because it's adding new information?
The old description said: "Ethernet interface"
The new description says: "Ethernet interface, including
10BASE-T and 100BASE-T variants"
Current module version: 1.5.0
Proposed version: 1.5.1 (if Editorial) or 1.6.0 (if BC)
Thank you for your guidance.
<END TEMPLATE TEXT>
8. Operational Considerations
This entire document provides operational guidance for the RFC Editor
and IANA on how to process and publish YANG modules. The procedures
described in Section 5 and Section 6 are designed to ensure
consistent and correct versioning of YANG modules across all IETF and
IANA publications.
Wilton Expires 16 October 2026 [Page 19]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
Correct versioning is critical because consumers of YANG modules rely
on the semantic version number to understand the compatibility and
risk associated with updating to a new module version:
* *PATCH version increments* signal that only editorial changes have
been made, indicating very low risk for updates
* *MINOR version increments* signal backwards-compatible additions,
indicating that existing implementations will continue to work but
new features are available
* *MAJOR version increments* signal non-backwards-compatible
changes, indicating that implementations must carefully evaluate
the impact before updating
Following the guidance in this document helps ensure that version
numbers accurately communicate these compatibility expectations to
the YANG module consumer community.
When uncertain about the correct classification or version for a
module, the operational recommendation is to choose the more
conservative option:
* If uncertain between editorial and backwards-compatible, choose
backwards-compatible (MINOR rather than PATCH)
* If uncertain between backwards-compatible and non-backwards-
compatible, choose non-backwards-compatible (MAJOR rather than
MINOR, and include the NBC extension)
This conservative approach ensures that consumers are appropriately
warned about potential compatibility implications, even if the actual
risk turns out to be lower than indicated.
9. Security Considerations
This document gives instructions to IANA on how to handle YANG
modules that are published in RFCs and also YANG modules that are
derived from IANA registries.
Incorrect interpretation of this document could cause incorrect
handling or versioning of IANA-maintained YANG modules.
Wilton Expires 16 October 2026 [Page 20]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
This document recommends the usage of various tools. Bugs or attacks
on these tools could cause the tools to give incorrect or misleading
guidance. In all cases, secondary evaluation of output of the tools
should be performed to confirm that they are giving the anticipated
results. The _YANG Doctors_ or _Operations and Management Area
Directors_ can also be contacted for further advice, if required.
10. IANA Considerations
This document provides operational guidance to IANA and the RFC
Editor for managing YANG modules. It does not require IANA to create
or modify any registries, nor does it define any new registration
procedures.
The guidance in this document is intended to clarify and standardize
how IANA processes YANG modules in the "YANG Module Names" registry
[IANA-YANG-PARAMETERS] and how IANA maintains YANG modules derived
from IANA registries.
IANA should follow the procedures described in Section 5 when
processing YANG modules from RFCs and the procedures described in
Section 6 when updating IANA-maintained YANG modules.
11. References
11.1. Normative References
[I-D.ietf-netmod-yang-module-filename]
Andersson, P., "YANG module file name convention", Work in
Progress, Internet-Draft, draft-ietf-netmod-yang-module-
filename-07, 2 April 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
yang-module-filename-07>.
[I-D.ietf-netmod-yang-module-versioning]
Wilton, R., Rahman, R., Lengyel, B., Clarke, J., and J.
Sterne, "Updated YANG Module Revision Handling", Work in
Progress, Internet-Draft, draft-ietf-netmod-yang-module-
versioning-15, 18 October 2025,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
yang-module-versioning-15>.
[I-D.ietf-netmod-yang-semver]
Clarke, J., Wilton, R., Rahman, R., Lengyel, B., Sterne,
J., and B. Claise, "YANG Semantic Versioning", Work in
Progress, Internet-Draft, draft-ietf-netmod-yang-semver-
25, 13 April 2026, <https://datatracker.ietf.org/doc/html/
draft-ietf-netmod-yang-semver-25>.
Wilton Expires 16 October 2026 [Page 21]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
[IANA-YANG-PARAMETERS]
IANA, "YANG Parameters", n.d.,
<https://www.iana.org/assignments/yang-parameters/yang-
parameters.xhtml>.
[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/rfc/rfc2119>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
<https://www.rfc-editor.org/rfc/rfc6020>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/rfc/rfc7950>.
[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/rfc/rfc8174>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/rfc/rfc8340>.
[RFC9907] Bierman, A., Boucadair, M., Ed., and Q. Wu, "Guidelines
for Authors and Reviewers of Documents Containing YANG
Data Models", BCP 216, RFC 9907, DOI 10.17487/RFC9907,
March 2026, <https://www.rfc-editor.org/rfc/rfc9907>.
11.2. Informative References
[I-D.boucadair-veloce-yang]
Boucadair, M., "YANG deVELpment PrOCEss & maintenance
(VELOCE)", Work in Progress, Internet-Draft, draft-
boucadair-veloce-yang-05, 18 September 2025,
<https://datatracker.ietf.org/doc/html/draft-boucadair-
veloce-yang-05>.
[I-D.ietf-netmod-yang-schema-comparison]
Andersson, P., Wilton, R., and M. Vaško, "YANG Schema
Comparison", Work in Progress, Internet-Draft, draft-ietf-
netmod-yang-schema-comparison-06, 15 February 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
yang-schema-comparison-06>.
Wilton Expires 16 October 2026 [Page 22]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
[iana-afnum-registry]
IANA, "Address Family Numbers", n.d.,
<https://www.iana.org/assignments/address-family-numbers>.
[iana-bgp-parameters]
IANA, "BGP Parameters", n.d.,
<https://www.iana.org/assignments/bgp-parameters>.
[iana-iftype-registry]
IANA, "Interface Types (ifType) Registry", n.d.,
<https://www.iana.org/assignments/smi-numbers>.
[iana-safi-registry]
IANA, "SAFI Parameters", n.d.,
<https://www.iana.org/assignments/safi-parameters>.
[RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "NETCONF Extensions to Support the Network
Management Datastore Architecture", RFC 8526,
DOI 10.17487/RFC8526, March 2019,
<https://www.rfc-editor.org/rfc/rfc8526>.
[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/rfc/rfc8675>.
[RFC8791] Bierman, A., Björklund, M., and K. Watsen, "YANG Data
Structure Extensions", RFC 8791, DOI 10.17487/RFC8791,
June 2020, <https://www.rfc-editor.org/rfc/rfc8791>.
[RFC9291] Boucadair, M., Ed., Gonzalez de Dios, O., Ed., Barguil,
S., and L. Munoz, "A YANG Network Data Model for Layer 2
VPNs", RFC 9291, DOI 10.17487/RFC9291, September 2022,
<https://www.rfc-editor.org/rfc/rfc9291>.
Appendix A. Available Tooling
This appendix describes tooling available to assist the RFC Editor
and IANA in validating and versioning YANG modules. The tools and
capabilities described here reflect the state of tooling as of the
publication of this document. Tool capabilities are expected to
evolve over time, and newer or improved tools may become available.
The NETMOD working group and YANG Doctors can provide updated
guidance on current best practices for tooling.
A.1. YANG Validation Tools
Wilton Expires 16 October 2026 [Page 23]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
A.1.1. pyang
*Purpose*: pyang is a comprehensive YANG validator and converter tool
that can validate syntax, check for backwards-compatible violations,
and generate documentation.
*Primary Use Cases*:
1. Validating YANG module syntax and compliance with IETF
conventions
2. Formatting YANG modules in a consistent way prior to publication
3. Suggesting proposed next version when updating a YANG module
4. Generating tree diagrams for documentation
*Installation*: pyang is available via PyPI (pip install pyang) or
from https://github.com/mbj4668/pyang (https://github.com/mbj4668/
pyang). It is recommended to periodically check and update the
version to pick up bugfixes and new functionality (which could
include stricter checks).
*Note to RFC Editor and reviewers, some of the tooling enhancements
documented here are not yet been merged into the master pyang
repository, so depending on publication timing we need to add further
references.*
To ensure that pyang correctly processes the YANG files, then the
correct versions of any YANG module dependencies must also be used,
this is often the latest version of the published YANG modules, but
if a draft contains a set of YANG modules, or if there are set of
drafts with YANG modules being published together then all the YANG
modules in those drafts MUST be extracted together and validated.
These dependent YANG modules can either be stored in the same
directory as the YANG module being validated/checked, or they can be
stored in a separate directory and passed using the -p argument to
provide a path to the directory.
A.1.1.1. Basic YANG Syntax Validation
This command below validates the module syntax and checks compliance
with IETF-specific conventions. The output will show any errors or
warnings. IETF and IANA modules SHOULD have no errors or warnings
before publication.
pyang --ietf --strict --max-line-length=69 -Werror -p <dep-module-directory> ietf-module-name.yang
Wilton Expires 16 October 2026 [Page 24]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
A.1.1.2. Consistent formatting of YANG modules
Pyang can be used to reformat a YANG file, particularly fixing line
length issues and correcting any indentation mistakes. Some complex
expressions, e.g., must, when and path statements may not be
automatically split to the correct line length and may need to be
done manually. Running the basic syntax validation command on the
output file indicates whether any further manual line folding is
required.
pyang -f yang --yang-line-length=69 --yang-canonical -Werror -p <dep-module-directory> -o <output-file> <treeOpts> ietf-module-name.yang
A.1.1.3. Suggesting proposed next version when updating a YANG module
Pyang can be used to compare the changes between two YANG module
versions and either validate that a suitable next version number has
been used, or to suggest what the appropriate next version should be,
or if further manual checks should be performed, e.g., for changes to
description statements.
If the new module version already includes a version statement for
the latest revision then pyang can perform a limited set of policy
checks against the declared version. In the current implementation,
this is not a full exact-match validation for every possible declared
version. Instead, the tool reports specific cases where the declared
version is inconsistent with detected known NBC changes or with
certain possible-NBC outcomes. Otherwise, if the latest revision
does not contain a version statement then it will suggest the new
version that should be used.
If the previous revision being compared does not contain a
ysv:version statement, then the tool assumes an old version of 1.0.0
and reports that assumption explicitly in its output.
If the old version is itself a pre-release form, for example with
MAJOR = 0 or with pre-release metadata, then the current
implementation may be unable to recommend a next release version
automatically.
pyang --check-update-semver --check-update-from module-name@old-version.yang module-name@new-version.yang
*Interpreting Tool Output*
The command output:
* prints the suggested next YANG Semver, when the tool can determine
one, based on the changes. It may print:
Wilton Expires 16 October 2026 [Page 25]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
- ASSUMED-OLD-YANG-SEMVER line if the previous revision does not
contain a ysv:version statement.
- SUGGESTED-NEXT-YANG-SEMVER: unavailable (...), if the previous
version is in a pre-release form that the current
implementation cannot automatically advance.
* indicates whether the rev:non-backwards-compatible extension
statement is needed.
* highlights any non-backwards-compatible changes, which are
reported as errors.
* indicates if there are changes to any statements, e.g.,
description, that require further analysis to decide whether a
semantic change has occurred and hence if the change is non-
backwards-compatible rather than editorial.
* may emit additional semver policy diagnostics if a declared new
ysv:version is inconsistent with the tool's semver policy checks.
*Example Tool Output 1*:
This example illustrates what the expected output would be for an
update to a YANG module that is derived from an IANA registry update
that defines a new enum or identity. This is a minor version change
and hence the version change recommended by the tool is from 1.0.0 →
1.1.0.
SUGGESTED-NEXT-YANG-SEMVER: 1.1.0
*Example Tool Output 2*:
This example output below due to deleting an enum entry indicates an
NBC change has occurred. Hence the tool recommends a major version
number change from 1.0.0 → 2.0.0 and the addition of the rev:non-
backwards-compatible statement.
SUGGESTED-NEXT-YANG-SEMVER: 2.0.0
NBC-CHANGE(S):
iana-ssh-mac-algs@2026-03-06.yang:45: error: rev:non-backwards-compatible is required for this revision
iana-ssh-mac-algs@2026-03-06.yang:62: error: the enum 'AEAD_AES_256_GCM', defined at iana-ssh-mac-algs@2024-10-16.yang:109 is illegally removed or marked obsolete
iana-ssh-mac-algs@2026-03-06.yang:62: error: the value for enum 'hmac-sha2-256', has changed from 7 to 6 (RFC 7950: sec. 11, p5, bullet 1)
iana-ssh-mac-algs@2026-03-06.yang:62: error: the value for enum 'hmac-sha2-512', has changed from 8 to 7 (RFC 7950: sec. 11, p5, bullet 1)
*Example Tool Output 3*:
Wilton Expires 16 October 2026 [Page 26]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
This example output is for a change to a description statement. The
tool output suggests a version change from 1.0.0 → 1.0.1, which is
correct if there is no change in semantics. It also highlights that
it may be necessary to consult with the authors to determine if a
semantic change has occurred, if that is not obvious. If after
reviewing, the conclusion is that a semantic change has occurred,
then the version change should be from 1.0.0 → 2.0.0 and the rev:non-
backwards-compatible statement should be added.
SUGGESTED-NEXT-YANG-SEMVER: 1.0.1
POSSIBLE-NBC-CHANGE(S):
Consult document authors and YANG Doctors.
iana-ssh-mac-algs@2025-03-17.yang:138: warning: the description change may have changed the semantics of the node
A.1.1.4. Generating tree diagrams for documentation
Pyang can be used to generate tree diagram output that conforms to
[RFC8340]. The command below generates the tree diagram for ietf-
module-name.yang, limited to a line length of 69 characters and
writes it into the specified output-file. The tree-options is based
on the options in pyang that are prefixed with --tree and can be seen
by running pyang --help. Common options may include printing out
grouping (--tree-print-groupings) or printing out structures (--tree-
print-structures).
pyang -f tree --tree-line-length=69 -Werror -p <dep-module-directory> -o <output-file> <tree-options> ietf-module-name.yang
A.1.2. yanglint
*Purpose*: yanglint is a YANG validator and data manipulation tool
from the libyang project, useful for validating modules and instance
data.
*Primary Use Cases*:
* Validating YANG module syntax
* Checking cross-module dependencies
* Validating instance data against YANG schemas
*Installation*: yanglint is part of libyang, available from
https://github.com/CESNET/libyang (https://github.com/CESNET/libyang)
*Syntax Validation*:
yanglint -p /path/to/yang/modules module-name.yang
Wilton Expires 16 October 2026 [Page 27]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
The -p option specifies a directory containing imported modules.
This command validates the module syntax. No output indicates
successful validation; errors will be displayed if found.
A.1.3. YANG Catalog Tools
*Purpose*: The YANG Catalog (https://www.yangcatalog.org
(https://www.yangcatalog.org)) provides online tools for module
validation, comparison, and discovery.
*Primary Use Cases*:
* Validating YANG modules without local tool installation
* Comparing different versions of modules
* Viewing module dependencies and impact analysis
* Searching for existing modules and versions
*Usage*:
Access the web interface at https://www.yangcatalog.org
(https://www.yangcatalog.org) and use the "Validator" and "YANG
Impact Analysis" tools.
*Interpreting Results*:
The online tools provide visual feedback on validation results and
module comparisons. The impact analysis tool can show which other
modules depend on a given module, helping assess the impact of
changes.
A.2. Tool Limitations
While tools are valuable for YANG module validation and versioning,
they have a couple of limitations relevant to their usage here:
*Limitation 1: Cannot Always Distinguish Editorial from BC/NBC
Changes*
Current tools cannot determine whether a description change is purely
editorial (clarifying existing meaning) or non-backwards-compatible
(changing meaning in semantically significant way). Human or AI
judgment is required to make this distinction.
Wilton Expires 16 October 2026 [Page 28]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
Example: Changing "Ethernet interface" to "Ethernet interface,
includes all Ethernet interface speeds" could be editorial (if those
variants were always included). But changing an "ip" type from a
description saying "IPv4 address or IPv6 address" to just "IPv4
address" would be regarded as an NBC change because the scope of the
type has clearly changed and may impact users of that type.
*Limitation 2: May Produce False Positives or False Negatives*
Tool implementations may have bugs or may not cover all edge cases in
the YANG versioning rules. Generally, in any ambiguous cases, the
tools are being designed to either explicitly flag this or choose the
more impactful option. It is assumed to be better for clients to
potentially flag an NBC change that is not really there than to
mistakenly flag an NBC change as only being a BC change.
Hence the recommendation is to always review tool output critically
and seek additional review (Section 7) when uncertainty remains.
Appendix B. Summary of IANA Registry Action Scenarios
This appendix provides a comprehensive reference of common scenarios
encountered when updating IANA-maintained YANG module derived from
IANA registries. Each scenario describes the registry action, the
corresponding YANG module change, the classification (NBC/BC/
Editorial), the version change required, and whether the rev:non-
backwards-compatible extension must be added.
B.1. Quick Reference Table
The assumption is that the YANG module uses the registry entry name,
numeric identifier, description, status, and any reference fields as
part of the YANG entries. If additional fields from the registry are
used in the YANG module (e.g., perhaps the YANG description is
constructed from multiple registry fields) then any changes to those
fields will require a new version of the YANG module to be published
and an appropriate new version number, chosen based on the actual
change to the YANG module.
*Important Principle*: The source or trigger of a change (errata, new
RFC, registry update, expert review, etc.) does NOT determine whether
it is NBC, BC, or Editorial. What matters is the resultant change
made to the YANG module content.
Wilton Expires 16 October 2026 [Page 29]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
+==================+=============+================+=========+=======+
| Registry Action | YANG Change | Classification | Version | NBC |
| | | | | Ext |
+==================+=============+================+=========+=======+
| Add new | Add enum/ | BC | MINOR | No |
| registration | identity | | | |
+------------------+-------------+----------------+---------+-------+
| Update | Update | Editorial | PATCH | No |
| reference | reference | | | |
| (Draft → RFC) | | | | |
+------------------+-------------+----------------+---------+-------+
| Update | Update | Editorial | PATCH | No |
| reference | reference | | | |
| (obsoleted RFC) | | | | |
+------------------+-------------+----------------+---------+-------+
| Add additional | Update | Editorial | PATCH | No |
| reference | reference | | | |
+------------------+-------------+----------------+---------+-------+
| Change or | Update | Editorial | PATCH | No |
| remove | reference | | | |
| reference | | | | |
+------------------+-------------+----------------+---------+-------+
| Update | Update | Editorial | PATCH | No |
| description | description | | | |
| (clarify) | | | | |
+------------------+-------------+----------------+---------+-------+
| Update | Update | NBC | MAJOR | Yes |
| description | description | | | |
| (change | | | | |
| meaning) | | | | |
+------------------+-------------+----------------+---------+-------+
| Deprecate entry | status | BC | MINOR | No |
| (keep name) | deprecated | | | |
+------------------+-------------+----------------+---------+-------+
| Obsolete entry | status | NBC | MAJOR | Yes |
| | obsolete | | | |
+------------------+-------------+----------------+---------+-------+
| Rename entry | Change | NBC | MAJOR | Yes |
| | identifier | | | |
+------------------+-------------+----------------+---------+-------+
| Remove entry | Remove | NBC | MAJOR | Yes |
| completely | enum/ | | | |
| | identity | | | |
+------------------+-------------+----------------+---------+-------+
| Change value | Change | NBC | MAJOR | Yes |
| number | value | | | |
+------------------+-------------+----------------+---------+-------+
| Reuse old value | Same as | BC | MINOR | No |
Wilton Expires 16 October 2026 [Page 30]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
| (previously | adding new | | | |
| removed) | entry | | | |
+------------------+-------------+----------------+---------+-------+
| Add footnote | Optionally | Editorial | PATCH | No |
| | update | | | |
| | description | | | |
+------------------+-------------+----------------+---------+-------+
| Non-YANG field | Depends on | Analyze | Varies | Maybe |
| changes | how the | | | |
| | module is | | | |
| | updated | | | |
+------------------+-------------+----------------+---------+-------+
| Errata | Depends on | Analyze | Varies | Maybe |
| | content | | | |
+------------------+-------------+----------------+---------+-------+
| Early alloc | No change | N/A | None | No |
| expired (left | | | | |
| as-is) | | | | |
+------------------+-------------+----------------+---------+-------+
| Early alloc | Follow | NBC | MAJOR | Yes |
| expired | removal | | | |
| (removed) | rules | | | |
+------------------+-------------+----------------+---------+-------+
| Revive expired | Add enum/ | BC | MINOR | No |
| (removed) | identity | | | |
| allocation | | | | |
+------------------+-------------+----------------+---------+-------+
Table 1: Registry Action → YANG Module Update Reference Table
*Key*:
* *BC* = Backwards-Compatible; *NBC* = Non-Backwards-Compatible
* *MAJOR/MINOR/PATCH* refer to the YANG Semver version components
* *NBC Ext* = Whether rev:non-backwards-compatible extension is
required
* *Varies* or *Maybe* indicates the specific change must be analyzed
using the detailed scenarios below
B.2. Detailed Common Scenarios
Note: The following scenarios only contain snippets of YANG to
illustrate the change being made and are not intended to represent
complete example modules, or be able to compile or validate.
Wilton Expires 16 October 2026 [Page 31]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
B.2.1. Scenario 1: Adding a New Registry Entry
*Registry Action*: A new entry is added to an IANA registry.
*YANG Module Change*: Add a new enum value or identity.
*Classification*: Backwards-Compatible (BC)
*Version Change*: Increment MINOR version (e.g., 1.0.0 → 1.1.0)
*NBC Extension Required*: No
*Rationale*: Adding a new type is backwards compatible because it
cannot break backwards-compatibility of existing implementations.
*Example*:
Previous version, _1.0.0_:
revision 2025-11-01 {
ysv:version "1.0.0";
description "Initial revision.";
}
typedef interface-type {
type enumeration {
enum ethernet {
value 6;
description "Ethernet interface";
}
}
}
New version, _1.1.0_, after addition of 'wifi' enum type:
Wilton Expires 16 October 2026 [Page 32]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
revision 2025-11-15 {
ysv:version "1.1.0";
description "Added 'wifi' (71).";
}
revision 2025-11-01 {
ysv:version "1.0.0";
description "Initial revision.";
}
typedef interface-type {
type enumeration {
enum ethernet {
value 6;
description "Ethernet interface";
}
enum wifi {
value 71;
description "IEEE 802.11 wireless interface";
}
}
}
B.2.2. Scenario 2: Updating References
*Registry Action*: A reference is updated (e.g., RFC obsoleted,
additional reference added, draft reference changed to RFC number).
*YANG Module Change*: Update the "reference" statement.
*Classification*: Editorial
*Version Change*: Increment PATCH version (e.g., 2.3.0 → 2.3.1)
*NBC Extension Required*: No
*Rationale*: Reference statements may be added or updated without
affecting compatibility of existing implementations.
*Example*:
Previous version, _2.3.0_:
Wilton Expires 16 October 2026 [Page 33]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
revision 2025-11-01 {
ysv:version "2.3.0";
description "Added 'foo' (42).";
}
typedef interface-type {
type enumeration {
...
enum foo {
value 42;
description "Foo interface type.";
reference "RFC 1234";
}
}
}
New version (_2.3.1_) after the reference for 'foo' is updated to RFC
5678:
revision 2025-11-15 {
ysv:version "2.3.1";
description "Updated reference for 'foo' (42).";
}
revision 2025-11-01 {
ysv:version "2.3.0";
description "Added 'foo' (42).";
}
typedef interface-type {
type enumeration {
...
enum foo {
value 42;
description "Foo interface type.";
reference "RFC 5678 (obsoletes RFC 1234)";
}
}
}
B.2.3. Scenario 3: Deprecating a Registry Entry
*Registry Action*: A registry entry is marked as deprecated (name and
description remain visible).
*YANG Module Change*: Change status from "current" to "deprecated".
*Classification*: Backwards-Compatible (BC)
Wilton Expires 16 October 2026 [Page 34]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
*Version Change*: Increment MINOR version (e.g., 2.3.1 → 2.4.0)
*NBC Extension Required*: No
*Rationale*: Changing status to deprecated is backwards-compatible
but the description must also be updated to highlight the difference
in meaning between IANA registries and YANG modules.
*Example*:
Previous version, _2.3.1_:
revision 2025-11-15 {
ysv:version "2.3.1";
description "Updated reference 'foo' (42).";
}
typedef interface-type {
type enumeration {
...
enum oldtype {
value 99;
description "Old interface type";
}
}
}
New version (_2.4.0_) after deprecation:
Wilton Expires 16 October 2026 [Page 35]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
revision 2025-11-23 {
ysv:version "2.4.0";
description "Deprecated 'oldtype' (99).";
}
revision 2025-11-15 {
ysv:version "2.3.1";
description "Updated reference 'foo' (42).";
}
typedef interface-type {
type enumeration {
...
enum oldtype {
value 99;
status deprecated;
description
"Old interface type. This value is deprecated in the base IANA
registry which means that its use is NOT RECOMMENDED.";
}
}
}
B.2.4. Scenario 4: Obsoleting a Registry Entry
*Registry Action*: A registry entry is marked as obsolete.
*YANG Module Change*: Change status from "deprecated" (or "current")
to "obsolete".
*Classification*: Non-Backwards-Compatible (NBC)
*Version Change*: Increment MAJOR version (e.g., 2.4.0 → 3.0.0)
*NBC Extension Required*: Yes
*Rationale*: Changing status to obsolete indicates the value MUST NOT
be used, breaking compatibility. Note, the description comment about
deprecation can also be removed.
*Example*:
Previous version (_2.4.0_):
Wilton Expires 16 October 2026 [Page 36]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
revision 2025-11-23 {
ysv:version "2.4.0";
description
"Deprecated 'oldtype' (99).";
}
typedef interface-type {
type enumeration {
...
enum oldtype {
value 99;
status deprecated;
description
"Old interface type. This value is deprecated in the base IANA
registry which means that its use is NOT RECOMMENDED.";
}
}
}
New version (_3.0.0_) after obsoletion:
revision 2025-11-30 {
ysv:version "3.0.0";
rev:non-backwards-compatible;
description
"Obsoleted 'oldtype' (99).";
}
revision 2025-11-23 {
ysv:version "2.4.0";
description
"Deprecated 'oldtype' (99).";
}
typedef interface-type {
type enumeration {
...
enum oldtype {
value 99;
status obsolete;
description
"Old interface type.";
}
}
}
Wilton Expires 16 October 2026 [Page 37]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
B.2.5. Scenario 5: Removing a Registry Entry Completely
*Registry Action*: A registry entry is removed with no trace.
*YANG Module Change*: Remove the enum or identity from the module.
*Classification*: Non-Backwards-Compatible (NBC)
*Version Change*: Increment MAJOR version (e.g., 2.2.0 → 3.0.0)
*NBC Extension Required*: Yes
*Rationale*: Removing a schema node is NBC per Section 3.1.2.1 of
[I-D.ietf-netmod-yang-module-versioning].
*Example*:
Previous version (_2.2.0_):
revision 2026-02-01 {
ysv:version "2.2.0";
description
"Added 'legacy-wireless' identity.";
}
identity interface-type {
description
"Base identity for interface types.";
}
identity legacy-wireless {
base interface-type;
description
"Legacy wireless interface.";
}
New version (_3.0.0_) after removal:
Wilton Expires 16 October 2026 [Page 38]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
revision 2026-03-15 {
ysv:version "3.0.0";
rev:non-backwards-compatible;
description
"Removed 'legacy-wireless' identity.";
}
revision 2026-02-01 {
ysv:version "2.2.0";
description
"Added 'legacy-wireless' identity.";
}
identity interface-type {
description "Base identity for interface types.";
}
B.2.6. Scenario 6: Renaming a Registry Entry
*Registry Action*: The name of a registry entry is changed.
*YANG Module Change*: Change the enum or identity identifier.
*Classification*: Non-Backwards-Compatible (NBC)
*Version Change*: Increment MAJOR version (e.g., 3.1.0 → 4.0.0)
*NBC Extension Required*: Yes
*Rationale*: Renaming breaks programmatic references to the
identifier.
*Example*:
Previous version (_3.1.0_):
revision 2026-04-01 {
ysv:version "3.1.0";
description "Added 'old-gre' identity.";
}
identity tunnel-type {
description "Base identity for tunnel types.";
}
identity old-gre {
base tunnel-type;
description "GRE tunnel (legacy name).";
}
Wilton Expires 16 October 2026 [Page 39]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
New version (_4.0.0_) after rename:
revision 2026-05-01 {
ysv:version "4.0.0";
rev:non-backwards-compatible;
description "Renamed 'old-gre' identity to 'gre'.";
}
revision 2026-04-01 {
ysv:version "3.1.0";
description "Added old-gre identity.";
}
identity tunnel-type {
description "Base identity for tunnel types.";
}
identity gre {
base tunnel-type;
description "GRE tunnel.";
}
B.2.7. Scenario 7: Changing a Value Number
*Registry Action*: The numeric value assigned to a registry entry is
changed.
*YANG Module Change*: Change the value assigned to an enum.
*Classification*: Non-Backwards-Compatible (NBC)
*Version Change*: Increment MAJOR version (e.g., 2.3.0 → 3.0.0)
*NBC Extension Required*: Yes
*Rationale*: Changing values breaks compatibility for implementations
using those values.
*Example*:
Previous version (_2.3.0_):
Wilton Expires 16 October 2026 [Page 40]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
revision 2026-01-10 {
ysv:version "2.3.0";
description "Added multiple identities.";
}
typedef interface-type {
type enumeration {
enum fastether {
value 210;
description "Fast Ethernet interface.";
}
enum atm {
value 211;
description "ATM interface.";
}
}
}
New version (_3.0.0_) after value change:
revision 2026-02-20 {
ysv:version "3.0.0";
rev:non-backwards-compatible;
description "Changed 'fastether' value to 215.";
}
revision 2026-01-10 {
ysv:version "2.3.0";
description "Added multiple identities.";
}
typedef interface-type {
type enumeration {
enum fastether {
value 215;
description "Fast Ethernet interface.";
}
enum atm {
value 211;
description "ATM interface.";
}
}
}
B.2.8. Scenario 8: Updating Description (Clarification)
*Registry Action*: Description is updated to clarify existing
behavior without changing meaning.
Wilton Expires 16 October 2026 [Page 41]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
*YANG Module Change*: Update the description statement.
*Classification*: Editorial
*Version Change*: Increment PATCH version (e.g., 2.1.3 → 2.1.4)
*NBC Extension Required*: No
*Example*:
Previous version (_2.1.3_):
revision 2026-02-05 {
ysv:version "2.1.3";
description "Clarified description for 'foo'.";
}
identity ethernet {
base interface-type;
description "Ethernet interface.";
}
New version (_2.1.4_) after clarification:
revision 2026-02-12 {
ysv:version "2.1.4";
description "Clarified description for 'ethernet'.";
}
revision 2026-02-05 {
ysv:version "2.1.3";
description "Clarified description for 'foo'.";
}
identity ethernet {
base interface-type;
description
"Ethernet interface, includes 10BASE-T, 100BASE-T, and
1000BASE-T variants.";
}
B.2.9. Scenario 9: Updating Description (Semantic Change)
*Registry Action*: Description is updated in a way that changes the
semantic meaning or behavior.
*YANG Module Change*: Update the description statement.
*Classification*: Non-Backwards-Compatible (NBC)
Wilton Expires 16 October 2026 [Page 42]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
*Version Change*: Increment MAJOR version (e.g., 2.2.0 → 3.0.0)
*NBC Extension Required*: Yes
*Example*:
Previous version (_2.2.0_):
revision 2026-03-01 {
ysv:version "2.2.0";
description "Defined 'ip' identity.";
}
identity ip {
base interface-type;
description "Interface supports IPv4.";
}
New version (_3.0.0_) after semantic change:
revision 2026-04-01 {
ysv:version "3.0.0";
rev:non-backwards-compatible;
description "Changed description for 'ip' identity";
}
revision 2026-03-01 {
ysv:version "2.2.0";
description "Defined 'ip' identity.";
}
identity ip {
base interface-type;
description "Interface supports IPv4 and IPv6.";
}
B.2.10. Scenario 10: Handling Errata
*Registry Action*: An errata report is filed for the registry or
module.
*YANG Module Change*: Depends on the specific errata content.
*Classification*: Analyze the actual change, not the source (errata
vs. new RFC does not determine classification).
*Version Change*: Follow the rules based on the actual change being
made to the IANA registry entry.
Wilton Expires 16 October 2026 [Page 43]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
*NBC Extension Required*: May be required depending on the change.
*Examples*:
* Errata fixes typo in description → Editorial / PATCH
* Errata adds missing enum → BC / MINOR
* Errata corrects wrong value assignment → NBC / MAJOR
Acknowledgments
The creation of this document was motivated by questions from IANA
team members Amanda Baber and Sabrina Tanamal regarding the correct
handling of YANG module versioning. This was followed by a
productive in-person discussion at IETF 124 between members of the
YANG versioning design team, the IANA team, NETMOD working group
chairs, RFC Editor representatives, and the OPS Area Director.
Participants in that meeting included: Amanda Baber, Jason Sterne,
Joe Clarke, Kent Watsen, Lou Berger, Mahesh Jethanandani, Per
Andersson, Reshad Rahman, Rob Wilton, and Sabrina Tanamal.
Special thanks to Joe Clarke for his presentation on YANG versioning
tooling at IETF 124, which informed the tooling guidance in
Appendix A.
The authors thank the RFC Editor and IANA teams for their
collaboration in refining the operational procedures described in
this document.
The authors would like to thank those providing comments on the
draft, including: Amanda Baber, Jason Sterne, Joe Clarke, Mohamed
Boucadair, Reshad Rahman, Sabrina Tanamal, and Sandy Ginoza.
The authors also thank the NETMOD working group for their extensive
work on YANG versioning specifications that form the foundation of
this guidance, including the module versioning framework, semantic
versioning, and associated tooling.
The initial substantive revision of this document used Claude Sonnet
4.5 to create prose and examples, which have been subsequently
reviewed and refined by the YANG Versioning design team and the
NETMOD working group.
Author's Address
Wilton Expires 16 October 2026 [Page 44]
Internet-Draft IANA & RFC Editor YANG Guidance April 2026
Robert Wilton
Cisco
Email: rwilton@cisco.com
Wilton Expires 16 October 2026 [Page 45]