Guidance for Managing YANG Modules in RFCs and IANA Registries

4.1. YANG Semantic Versioning

YANG Semantic Versioning (YANG Semver), defined in [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¶

• MINOR version increments indicate backwards-compatible (BC) feature additions¶

• PATCH version increments indicate editorial or documentation-only changes¶

• _COMPAT is used for branched development trees and is not applicable to modules published by the RFC Editor in RFCs that are expected to follow a linear development, (TODO, but may be useful/needed if we allow verified errata against YANG modules) or maintained by IANA.¶

For example, if a published IETF YANG module is at version 1.2.3: - A non-backwards-compatible change would update it to 2.0.0 - A backwards-compatible feature addition would update it to 1.3.0 - An editorial change would update it to 1.2.4¶

Pre-release versions (versions with MAJOR = 0 or with a pre-release suffix such as "-draft-verdt-iana-yang-guidance") 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.¶

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, which include:¶

• Adding new schema nodes (e.g., new enum values, identities, leafs, containers)¶

• Adding new optional features or extensions¶

• Changing the status of a schema node from "current" to "deprecated"¶

• Adding or updating "description" and "reference" statements (provided the semantic meaning is unchanged)¶

• Expanding constraints (e.g., widening ranges, adding enum values)¶

Section 3.1.2 of [I-D.ietf-netmod-yang-module-versioning] defines non-backwards-compatible changes, which 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¶

• Restricting constraints (e.g., narrowing ranges, removing enum values)¶

• Modifying "description" statements in ways that change semantic meaning or behavior¶

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, which include:¶

• Corrections to comments, descriptions, or references that do not change the semantic meaning¶

• Formatting improvements such as whitespace or indentation changes¶

• Corrections to typographical errors in description text¶

• Updates to contact information or copyright statements¶

• Changes to import statements that do not affect module functionality (e.g., updating import prefixes for readability)¶

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'.";
  }
  ...

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 SHOULD use pre-release versions (e.g., 0.1.0 or 2.0.0-draft) to indicate that the content may still change¶

• Once a document is approved by the IESG, the module version MUST be updated to a release version (e.g., 1.0.0, or 2.0.0) before publication as an RFC.¶

• IANA-maintained modules MUST publish a new revision any time the registry changes require module updates¶

5.1. Core Requirements

All YANG modules published by the RFC Editor or maintained by IANA MUST meet the following requirements:¶

1. YANG Semver Version: Every 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 previously published version of the same module (either in a previous RFC or on the IANA website).¶

2. NBC Extension for NBC Changes: If the module contains non-backwards-compatible changes relative to the previously published version, the revision statement MUST include the rev:non-backwards-compatible extension.¶

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 SHOULD 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-draft) to indicate that content may still change before final publication.¶

4. RFC Code Markers: 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. 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.3. Determining the Correct Version

The correct version for a module in an RFC depends on its relationship to any previously published version:¶

• New Module (never published before): Version 1.0.0 is typically appropriate for the first publication¶

• Updated Module (updating a module from a previous RFC): The version increment depends on the nature of changes:¶

  • Editorial changes only → PATCH increment (e.g., 1.0.0 → 1.0.1)¶

  • Backwards-compatible additions → MINOR increment (e.g., 1.0.0 → 1.1.0)¶

  • Non-backwards-compatible changes → MAJOR increment (e.g., 1.0.0 → 2.0.0) with NBC extension¶

Tooling (described in Appendix A) can assist in determining the correct version by comparing the new module with the previously published version. The pyang --check-update-from command is particularly useful for detecting NBC changes.¶

However, tools have limitations and cannot always detect editorial versus backwards-compatible changes, particularly in description text and must/when expressions. In such cases:¶

• Review the classification guidance in Appendix B¶

• Consult with document authors who understand the intent of changes¶

• Seek expert guidance as described in Section 7 if uncertainty remains¶

• When in doubt, choose the more conservative classification (e.g., NBC rather than BC, or BC rather than editorial) to better highlight potential risks to implementations¶

5.4. Verification by IANA

When registering a YANG module from an RFC, IANA SHOULD verify:¶

1. The module includes a ysv:version statement in the most recent revision¶

2. If the MAJOR version has incremented from a previous publication, the rev:non-backwards-compatible extension is present¶

3. The module filename follows the conventions in [I-D.ietf-netmod-yang-module-filename]¶

4. The module is syntactically valid (can be validated using tools described in Appendix A)¶

If issues are found, IANA SHOULD report them to the RFC Editor, the document authors, and the NETMOD working group.¶

6.1. Overview

Many IANA registries have corresponding YANG modules that represent registry contents in a machine-readable format. Examples include:¶

• iana-if-type - derived from the Interface Types (ifType) registry¶

• iana-routing-types - derived from Address Family Numbers and SAFI Parameters registries¶

• iana-bgp-types - derived from BGP Parameters registries¶

When these registries are updated, the corresponding YANG modules MUST be updated accordingly, 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 map directly to registry entries¶

• Are updated more frequently than IETF-defined modules¶

• Follow a linear version history without branching¶

• Have simpler structure than general-purpose YANG modules, which simplifies classification of changes¶

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. The most relevant compatibility rules for these modules are:¶

Backwards-Compatible Changes:¶

• Adding a new enum value or identity¶

• Changing status from "current" to "deprecated"¶

• Adding or updating "reference" statements¶

• Clarifying "description" statements without changing meaning¶

• Removing schema nodes that have status "obsolete" (per Section 3.1.1 of [I-D.ietf-netmod-yang-module-versioning])¶

Non-Backwards-Compatible Changes:¶

• Removing an enum value or identity (unless status is "obsolete")¶

• Changing status to "obsolete"¶

• Renaming an enum or identity¶

• Changing the numeric value assigned to an enum¶

• Reusing a previously assigned numeric value for a different enum¶

• Modifying "description" in a way that changes the semantic meaning¶

Editorial Changes:¶

• Fixing typographical errors in description text¶

• Updating contact information¶

• Formatting improvements¶

6.4. Process for Updating IANA-Maintained Modules

When a change is made to an IANA registry that has a corresponding YANG module, IANA MUST update the module following these steps:¶

pyang --check-update-from iana-if-type@2025-10-15.yang \
                          iana-if-type@2025-11-15.yang

pyang --ietf iana-if-type@2025-11-15.yang

yanglint iana-if-type@2025-11-15.yang

6.5. Simplified Decision Process

For IANA-maintained modules, the following simplified decision process can be used in most cases:¶

Did you add a new enum or identity? → Backwards-Compatible: MINOR version increment (e.g., 1.0.0 → 1.1.0)¶

Did you only update references or clarify descriptions without changing meaning? → Editorial: PATCH version increment (e.g., 1.0.0 → 1.0.1)¶

Did you change status from "current" to "deprecated"? → Backwards-Compatible: MINOR version increment (e.g., 1.0.0 → 1.1.0)¶

Did you change status to "obsolete", remove an entry, rename an entry, or change a value number? → Non-Backwards-Compatible: MAJOR version increment (e.g., 1.0.0 → 2.0.0) and ADD rev:non-backwards-compatible extension¶

Did you change a description in a way that changes behavior or meaning? → Non-Backwards-Compatible: MAJOR version increment (e.g., 1.0.0 → 2.0.0) and ADD rev:non-backwards-compatible extension¶

Are you uncertain? → Use tooling (Appendix A), consult scenarios (Appendix B), or seek expert guidance (Section 7)¶

6.6. Examples

For detailed examples of common scenarios (adding entries, updating references, deprecating entries, etc.), see Appendix B.¶

7.1. When to Seek Guidance

The RFC Editor and IANA SHOULD contact YANG experts in the following situations:¶

1. Classification Uncertainty - When it's unclear whether a change is NBC, BC, or Editorial¶

2. Complex Changes - Multiple simultaneous changes that are difficult to classify individually¶

3. Description Changes - When a description update may alter the 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. Value Reuse - When considering reusing a previously assigned value number¶

7. Tool Disagreement - When validation tools give unexpected or contradictory results¶

8. RFC Editor Processing - When RFC Editor changes may go beyond editorial scope¶

7.2. How to Seek Guidance

7.3. Example Request

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.

11.1. Normative References

[I-D.ietf-netmod-rfc8407bis]

Bierman, A., Boucadair, M., and Q. Wu, "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", Work in Progress, Internet-Draft, draft-ietf-netmod-rfc8407bis-28, 5 June 2025, <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-rfc8407bis-28>.

[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-03, 20 October 2025, <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-yang-module-filename-03>.

[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-24, 29 September 2025, <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-yang-semver-24>.

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

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-05, 20 October 2025, <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-yang-schema-comparison-05>.

A.1. YANG Validation Tools

pyang --ietf module-name.yang

pyang --check-update-from old-module.yang new-module.yang

old-module.yang:15: error: the enum 'deprecated-value' has been removed

yanglint module-name.yang

yanglint -p /path/to/yang/modules module-name.yang

A.2. Recommended Workflow

The following workflow is recommended for validating and versioning YANG modules:¶

1. Make Changes to Module - Update the YANG file based on registry changes or RFC Editor edits¶

2. Validate Syntax - Run pyang or yanglint to check for syntax errors: ~~~~ shell pyang --ietf module-name.yang ~~~~¶

3. Check for NBC Changes - Use pyang to compare with the previous version: ~~~~ shell pyang --check-update-from old-version.yang new-version.yang ~~~~¶

4. Review Tool Output - Analyze any reported issues:¶

   • Errors from --check-update-from indicate NBC changes¶

   • No errors indicate BC or editorial changes¶

5. Determine Version - Based on the tool output and manual review:¶

   • NBC changes → MAJOR version increment (e.g., 1.0.0 → 2.0.0)¶

   • BC changes (new functionality) → MINOR version increment (e.g., 1.0.0 → 1.1.0)¶

   • Editorial changes (documentation only) → PATCH version increment (e.g., 1.0.0 → 1.0.1)¶

6. Add Revision Statement - Include:¶

   • Current date¶

   • New version number using ysv:version¶

   • Clear description of changes¶

   • rev:non-backwards-compatible extension if NBC changes occurred¶

7. Final Validation - Validate the complete updated module: ~~~~ shell pyang --ietf module-name.yang ~~~~¶

8. Seek Review if Needed - Contact experts (Section 7) if:¶

   • Tool output is unclear or surprising¶

   • Classification is uncertain¶

   • Description changes may have altered semantic meaning¶

A.3. Tool Limitations

While tools are valuable for YANG module validation and versioning, they have important limitations:¶

Limitation 1: Cannot Always Distinguish Editorial from BC Changes¶

Tools cannot determine whether a description change is purely editorial (clarifying existing meaning) or backwards-compatible (adding new information). Human judgment is required to make this distinction.¶

Example: Changing "Ethernet interface" to "Ethernet interface, including 10BASE-T and 100BASE-T" could be editorial (if those variants were always included) or BC (if documenting newly supported variants).¶

Limitation 2: Cannot Detect Semantic Changes in Descriptions¶

If a description change alters the intended behavior or meaning of a schema node, it may be an NBC change, but tools cannot detect this automatically.¶

Example: Changing "includes IPv4 only" to "includes IPv4 and IPv6" changes the semantic meaning and may be NBC, but tools will not flag this.¶

Limitation 3: Cannot Assess Practical Impact¶

Tools can identify that an NBC change has occurred but cannot assess how many implementations are affected or what the practical migration cost will be.¶

Limitation 4: May Produce False Positives or False Negatives¶

Tool implementations may have bugs or may not cover all edge cases in the YANG versioning rules. Always review tool output critically and consult experts if results are unexpected.¶

Recommendation: Always combine tool usage with the classification guidance in this document (particularly Appendix B) and seek expert review (Section 7) when uncertainty remains.¶

A.4. Future Tool Development

The NETMOD working group continues to develop improved tooling for YANG module management. Anticipated future capabilities include:¶

• Automated registry-to-YANG conversion tools¶

• Enhanced NBC change detection optimized for IANA-maintained modules¶

• Automated version recommendation based on detected changes¶

• Better detection of semantic changes in descriptions and constraints¶

As new tools become available, the NETMOD working group and YANG Doctors will provide guidance on their usage. The RFC Editor and IANA will be informed of tool updates that affect the workflows described in this document.¶

B.1. Quick 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 Scenarios

// Previous version 1.0.0
typedef interface-type {
  type enumeration {
    enum ethernet {
      value 6;
      description "Ethernet interface";
    }
  }
}

// New version 1.1.0
revision 2025-11-15 {
  ysv:version "1.1.0";
  description "Added wifi interface type";
}

typedef interface-type {
  type enumeration {
    enum ethernet {
      value 6;
      description "Ethernet interface";
    }
    enum wifi {
      value 71;
      description "IEEE 802.11 wireless interface";
    }
  }
}

// Previous version 1.0.0
enum foo {
  value 42;
  description "Foo interface type";
  reference "RFC 1234";
}

// New version 1.0.1
revision 2025-11-15 {
  ysv:version "1.0.1";
  description "Updated reference for RFC obsolescence";
}

enum foo {
  value 42;
  description "Foo interface type";
  reference "RFC 5678 (obsoletes RFC 1234)";
}

// Previous version 1.0.0
enum oldtype {
  value 99;
  status current;
  description "Old interface type";
}

// New version 1.1.0
revision 2025-11-15 {
  ysv:version "1.1.0";
  description "Deprecated oldtype interface";
}

enum oldtype {
  value 99;
  status deprecated;
  description
    "Old interface type. This value is deprecated and
     SHOULD NOT be used in new implementations.";
}

// Previous version 1.0.0
enum removedtype {
  value 98;
  status deprecated;
  description "Type being removed";
}

// New version 2.0.0
revision 2025-11-15 {
  ysv:version "2.0.0";
  rev:non-backwards-compatible;
  description
    "Obsoleted removedtype interface. Support has been removed.";
}

enum removedtype {
  value 98;
  status obsolete;
  description
    "Obsolete interface type. This value MUST NOT be used.
     Support was removed as of 2025-11-15.";
}

B.3. Notes on Classification

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 actual change made to the YANG module content.¶

C.1. Example: iana-if-type Module Structure

module iana-if-type {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:iana-if-type";
  prefix ianaift;

  import ietf-yang-revisions { prefix rev; }
  import ietf-yang-semver { prefix ysv; }

  organization
    "Internet Assigned Numbers Authority (IANA)";

  contact
    "Internet Assigned Numbers Authority

     ICANN
     12025 Waterfront Drive, Suite 300
     Los Angeles, CA 90094

     Tel: +1 424 254 5300

     <mailto:iana@iana.org>

     See the Interface Types (ifType) registry:
     <https://www.iana.org/assignments/smi-numbers>";

  description
    "This YANG module defines the iana-if-type typedef, which
     contains YANG definitions for IANA-registered interface types.

     This YANG module is maintained by IANA and reflects the
     'Interface Types (ifType)' registry.

     Copyright (c) 2025 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject
     to the license terms contained in, the Revised BSD License
     set forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC XXXX; see
     the RFC itself for full legal notices.";

  // Example revision with new interface type (BC change)
  revision 2025-11-15 {
    ysv:version "2.5.0";
    description
      "Added new interface type 'wifi6e' per registry update.";
    reference
      "RFC XXXX: IANA Guidance for YANG Modules";
  }

  // Example revision with obsoleted type (NBC change)
  revision 2025-10-01 {
    ysv:version "2.0.0";
    rev:non-backwards-compatible;
    description
      "Obsoleted 'arcnet' interface type as support has been removed.";
    reference
      "RFC XXXX: IANA Guidance for YANG Modules";
  }

  // Example earlier revision (BC change)
  revision 2025-09-01 {
    ysv:version "1.1.0";
    description
      "Added new interface type 'virtualEthernet'.";
  }

  // Example initial revision
  revision 2025-01-01 {
    ysv:version "1.0.0";
    description
      "Initial version matching the Interface Types registry
       as of 2025-01-01.";
  }

  typedef interface-type {
    type enumeration {
      enum other {
        value 1;
        description
          "None of the following types.";
      }
      enum ethernet {
        value 6;
        description
          "Ethernet interface, including 10BASE-T, 100BASE-T,
           and 1000BASE-T variants.";
        reference
          "RFC 3635: Definitions of Managed Objects for the
           Ethernet-like Interface Types";
      }
      enum wifi6e {
        value 289;
        description
          "IEEE 802.11ax (Wi-Fi 6E) wireless interface.";
        reference
          "IEEE 802.11ax-2021";
      }
      enum arcnet {
        value 35;
        status obsolete;
        description
          "ARCNET interface. This interface type is obsolete
           and MUST NOT be used. Support was removed 2025-10-01.";
      }
    }
    description
      "This typedef is used to represent the IANA-registered
       interface types. It is derived from the 'Interface Types
       (ifType)' registry.";
    reference
      "IANA Interface Types registry:
       <https://www.iana.org/assignments/smi-numbers>";
  }
}