draft-ietf-netmod-yang-semver-26.txt   draft-ietf-netmod-yang-semver.txt 
Network Working Group J. Clarke, Ed. Network Working Group J. Clarke, Ed.
Internet-Draft R. Wilton, Ed. Internet-Draft R. Wilton, Ed.
Updates: 9907, 8525, 7950 (if approved) Cisco Systems, Inc. Updates: 9907, 8525, 7950 (if approved) Cisco Systems, Inc.
Intended status: Standards Track R. Rahman Intended status: Standards Track R. Rahman
Expires: 8 November 2026 Equinix Expires: 26 December 2026 Equinix
B. Lengyel B. Lengyel
Ericsson Ericsson
J. Sterne J. Sterne
Nokia Nokia
B. Claise B. Claise
Everything OPS Everything OPS
7 May 2026 24 June 2026
YANG Semantic Versioning YANG Semantic Versioning
draft-ietf-netmod-yang-semver-26 draft-ietf-netmod-yang-semver-26
Abstract Abstract
This document specifies a YANG extension along with guidelines for This document specifies a YANG extension along with guidelines for
applying an extended set of semantic versioning rules to revisions of applying an extended set of semantic versioning rules to revisions of
YANG artifacts (e.g., modules and packages). Additionally, this YANG artifacts (e.g., modules and packages). Additionally, this
document defines a YANG extension for controlling module imports document defines a YANG extension for controlling module imports
skipping to change at page 1, line 44 skipping to change at page 1, line 44
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 8 November 2026. This Internet-Draft will expire on 26 December 2026.
Copyright Notice Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License. provided without warranty as described in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Updates to Other RFCs . . . . . . . . . . . . . . . . . . 3 1.1. Updates to Other RFCs . . . . . . . . . . . . . . . . . . 4
2. Examples of How Versioning Is Applied To YANG Module 2. Examples of How Versioning Is Applied To YANG Module
Revisions . . . . . . . . . . . . . . . . . . . . . . . . 3 Revisions . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Terminology and Conventions . . . . . . . . . . . . . . . . . 5 3. Terminology and Conventions . . . . . . . . . . . . . . . . . 5
4. YANG Semantic Versioning . . . . . . . . . . . . . . . . . . 5 4. YANG Semantic Versioning . . . . . . . . . . . . . . . . . . 5
4.1. Relationship Between SemVer and YANG Semver . . . . . . . 5 4.1. Relationship Between SemVer and YANG Semver . . . . . . . 6
4.2. YANG Semantic Version Extension . . . . . . . . . . . . . 6 4.2. YANG Semantic Version Extension . . . . . . . . . . . . . 6
4.3. YANG Semver Pattern . . . . . . . . . . . . . . . . . . . 6 4.3. YANG Semver Pattern . . . . . . . . . . . . . . . . . . . 6
4.4. Semantic Versioning Scheme for YANG Artifacts . . . . . . 7 4.4. Semantic Versioning Scheme for YANG Artifacts . . . . . . 7
4.4.1. YANG Semver with submodules . . . . . . . . . . . . . 9 4.4.1. YANG Semver with submodules . . . . . . . . . . . . . 10
4.4.2. Examples for YANG semantic versions . . . . . . . . . 10 4.4.2. Examples for YANG semantic versions . . . . . . . . . 10
4.4.3. Branching Limitations with YANG Semver . . . . . . . 11 4.4.3. Branching Limitations with YANG Semver . . . . . . . 12
4.5. YANG Semantic Version Update Rules . . . . . . . . . . . 12 4.5. YANG Semantic Version Update Rules . . . . . . . . . . . 13
4.6. Examples of the YANG Semver Version Identifier . . . . . 14 4.6. Examples of the YANG Semver Version Identifier . . . . . 15
4.6.1. Example Module Using YANG Semver . . . . . . . . . . 14 4.6.1. Example Module Using YANG Semver . . . . . . . . . . 15
4.6.2. Example of Package Using YANG Semver . . . . . . . . 16 4.6.2. Example of Package Using YANG Semver . . . . . . . . 17
5. Import Module by YANG Semantic Version . . . . . . . . . . . 16 5. Import Module by YANG Semantic Version . . . . . . . . . . . 18
5.1. The recommended-min-version Extension . . . . . . . . . . 17 5.1. The recommended-min-version Extension . . . . . . . . . . 18
5.2. Import by YANG Semantic Version Rules . . . . . . . . . . 17 5.2. Import by YANG Semantic Version Rules . . . . . . . . . . 18
6. Guidelines for Using YANG Semver During Module Development . 18 6. Guidelines for Using YANG Semver During Module Development . 19
6.1. YANG Semver in IETF Modules . . . . . . . . . . . . . . . 20 6.1. YANG Semver in IETF Modules . . . . . . . . . . . . . . . 21
6.1.1. YANG Semver in New IETF Modules . . . . . . . . . . . 20 6.1.1. YANG Semver in New IETF Modules . . . . . . . . . . . 21
6.1.2. YANG Semver when updating IETF Modules . . . . . . . 20 6.1.2. YANG Semver when updating IETF Modules . . . . . . . 21
6.1.3. YANG Semver when there are multiple parallel competing 6.1.3. YANG Semver when there are multiple parallel competing
IETF drafts . . . . . . . . . . . . . . . . . . . . . 21 IETF drafts . . . . . . . . . . . . . . . . . . . . . 22
7. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 22 7. Updates to ietf-yang-library . . . . . . . . . . . . . . . . 23
7.1. YANG library versioning augmentations . . . . . . . . . . 22 7.1. YANG library versioning augmentations . . . . . . . . . . 23
7.1.1. Advertising version . . . . . . . . . . . . . . . . . 23 7.1.1. Advertising version . . . . . . . . . . . . . . . . . 24
8. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 23 8. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 24
9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 28 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 30
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30
11. Security Considerations . . . . . . . . . . . . . . . . . . . 29 11. Security Considerations . . . . . . . . . . . . . . . . . . . 30
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31
12.1. YANG Module Registrations . . . . . . . . . . . . . . . 30 12.1. YANG Module Registrations . . . . . . . . . . . . . . . 31
12.2. Guidance for YANG Semver in IANA maintained YANG modules 12.2. Guidance for YANG Semver in IANA maintained YANG modules
and submodules . . . . . . . . . . . . . . . . . . . . . 31 and submodules . . . . . . . . . . . . . . . . . . . . . 32
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 33
13.1. Normative References . . . . . . . . . . . . . . . . . . 32 13.1. Normative References . . . . . . . . . . . . . . . . . . 33
13.2. Informative References . . . . . . . . . . . . . . . . . 32 13.2. Informative References . . . . . . . . . . . . . . . . . 34
Appendix A. Example IETF Module Development . . . . . . . . . . 34 Appendix A. Example IETF Module Development . . . . . . . . . . 36
Appendix B. Examples of _COMPAT Modifier Use . . . . . . . . . . 36 Appendix B. Examples of _COMPAT Modifier Use . . . . . . . . . . 37
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39
1. Introduction 1. Introduction
[I-D.ietf-netmod-yang-module-versioning] puts forth new concepts [I-D.ietf-netmod-yang-module-versioning] puts forth new concepts
relating to modified rules for updating YANG modules and submodules, relating to modified rules for updating YANG modules and submodules,
a means to signal when a new revision of a module or submodule has a means to signal when a new revision of a module or submodule has
non-backwards-compatible (NBC) changes compared to its previous non-backwards-compatible (NBC) or backwards-compatible (BC) changes
revision, and extends the YANG import statement with a minimum compared to its previous revision, and extends the YANG import
revision suggestion to help document inter-module dependencies. statement with a minimum revision suggestion to help document inter-
module dependencies.
This document defines a YANG extension that tags a YANG artifact This document defines a YANG extension that tags a YANG artifact
(i.e., YANG modules, YANG submodules, and YANG packages (i.e., YANG modules, YANG submodules, and YANG packages
[I-D.ietf-netmod-yang-packages] ) with a version identifier (YANG [I-D.ietf-netmod-yang-packages] ) with a version identifier (YANG
Semver) that adheres to extended semantic versioning rules [SemVer]. Semver) that adheres to extended semantic versioning rules [SemVer].
The goal being to add a human readable version identifier that The goal is to add a human-readable version identifier that provides
provides compatibility information for the YANG artifact without compatibility information for the YANG artifact without needing to
needing to compare or parse its body. The version identifier and compare or parse its body. The version identifier and rules defined
rules defined herein represent the recommended approach to apply herein represent the recommended approach to apply versioning to IETF
versioning to IETF YANG artifacts. This document defines YANG artifacts. This document defines augmentations to ietf-yang-
augmentations to ietf-yang-library to reflect the version of YANG library to reflect the version of YANG modules within the module-set
modules within the module-set data. YANG Semver extends SemVer with data. YANG Semver extends SemVer with an optional '_COMPAT' suffix
an optional '_COMPAT' suffix to support limited branching within YANG to support limited branching within YANG artifact revision histories,
artifact revision histories, as described in Section 4.3 and as described in Section 4.3 and Section 4.4.3.
Section 4.4.3.
This extension is particularly useful for artifact authors, such as
vendors, that maintain multiple supported release branches of a YANG
artifact. In those cases, fixes or enhancements may need to be
applied to an older branch rather than only to the latest revision.
The '_COMPAT' modifier allows those updates to retain useful
compatibility information without implying a single linear SemVer
progression.
Note that a specific revision of the SemVer 2.0.0 specification is Note that a specific revision of the SemVer 2.0.0 specification is
referenced here (from June 19, 2020) to provide an immutable version. referenced here (from June 19, 2020) to provide an immutable version.
This is because the 2.0.0 version of the specification has changed This is because the 2.0.0 version of the specification has changed
over time without any change to the semantic version itself. over time without any change to the semantic version itself.
1.1. Updates to Other RFCs 1.1. Updates to Other RFCs
This document updates [RFC7950] to clarify how ambiguous module This document updates [RFC7950] to clarify how ambiguous module
imports are resolved (Section 5). It updates [RFC8525] by adding a imports are resolved (Section 5). It updates [RFC8525] by adding a
skipping to change at page 5, line 43 skipping to change at page 6, line 13
updated. updated.
4.1. Relationship Between SemVer and YANG Semver 4.1. Relationship Between SemVer and YANG Semver
[SemVer] is completely compatible with YANG Semver in that a SemVer [SemVer] is completely compatible with YANG Semver in that a SemVer
semantic version number is legal according to the YANG Semver rules semantic version number is legal according to the YANG Semver rules
(though the inverse is not necessarily true). YANG Semver is a (though the inverse is not necessarily true). YANG Semver is a
superset of the SemVer rules, and allows for limited branching within superset of the SemVer rules, and allows for limited branching within
YANG artifacts. If no branching occurs within a YANG artifact (e.g., YANG artifacts. If no branching occurs within a YANG artifact (e.g.,
in IETF modules, which are not expected to use branching), the YANG in IETF modules, which are not expected to use branching), the YANG
Semver version label will appear as a SemVer version number (i.e., Semver version number will appear as a SemVer version number (i.e.,
they will not use the compatibility modifier described below). Note they will not use the compatibility modifier described below). Note
that standard SemVer does not support branching and assumes a single that standard SemVer does not support branching and assumes a single
linear progression of releases. The optional '_COMPAT' modifier is linear progression of releases. The optional '_COMPAT' modifier is
unique to YANG Semver and is introduced to support the limited unique to YANG Semver and is introduced to support the limited
branching that may be needed for certain YANG artifact revision branching that may be needed for certain YANG artifact revision
histories. histories.
4.2. YANG Semantic Version Extension 4.2. YANG Semantic Version Extension
The ietf-yang-semver module defines a "version" extension -- a The ietf-yang-semver module defines a "version" extension -- a
skipping to change at page 6, line 26 skipping to change at page 6, line 42
YANG artifacts that employ semantic versioning as defined in this YANG artifacts that employ semantic versioning as defined in this
document MUST use a version identifier that corresponds to the document MUST use a version identifier that corresponds to the
following pattern: 'X.Y.Z_COMPAT'. Where: following pattern: 'X.Y.Z_COMPAT'. Where:
* X, Y and Z are mandatory non-negative integers that are each less * X, Y and Z are mandatory non-negative integers that are each less
than or equal to 2147483647 (i.e., the maximum signed 32-bit than or equal to 2147483647 (i.e., the maximum signed 32-bit
integer value) and MUST NOT contain leading zeroes, integer value) and MUST NOT contain leading zeroes,
* The '.' is a literal period (ASCII character 0x2e), * The '.' is a literal period (ASCII character 0x2e),
* The '_' is an optional single literal underscore (ASCII character * _COMPAT is an optional element. If present, it consists of a
0x5f) and MUST only be present if the following COMPAT element is single literal underscore (ASCII character 0x5f) followed by
included, either the literal string "compatible" or the literal string
"non_compatible". If _COMPAT is absent, the underscore MUST NOT
* COMPAT, if specified, MUST be either the literal string appear.
"compatible" or the literal string "non_compatible".
Additionally, [SemVer] defines two specific types of metadata that Additionally, [SemVer] defines two specific types of metadata that
may be appended to a semantic version string. Pre-release metadata may be appended to a semantic version string. Pre-release metadata
MAY be appended to a YANG Semver string after a trailing '-' MAY be appended to a YANG Semver string after a trailing '-'
character. Build metadata MAY be appended after a trailing '+' character. Build metadata MAY be appended after a trailing '+'
character. If both pre-release and build metadata are present, then character. If both pre-release and build metadata are present, then
build metadata MUST follow pre-release metadata. While build build metadata MUST follow pre-release metadata. While pre-release
metadata MUST be ignored when comparing YANG semantic versions, pre- metadata can be used during module and submodule development as
release metadata can be used during module and submodule development specified in Section 6, both pre-release and build metadata MUST be
as specified in Section 6. Both pre-release and build metadata are ignored when comparing YANG semantic versions. Both pre-release and
allowed in order to support all the [SemVer] rules. Thus, a version build metadata are allowed in order to support all the [SemVer]
lineage that follows strict [SemVer] rules is allowed for a YANG rules. Thus, a version lineage that follows strict [SemVer] rules is
artifact. allowed for a YANG artifact.
The ietf-yang-semver module included in this document defines an The ietf-yang-semver module included in this document defines an
extension to apply a YANG Semver identifier to a YANG artifact as extension to apply a YANG Semver identifier to a YANG artifact as
well as a typedef that formally specifies the syntax of the YANG well as a typedef that formally specifies the syntax of the YANG
Semver. Semver.
4.4. Semantic Versioning Scheme for YANG Artifacts 4.4. Semantic Versioning Scheme for YANG Artifacts
This document defines the YANG semantic versioning scheme that is This document defines the YANG semantic versioning scheme that is
used for YANG artifacts. The versioning identifier has the following used for YANG artifacts. The versioning identifier has the following
skipping to change at page 8, line 15 skipping to change at page 8, line 29
* 'X' is the MAJOR version. Changes in the MAJOR version number * 'X' is the MAJOR version. Changes in the MAJOR version number
indicate changes that are non-backwards-compatible (Section 3.1.1 indicate changes that are non-backwards-compatible (Section 3.1.1
of [I-D.ietf-netmod-yang-module-versioning]) to versions with a of [I-D.ietf-netmod-yang-module-versioning]) to versions with a
lower MAJOR version number. lower MAJOR version number.
* 'Y' is the MINOR version. Changes in the MINOR version number * 'Y' is the MINOR version. Changes in the MINOR version number
indicate changes that are backwards-compatible to versions with indicate changes that are backwards-compatible to versions with
the same MAJOR version number, but a lower MINOR version number the same MAJOR version number, but a lower MINOR version number
and no "_compatible" or "_non_compatible" modifier. and no "_compatible" or "_non_compatible" modifier.
* 'Z' is the PATCH version. Changes in the PATCH version number can * 'Z' is the PATCH version. A change to the PATCH version number
indicate an editorial change to the YANG artifact. In conjunction alone (i.e., with no '_COMPAT' modifier) indicates an editorial
with the '_COMPAT' modifier (see below) changes to 'Z' may change to the YANG artifact. When the '_COMPAT' modifier is also
indicate a more substantive module change. An editorial change is present (see below), a change to 'Z' indicates a backwards-
defined to be a change in the YANG artifact's content that does compatible or non-backwards-compatible change as conveyed by the
not affect the semantic meaning or functionality provided by the modifier. An editorial change is defined to be a change in the
artifact in any way. Some examples include correcting a spelling YANG artifact's content that does not affect the semantic meaning
mistake in the description of a leaf within a YANG module or or functionality provided by the artifact in any way. Some
submodule, non-significant whitespace changes (e.g., realigning examples include correcting a spelling mistake in the description
description statements or changing indentation), or changes to of a leaf within a YANG module or submodule, non-significant
YANG comments. Note: restructuring how a module uses, or does not whitespace changes (e.g., realigning description statements or
use, submodules is treated as an editorial level change on the changing indentation), or changes to YANG comments. Note:
condition that there is no change in the module's semantic restructuring how a module uses, or does not use, submodules is
behavior due to the restructuring. treated as an editorial level change on the condition that there
is no change in the module's semantic behavior due to the
restructuring.
* '_COMPAT' is an additional modifier, unique to YANG Semver (i.e., * '_COMPAT' is an additional modifier, unique to YANG Semver (i.e.,
not valid in [SemVer] ), that indicates backwards-compatible, or not valid in [SemVer] ), that indicates backwards-compatible, or
non-backwards-compatible changes relative to versions with the non-backwards-compatible changes relative to versions with the
same MAJOR and MINOR version numbers, but lower PATCH version same MAJOR and MINOR version numbers, but lower PATCH version
number, depending on what form modifier '_COMPAT' takes: number, depending on what form modifier '_COMPAT' takes.
The branching limitations that arise from these rules are
described in Section 4.4.3. The modifier takes the following
forms:
- If the modifier string is absent, the change represents an - If the modifier string is absent, the change represents an
editorial change. editorial change.
- If, however, the modifier string is present, the meaning is - If, however, the modifier string is present, the meaning is
described below: described below:
- "_compatible" - the change represents a backwards-compatible - "_compatible" - the change represents a backwards-compatible
change change
- "_non_compatible" - the change represents a non-backwards- - "_non_compatible" - the change represents a non-backwards-
compatible change compatible change
The '_COMPAT' modifier string is "sticky". Once a revision of a The '_COMPAT' modifier string is "sticky" (this applies to published
module has a modifier in the version identifier, then all subsequent versions only as pre-released versions are exempt, see Section 4.5,
module versions in that branch (i.e., those with the same X.Y version rule 4). Once a published version of a module has a modifier in the
digits) will also have a modifier. The modifier can change from version identifier, then all subsequent module versions with the same
"_compatible" to "_non_compatible" in a subsequent version, but the X.Y version digits will also have a modifier. The modifier can
modifier MUST NOT change from "_non_compatible" to "_compatible" and change from "_compatible" to "_non_compatible" in a subsequent
MUST NOT be removed. The persistence of the "_non_compatible" version, but the modifier MUST NOT change from "_non_compatible" to
modifier ensures that comparisons of versions do not give the false "_compatible" and MUST NOT be removed. The persistence of the
impression of compatibility between two potentially non-compatible "_non_compatible" modifier ensures that comparisons of versions do
versions. If "_non_compatible" was removed, for example between not give the false impression of compatibility between two
versions "3.3.2_non_compatible" and "3.3.3" (where "3.3.3" was simply potentially non-compatible versions. If "_non_compatible" was
an editorial change), then comparing versions "3.3.3" to "3.0.0" removed, for example between versions "3.3.2_non_compatible" and
would look like they are backwards compatible when they are not "3.3.3" (where "3.3.3" was simply an editorial change), then
(since "3.3.2_non_compatible" was on the same MAJOR.MINOR branch and comparing versions "3.3.3" to "3.0.0" would look like they are
introduced a non-backwards-compatible change). backwards compatible when they are not (since "3.3.2_non_compatible"
was on the same MAJOR.MINOR branch and introduced a non-backwards-
compatible change).
The YANG artifact name and YANG semantic version uniquely identify a The YANG artifact name and YANG semantic version uniquely identify a
revision of said artifact. There MUST NOT be multiple instances of a revision of said artifact. There MUST NOT be multiple instances of a
YANG artifact definition with the same name and YANG semantic version YANG artifact definition with the same name and YANG semantic version
but different content (and in the case of modules and submodules, but different content (and in the case of modules and submodules,
different revision dates). different revision dates).
There MUST NOT be multiple versions of a YANG artifact that have the There MUST NOT be multiple versions of a YANG artifact that have the
same MAJOR, MINOR and PATCH version numbers, but different patch same MAJOR, MINOR and PATCH version numbers, but different patch
modifier strings. E.g., artifact version "1.2.3_non_compatible" MUST modifier strings. E.g., artifact version "1.2.3_non_compatible" MUST
skipping to change at page 11, line 4 skipping to change at page 11, line 39
0.1.0 - first pre-release module version 0.1.0 - first pre-release module version
0.2.0 - second pre-release module version (with NBC changes) 0.2.0 - second pre-release module version (with NBC changes)
1.0.0 - first release (may have NBC changes from 0.2.0) 1.0.0 - first release (may have NBC changes from 0.2.0)
1.1.0 - added new functionality, leaf "foo" (BC) 1.1.0 - added new functionality, leaf "foo" (BC)
1.2.0 - added new functionality, leaf "baz" (BC) 1.2.0 - added new functionality, leaf "baz" (BC)
2.0.0 - change existing model for performance reasons, e.g. re-key 2.0.0 - change existing model for performance reasons, e.g. re-key
list (NBC) list (NBC)
1.3.0 - improve existing functionality, added leaf "foo-64" (BC) 1.3.0 - improve existing functionality, added leaf "foo-64" (BC)
1.1.1_compatible - backport "foo-64" leaf to 1.1.x to avoid 1.1.1_compatible - backport "foo-64" leaf to 1.1.x to avoid
implementing "baz" from 1.2.0. This revision was created after implementing "baz" from 1.2.0. This revision was created after
1.2.0 otherwise it may have been released as 1.2.0. (BC) 1.2.0 otherwise it may have been published as 1.2.0. (BC)
3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf 3.0.0 - NBC bugfix, rename "baz" to "bar"; also add new BC leaf
"wibble"; (NBC) "wibble"; (NBC)
1.3.1_non_compatible - backport NBC fix, rename "baz" to "bar" 1.3.1_non_compatible - backport NBC fix, rename "baz" to "bar"
(NBC) (NBC)
1.2.1_non_compatible - backport NBC fix, rename "baz" to "bar" 1.2.1_non_compatible - backport NBC fix, rename "baz" to "bar"
(NBC) (NBC)
1.1.2_non_compatible - NBC point bug fix, not required in 2.0.0 1.1.2_non_compatible - NBC point bug fix, not required in 2.0.0
due to model changes (NBC) due to model changes (NBC)
1.4.0 - introduce new leaf "ghoti" (BC) 1.4.0 - introduce new leaf "ghoti" (BC)
3.1.0 - introduce new leaf "wobble" (BC) 3.1.0 - introduce new leaf "wobble" (BC)
1.2.2_non_compatible - backport "wibble". This is a BC change but 1.2.2_non_compatible - backport "wibble". This is a BC change but
"non_compatible" modifier is sticky. (BC) "non_compatible" modifier is sticky. (BC)
Note: the "0.Y.Z" pre-release versions above (0.1.0, 0.2.0) do not
carry a '_COMPAT' modifier because pre-release versions are exempt
from the modifier rules (see rule 4 in Section 4.5). Likewise,
"1.0.0" is the initial release and has no earlier same-MAJOR.MINOR
version to be compatible or incompatible with, so no modifier is
needed there, either.
4.4.3. Branching Limitations with YANG Semver 4.4.3. Branching Limitations with YANG Semver
YANG artifacts that use the YANG Semver version scheme MUST ensure YANG artifacts that use the YANG Semver version scheme MUST ensure
that two artifacts with the same MAJOR version number and no that two artifacts with the same MAJOR version number and no
_compatible or _non_compatible modifiers are backwards compatible. _compatible or _non_compatible modifiers are backwards compatible.
Therefore, certain branching schemes cannot be used with YANG Semver. Therefore, certain branching schemes cannot be used with YANG Semver.
For example, the following branching approach using the following For example, the following branching approach using the following
YANG Semver identifiers is not supported: YANG Semver identifiers is not supported:
3.5.0 -- 3.6.0 (add leaf foo) 3.5.0 -- 3.6.0 (add leaf foo)
| |
| |
3.20.0 (added leaf bar) 3.20.0 (added leaf bar)
In this case, given only the YANG Semver identifiers 3.6.0 and In this case, given only the YANG Semver identifiers 3.6.0 and
3.20.0, one would assume that 3.20.0 is backwards compatible with 3.20.0, one would assume that 3.20.0 is backwards compatible with
3.6.0. But in the illegal example above, 3.20.0 is not backwards 3.6.0. But in the illegal example above, 3.20.0 is not backwards
compatible with 3.6.0 since 3.20.0 does not contain the leaf foo. compatible with 3.6.0 since 3.20.0 does not contain the leaf foo.
Branching limitations should be carefully considered when doing Branching limitations should be carefully considered when doing
software development. It is recommended to avoid only incrementing software development. When advancing the main branch of a YANG
the PATCH digit on the main branch of YANG modules. See Appendix B module, incrementing the MINOR component rather than only the PATCH
Scenario 2 for an illustration and explanation. component can preserve more flexibility for any future branching.
See Appendix B Scenario 2 for an illustration and explanation.
4.5. YANG Semantic Version Update Rules 4.5. YANG Semantic Version Update Rules
When a new version of an artifact is produced, then the following When a new version of an artifact is produced, then the following
rules define how the YANG semantic version for the new artifact is rules define how the YANG semantic version for the new artifact is
calculated, based on the changes between the two artifact versions, calculated, based on the changes between the two artifact versions,
and the YANG semantic version of the original artifact from which the and the YANG semantic version of the original artifact from which the
changes are derived. changes are derived.
Additional pre-release rules for modules that have had at least one
release are specified in Section 6.
The following four rules specify the RECOMMENDED, and REQUIRED The following four rules specify the RECOMMENDED, and REQUIRED
minimum, update to a YANG semantic version: minimum, update to a YANG semantic version. (A separate set of
OPTIONAL rules, describing more significant updates an author MAY
choose, follows these four.)
1. If an artifact is being updated in a non-backwards-compatible 1. If an artifact is being updated in a non-backwards-compatible
way, then the artifact version way, then the artifact version
"X.Y.Z[_compatible|_non_compatible]" SHOULD be updated to "X.Y.Z[_compatible|_non_compatible]" SHOULD be updated to
"X+1.0.0" unless that version has already been used for this "X+1.0.0". If "X+1.0.0" has already been used for this artifact
artifact but with different content, in which case the artifact but with different content, the artifact version
version "X.Y.Z+1_non_compatible" SHOULD be used instead. "X.Y.Z+1_non_compatible" SHOULD be used instead. An artifact
author MAY choose a more significant MAJOR component update, as
described later in this section.
2. If an artifact is being updated in a backwards-compatible way, 2. If an artifact is being updated in a backwards-compatible way,
then the next version number depends on the format of the current then the next version number depends on the format of the current
version number: version number:
i "X.Y.Z" - the artifact version SHOULD be updated to i "X.Y.Z" - the artifact version SHOULD be updated to
"X.Y+1.0", unless that version has already been used for "X.Y+1.0". Where "X.Y+1.0" has already been used for this
this artifact but with different content, when the artifact artifact but with different content, the artifact version
version SHOULD be updated to "X.Y.Z+1_compatible" instead. MUST be updated to "X.Y.Z+1_compatible" instead.
ii "X.Y.Z_compatible" - the artifact version SHOULD be updated ii "X.Y.Z_compatible" - the artifact version SHOULD be updated
to "X.Y.Z+1_compatible". to "X.Y.Z+1_compatible".
iii "X.Y.Z_non_compatible" - the artifact version SHOULD be iii "X.Y.Z_non_compatible" - the artifact version SHOULD be
updated to "X.Y.Z+1_non_compatible". updated to "X.Y.Z+1_non_compatible".
3. If an artifact is being updated in an editorial way, then the 3. If an artifact is being updated in an editorial way, then the
next version identifier depends on the format of the current next version identifier depends on the format of the current
version identifier: version identifier:
skipping to change at page 13, line 9 skipping to change at page 14, line 12
i "X.Y.Z" - the artifact version SHOULD be updated to i "X.Y.Z" - the artifact version SHOULD be updated to
"X.Y.Z+1" "X.Y.Z+1"
ii "X.Y.Z_compatible" - the artifact version SHOULD be updated ii "X.Y.Z_compatible" - the artifact version SHOULD be updated
to "X.Y.Z+1_compatible". to "X.Y.Z+1_compatible".
iii "X.Y.Z_non_compatible" - the artifact version SHOULD be iii "X.Y.Z_non_compatible" - the artifact version SHOULD be
updated to "X.Y.Z+1_non_compatible". updated to "X.Y.Z+1_non_compatible".
4. YANG artifact semantic version identifiers beginning with 0, 4. YANG artifact semantic version identifiers beginning with 0,
i.e., "0.X.Y", are regarded as pre-release definitions and need i.e., "0.Y.Z", are regarded as pre-release definitions and need
not follow the rules above. Either the MINOR or PATCH version not follow the rules above. Either the MINOR or PATCH version
numbers may be updated, regardless of whether the changes are numbers may be updated, regardless of whether the changes are
non-backwards-compatible, backwards-compatible, or editorial. non-backwards-compatible, backwards-compatible, or editorial.
See Section 6 for more details on using this notation during See Section 6 for more details on using this notation during
module and submodule development. module and submodule development.
5. Additional pre-release rules for modules that have had at least
one release are specified in Section 6.
Although artifacts SHOULD be updated according to the rules above, Although artifacts SHOULD be updated according to the rules above,
which specify the recommended (and minimum required) update to the which specify the recommended (and minimum required) update to the
version identifier, the following rules MAY be applied when choosing version identifier, the following rules MAY be applied when choosing
a new version identifier: a new version identifier:
1. An artifact author MAY update the version identifier with a more 1. An artifact author MAY update the version identifier with a more
significant update than described by the rules above. For significant update than described by the rules above. For
example, an artifact could be given a new MAJOR version number example, an artifact could be given a new MAJOR version number
(i.e., X+1.0.0), even though no non-backwards-compatible changes (i.e., X+1.0.0), even though no non-backwards-compatible changes
have occurred, or an artifact could be given a new MINOR version have occurred, or an artifact could be given a new MINOR version
number (i.e., X.Y+1.0) even if the changes were only editorial. number (i.e., X.Y+1.0) even if the changes were only editorial.
2. An artifact author MAY skip versions. For example, a vendor 2. An artifact author MAY skip versions. For example, a vendor
might have released 1.0.0 of a module for general availability. might have published 1.0.0 of a module for general availability.
Then, during subsequent development, used 1.1.0 and 1.2.0 for Then, during subsequent development, used 1.1.0 and 1.2.0 for
internal releases. The next generally available release could be internal releases. The next generally available release could be
1.3.0 where external users never see 1.1.0 or 1.2.0. 1.3.0 where external users never see 1.1.0 or 1.2.0.
Although YANG Semver always indicates when a non-backwards- Although YANG Semver always indicates when a non-backwards-
compatible, or backwards-compatible change may have occurred to a compatible, or backwards-compatible change may have occurred to a
YANG artifact, it does not guarantee that such a change has occurred, YANG artifact, it does not guarantee that such a change has occurred,
or that consumers of that YANG artifact will be impacted by the or that consumers of that YANG artifact will be impacted by the
change. Hence, tooling, e.g., change. Hence, tooling, e.g.,
[I-D.ietf-netmod-yang-schema-comparison], also plays an important [I-D.ietf-netmod-yang-schema-comparison], also plays an important
role for comparing YANG artifacts and calculating the likely impact role for comparing YANG artifacts and calculating the likely impact
from changes. from changes.
[I-D.ietf-netmod-yang-module-versioning] defines the "rev:non- [I-D.ietf-netmod-yang-module-versioning] defines the "rev:non-
backwards-compatible" extension statement to indicate where non- backwards-compatible" extension statement to indicate where non-
backwards-compatible changes have occurred in the module revision backwards-compatible changes have occurred in the module revision
history. If a revision entry in a module's revision history includes history. If a revision entry in a module's revision history includes
the "rev:non-backwards-compatible" statement then that MUST be the "rev:non-backwards-compatible" statement then that MUST be
reflected in any YANG semantic version associated with that revision. reflected in any YANG semantic version associated with that revision.
However, the reverse does not necessarily hold, i.e., if the MAJOR That is, the version MUST either increment the MAJOR component or
version has been incremented it does not necessarily mean that a increment the PATCH component and carry the "_non_compatible"
"rev:non-backwards-compatible" statement would be present. modifier relative to the prior version. However, the reverse does
not necessarily hold, i.e., if the MAJOR version has been incremented
it does not necessarily mean that a "rev:non-backwards-compatible"
statement would be present.
4.6. Examples of the YANG Semver Version Identifier 4.6. Examples of the YANG Semver Version Identifier
4.6.1. Example Module Using YANG Semver 4.6.1. Example Module Using YANG Semver
Below is a sample YANG module that uses YANG Semver based on the Below is a sample YANG module that uses YANG Semver based on the
rules defined in this document. rules defined in this document. The following diagram illustrates
the revision history captured by the module's revision statements,
from the initial published version through the latest revision (the
chronological order matches the order in which the versions were
published):
Module revision date YANG Semver version identifier
2017-02-07 <- 1.0.0
|
2017-04-03 <- 1.1.0
|
2017-04-20 <- 1.2.0
|
2017-07-30 <- 1.2.1_non_compatible
|
2017-08-30 <- 1.2.2_non_compatible
Figure 3
module example-versioned-module { module example-versioned-module {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:versioned:module"; namespace "urn:example:versioned:module";
prefix "exvermod"; prefix "exvermod";
import ietf-yang-revisions { prefix "rev"; } import ietf-yang-revisions { prefix "rev"; }
import ietf-yang-semver { prefix "ysv"; } import ietf-yang-semver { prefix "ysv"; }
description description
skipping to change at page 15, line 4 skipping to change at page 16, line 17
revision 2017-04-20 { revision 2017-04-20 {
description "Add new functionality, leaf 'baz'"; description "Add new functionality, leaf 'baz'";
ysv:version 1.2.0; ysv:version 1.2.0;
} }
revision 2017-04-03 { revision 2017-04-03 {
description "Add new functionality, leaf 'foo'"; description "Add new functionality, leaf 'foo'";
ysv:version 1.1.0; ysv:version 1.1.0;
} }
revision 2017-02-07 { revision 2017-02-07 {
description "First release version."; description "First published version.";
ysv:version 1.0.0; ysv:version 1.0.0;
} }
// Note: YANG Semver rules do not apply to 0.X.Y labels. // Note: YANG Semver rules do not apply to 0.Y.Z versions.
// The following pre-release revision statements would not // The following pre-release revision statements would not
// appear in any final published version of a module. They // appear in any final published version of a module. They
// are removed when the final version is published. // are removed when the final version is published.
// During the pre-release phase of development, only a // During the pre-release phase of development, only a
// single one of these revision statements would appear // single one of these revision statements would appear
// revision 2017-01-30 { // revision 2017-01-30 {
// description "NBC changes to initial revision"; // description "NBC changes to initial revision";
// ysv:version 0.2.0; // ysv:version 0.2.0;
// rev:non-backwards-compatible; // optional // rev:non-backwards-compatible; // optional
// // (theoretically no // // (theoretically no
// // 'previous released version') // // 'previous published version')
// } // }
// revision 2017-01-26 { // revision 2017-01-26 {
// description "Initial module version"; // description "Initial module version";
// ysv:version 0.1.0; // ysv:version 0.1.0;
// } // }
//YANG module definition starts here //YANG module definition starts here
container example { container example {
description description
skipping to change at page 16, line 38 skipping to change at page 18, line 4
{ {
"name": "example-yang-pkg", "name": "example-yang-pkg",
"version": "1.3.1", "version": "1.3.1",
... ...
} }
] ]
} }
} }
} }
} }
Figure 4
Figure 3
5. Import Module by YANG Semantic Version 5. Import Module by YANG Semantic Version
[I-D.ietf-netmod-yang-module-versioning] defines the rev:recommended- [I-D.ietf-netmod-yang-module-versioning] defines the rev:recommended-
min-date extension that allows for the imported revision to be min-date extension that allows for the imported revision to be
selected based on any revision that matches -- or is later -- than selected based on any revision that matches -- or is later -- than
the specified revision date in the import. This section defines a the specified revision date in the import. This section defines a
similar extension for controlling import by YANG semantic version, as similar extension for controlling import by YANG semantic version, as
well as the rules for how imports are resolved. well as the rules for how imports are resolved.
skipping to change at page 17, line 28 skipping to change at page 18, line 38
import example-module { import example-module {
ysv:recommended-min-version 3.0.0; ysv:recommended-min-version 3.0.0;
} }
5.2. Import by YANG Semantic Version Rules 5.2. Import by YANG Semantic Version Rules
When evaluating target module to import, only the numeric triplet of When evaluating target module to import, only the numeric triplet of
MAJOR.MINOR.PATCH is considered. The "_compatible" and MAJOR.MINOR.PATCH is considered. The "_compatible" and
"_non_compatible" modifiers as well as any metadata are ignored. A "_non_compatible" modifiers as well as any metadata are ignored. A
module to be imported is considered as meeting the recommended module to be imported is considered as meeting the recommended
minimum version criteria if it meets one of the following conditions: minimum version criteria if it meets at least one of the following
conditions (the conditions are not listed in priority order and any
single matching condition is sufficient):
1. Has the exact same MAJOR, MINOR, PATCH as in the recommended-min- 1. Has the exact same MAJOR, MINOR, PATCH as in the recommended-min-
version value. version value.
2. Has the same MAJOR and MINOR version numbers and a greater PATCH 2. Has the same MAJOR and MINOR version numbers and a greater PATCH
number. number.
3. Has the same MAJOR version number and greater MINOR number. In 3. Has the same MAJOR version number and greater MINOR number. In
this case the PATCH number is ignored. this case the PATCH number is ignored.
skipping to change at page 18, line 30 skipping to change at page 19, line 45
version, or a version carrying the "_non_compatible" modifier) to version, or a version carrying the "_non_compatible" modifier) to
satisfy the recommended-min-version. This keeps the import satisfy the recommended-min-version. This keeps the import
resolution rules simple, and reflects the fact that the resolution rules simple, and reflects the fact that the
responsibility for ensuring a coherent set of module versions is responsibility for ensuring a coherent set of module versions is
expected to be handled outside of this extension (e.g., by grouping expected to be handled outside of this extension (e.g., by grouping
modules into YANG packages [I-D.ietf-netmod-yang-packages], which by modules into YANG packages [I-D.ietf-netmod-yang-packages], which by
their nature describe a consistent set of module dependencies). their nature describe a consistent set of module dependencies).
6. Guidelines for Using YANG Semver During Module Development 6. Guidelines for Using YANG Semver During Module Development
This section and the IETF-specific sub-section below provide YANG This section and the IETF-specific subsection below provide YANG
Semver-specific guidelines to consider when developing new YANG Semver-specific guidelines to consider when developing new YANG
modules. As such this section updates Section 4.8 of [RFC9907]. modules. As such this section updates Section 4.8 of [RFC9907].
All modules and submodules being developed or updated that use the All modules and submodules being developed or updated that use the
YANG Semver versioning scheme MUST have unique YANG Semver version YANG Semver versioning scheme MUST have unique YANG Semver version
identifiers throughout their lifecycle. identifiers throughout their lifecycle.
Development of a new YANG module or submodule outside of the IETF Development of a new YANG module or submodule outside of the IETF
that uses the YANG Semver versioning scheme SHOULD begin with a 0 for that uses the YANG Semver versioning scheme SHOULD begin with a 0 for
the MAJOR version component. This allows the module or submodule to the MAJOR version component. This allows the module or submodule to
skipping to change at page 19, line 23 skipping to change at page 20, line 38
1.0.0-beta.42 1.0.0-beta.42
1.0.0-202007.rc 1.0.0-202007.rc
1.0.0-20250106 1.0.0-20250106
1.0.0-03 1.0.0-03
When updating an existing module or submodule using the YANG Semver When updating an existing module or submodule using the YANG Semver
versioning scheme, the intended target semantic version can be used versioning scheme, the intended target semantic version can be used
along with pre-release notation. For example, if a released module along with pre-release notation. For example, if a published module
or submodule which has a current version of 1.0.0 is being modified or submodule which has a current version of 1.0.0 is being modified
with the intent to make non-backwards-compatible changes, the first with the intent to make non-backwards-compatible changes, the first
development MAJOR version component should be 2 with some pre-release development MAJOR version component should be 2 with some pre-release
notation such as -alpha.1, making the version 2.0.0-alpha.1. It may notation such as -alpha.1, making the version 2.0.0-alpha.1. It may
be prudent to include the year or year and month development began be prudent to include the year or year and month development began
(e.g., 2.0.0-201907-alpha.1) in order to guarantee uniqueness. As a (e.g., 2.0.0-201907-alpha.1) in order to guarantee uniqueness. As a
module or submodule undergoes development, it is possible that the module or submodule undergoes development, it is possible that the
original intent changes. For example, a 1.0.0 version of a module or original intent changes. For example, a 1.0.0 version of a module or
submodule that was destined to become 2.0.0 after a development cycle submodule that was destined to become 2.0.0 after a development cycle
may have had a scope change such that the final version has no non- may have had a scope change such that the final version has no non-
backwards-compatible changes and becomes 1.1.0 instead. This change backwards-compatible changes and becomes 1.1.0 instead. This change
is acceptable to make during the development phase so long as pre- is acceptable to make during the development phase so long as pre-
release notation is present in both versions (e.g., 2.0.0-alpha.3 release notation is present in both versions (e.g., 2.0.0-alpha.3
becomes 1.1.0-alpha.4). However, on the next development cycle becomes 1.1.0-alpha.4). However, on the next development cycle
(after 1.1.0 is released), if again the new target release is 2.0.0, (after 1.1.0 is published), if again the new target release is 2.0.0,
new pre-release components must be used such that every version for a new pre-release components must be used such that every version for a
given module or submodule is unique throughout its entire lifecycle given module or submodule is unique throughout its entire lifecycle
(e.g., the first pre-release version might be 2.0.0-202005-alpha.1 if (e.g., the first pre-release version might be 2.0.0-202005-alpha.1 if
keeping the same year and month notation mentioned above). keeping the same year and month notation mentioned above).
Module and submodule developers SHOULD maintain only one revision Module and submodule developers SHOULD maintain only one revision
statement in a pre-released module or submodule that reflects its statement in a pre-released module or submodule that reflects its
latest revision. latest revision.
6.1. YANG Semver in IETF Modules 6.1. YANG Semver in IETF Modules
All published IETF modules and submodules MUST use YANG semantic All published IETF modules and submodules MUST use YANG semantic
versions in their revisions. This is an update to the guidance versions in their revisions. This is an update to the guidance
provided in Section 4.8 of [RFC9907]. As IETF modules are not provided in Section 4.8 of [RFC9907]. As IETF modules are not
expected to require branching in their revision history, the expected to require branching in their revision history, the
'_COMPAT' modifier SHOULD NOT be used in IETF published modules. '_COMPAT' modifier SHOULD NOT be used in IETF published modules. The
modifier would only be appropriate in the unexpected event that an
IETF module's revision history branched (e.g., to maintain an older
MAJOR.MINOR stream).
6.1.1. YANG Semver in New IETF Modules 6.1.1. YANG Semver in New IETF Modules
Development of a new module or submodule (i.e., when there is no Development of a new module or submodule (i.e., when there is no
existing module of the same name) within the IETF MUST begin by using existing module of the same name) within the IETF MUST begin by using
0 as the MAJOR version component. If the Internet Draft containing 0 as the MAJOR version component. If the Internet Draft containing
the module or submodule is an adopted document, pre-release metadata the module or submodule is an adopted document, pre-release metadata
MUST NOT be used. Instead, the Y.Z (i.e., MINOR.PATCH) version MUST NOT be used. Instead, the Y.Z (i.e., MINOR.PATCH) version
components MUST be incremented with new revisions in order to components MUST be incremented with new revisions in order to
maintain version uniqueness. maintain version uniqueness.
skipping to change at page 20, line 39 skipping to change at page 22, line 9
version number MUST be 0. During pre-release IETF draft development, version number MUST be 0. During pre-release IETF draft development,
a simplified notation of the form X.Y.Z-REVISION is used, where a simplified notation of the form X.Y.Z-REVISION is used, where
REVISION is the draft revision number (e.g., 1.1.0-01, 1.1.0-02). REVISION is the draft revision number (e.g., 1.1.0-01, 1.1.0-02).
This notation is described in detail, including the special This notation is described in detail, including the special
considerations for parallel competing drafts, in Section 6.1.3. considerations for parallel competing drafts, in Section 6.1.3.
6.1.2.1. Guidelines for IETF Modules Previously Published without YANG 6.1.2.1. Guidelines for IETF Modules Previously Published without YANG
Semvers Semvers
For IETF YANG modules and submodules that have already been For IETF YANG modules and submodules that have already been
published, versions MUST be retroactively applied to all existing published, versions are retroactively applied to all existing
revisions when the next new revision is created, starting at version revisions when the next new revision is created, starting at version
"1.0.0" for the initial published revision, and then incrementing "1.0.0" for the initial published revision, and then incrementing
according to the YANG Semver version rules specified in Section 4.5. according to the YANG Semver version rules specified in Section 4.5.
For example, if a module or submodule started out in the pre-NMDA For example, if a module or submodule was first published before NMDA
([RFC8342] ) world, and then had NMDA support added without removing ([RFC8342] ) and subsequently had NMDA support added without removing
any legacy "state" branches -- and you are looking to add additional any legacy "state" branches, then when adding additional new features
new features -- a sensible choice for the target YANG Semver would be a sensible choice for the target YANG Semver would be 1.2.0 (since
1.2.0 (since 1.0.0 would have been the initial, pre-NMDA release, and 1.0.0 would have been the initial, pre-NMDA release, and 1.1.0 would
1.1.0 would have been the NMDA revision). have been the NMDA revision).
6.1.3. YANG Semver when there are multiple parallel competing IETF 6.1.3. YANG Semver when there are multiple parallel competing IETF
drafts drafts
Whether a new IETF module is being defined, or a previously published Whether a new IETF module is being defined, or a previously published
IETF module is being updated, special considerations are required IETF module is being updated, special considerations are required
when multiple parallel competing drafts are in progress for a new when multiple parallel competing drafts are in progress for a new
module or a module update. module or a module update.
The following recommendations apply to the 2nd, 3rd, etc. parallel The following recommendations apply to the 2nd, 3rd, etc. parallel
drafts that develop a module or submodule with the same name. The drafts that develop a module or submodule with the same name. The
first draft published can simply use the guidelines above without any first draft published can simply use the guidelines above without any
extra metadata described below. The YANG Semver in subsequent drafts extra metadata described below. The YANG Semver in subsequent drafts
SHOULD include the full document name as a pre-release version SHOULD include the full document name as a pre-release version
identifier, including the current document revision. For example, if identifier, including the current document revision. For example, if
a module or submodule which is currently released at version 1.0.0 is a module or submodule which is currently published at version 1.0.0
being revised to include non-backwards-compatible changes in draft- is being revised to include non-backwards-compatible changes in
user-netmod-foo, its development versions SHOULD include 2.0.0-draft- draft-user-netmod-foo, its development versions SHOULD include 2.0.0-
user-netmod-foo followed by the document's revision (e.g., 2.0.0- draft-user-netmod-foo followed by the document's revision (e.g.,
draft-user-netmod-foo-02). This will ensure each pre-release version 2.0.0-draft-user-netmod-foo-02). This will ensure each pre-release
is unique across the lifecycle of the module or submodule. When version is unique across the lifecycle of the module or submodule.
using the 0 MAJOR version for initial module or submodule development When using the 0 MAJOR version for initial module or submodule
in an individual Internet Draft (where MINOR and PATCH can change), development in an individual Internet Draft (where MINOR and PATCH
appending the draft name as a pre-release component helps to ensure can change), appending the draft name as a pre-release component
uniqueness when there are perhaps multiple, parallel efforts creating helps to ensure uniqueness when there are perhaps multiple, parallel
the same module or submodule. efforts creating the same module or submodule.
Other approaches are also possible to ensure uniqueness of YANG Other approaches are also possible to ensure uniqueness of YANG
Semver identifiers across all parallel competing modules and Semver identifiers across all parallel competing modules and
revisions before IETF adoption including: revisions before IETF adoption including:
1. Using unique module names (i.e., module names with unique 1. Using unique module names (i.e., module names with unique
prefixes such as the author's name, e.g. johnsmith- prefixes such as the author's name, e.g. johnsmith-
interfaces.yang), or interfaces.yang), or
2. Using unique strings within the YANG Semver pre-release metadata 2. Using unique strings within the YANG Semver pre-release metadata
skipping to change at page 23, line 4 skipping to change at page 24, line 18
+--ro version? ysv:version +--ro version? ysv:version
augment /yanglib:yang-library/yanglib:module-set/yanglib:module augment /yanglib:yang-library/yanglib:module-set/yanglib:module
/yanglib:submodule: /yanglib:submodule:
+--ro version? ysv:version +--ro version? ysv:version
augment /yanglib:yang-library/yanglib:module-set augment /yanglib:yang-library/yanglib:module-set
/yanglib:import-only-module: /yanglib:import-only-module:
+--ro version? ysv:version +--ro version? ysv:version
augment /yanglib:yang-library/yanglib:module-set augment /yanglib:yang-library/yanglib:module-set
/yanglib:import-only-module/yanglib:submodule: /yanglib:import-only-module/yanglib:submodule:
+--ro version? ysv:version +--ro version? ysv:version
Figure 4
Figure 5
7.1.1. Advertising version 7.1.1. Advertising version
The ietf-yang-library-semver YANG module augments the "module" and The ietf-yang-library-semver YANG module augments the "module" and
"submodule" lists in ietf-yang-library with "version" leafs to "submodule" lists in ietf-yang-library with "version" leafs to
optionally declare the version identifier associated with each module optionally declare the version identifier associated with each module
and submodule. and submodule.
8. YANG Modules 8. YANG Modules
skipping to change at page 28, line 37 skipping to change at page 30, line 4
"Add a version to submodule information"; "Add a version to submodule information";
uses module-version; uses module-version;
} }
augment "/yanglib:yang-library/yanglib:module-set/" augment "/yanglib:yang-library/yanglib:module-set/"
+ "yanglib:import-only-module" { + "yanglib:import-only-module" {
description description
"Add a version to module information"; "Add a version to module information";
uses module-version; uses module-version;
} }
augment "/yanglib:yang-library/yanglib:module-set/" augment "/yanglib:yang-library/yanglib:module-set/"
+ "yanglib:import-only-module/yanglib:submodule" { + "yanglib:import-only-module/yanglib:submodule" {
description description
"Add a version to submodule information"; "Add a version to submodule information";
uses module-version; uses module-version;
} }
} }
<CODE ENDS> <CODE ENDS>
9. Contributors 9. Contributors
The following people made substantial contributions to this document: The following people made substantial contributions to this document:
Bo Wu Bo Wu
lana.wubo@huawei.com lana.wubo@huawei.com
Jan Lindblad Jan Lindblad
jlindbla@cisco.com jlindbla@cisco.com
Figure 5 Figure 6
10. Acknowledgments 10. Acknowledgments
This document grew out of the YANG module versioning design team that This document grew out of the YANG module versioning design team that
started after IETF 101. The team consists of the following members started after IETF 101. The team consists of the following members
whom have worked on the YANG versioning project: Balazs Lengyel, whom have worked on the YANG versioning project: Balazs Lengyel,
Benoit Claise, Bo Wu, Ebben Aries, Jan Lindblad, Jason Sterne, Joe Benoit Claise, Bo Wu, Ebben Aries, Jan Lindblad, Jason Sterne, Joe
Clarke, Juergen Schoenwaelder, Mahesh Jethanandani, Michael Clarke, Juergen Schoenwaelder, Mahesh Jethanandani, Michael
(Wangzitao), Per Andersson, Qin Wu, Reshad Rahman, Tom Hill, and Rob (Wangzitao), Per Andersson, Qin Wu, Reshad Rahman, Tom Hill, and Rob
Wilton. Wilton.
skipping to change at page 31, line 4 skipping to change at page 32, line 16
Maintained by IANA? N Maintained by IANA? N
Reference: [RFCXXXX] Reference: [RFCXXXX]
The ietf-yang-library-semver module: The ietf-yang-library-semver module:
Name: ietf-yang-library-semver Name: ietf-yang-library-semver
XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library- XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library-
semver semver
Prefix: yl-semver Prefix: yl-semver
Maintained by IANA? N Maintained by IANA? N
Reference: [RFCXXXX] Reference: [RFCXXXX]
12.2. Guidance for YANG Semver in IANA maintained YANG modules and 12.2. Guidance for YANG Semver in IANA maintained YANG modules and
submodules submodules
Note for IANA (to be removed by the RFC editor): Please check that Note for IANA (to be removed by the RFC editor): Please check that
the registries and IANA YANG modules and submodules are referenced in the registries and IANA YANG modules and submodules are referenced in
the appropriate way. the appropriate way.
IANA is responsible for maintaining and versioning all IANA (iana-) IANA is responsible for maintaining and versioning all IANA (iana-)
YANG modules and submodules, e.g., iana-if-types.yang [IfTypeYang] YANG modules and submodules, e.g., iana-if-types.yang [IfTypeYang]
and iana-routing-types.yang [RoutingTypesYang]. and iana-routing-types.yang [RoutingTypesYang].
In addition to following the rules specified in the IANA In addition to following the rules specified in the IANA
Considerations section of [I-D.ietf-netmod-yang-module-versioning], Considerations section of [I-D.ietf-netmod-yang-module-versioning],
IANA maintained YANG modules and submodules MUST also include a YANG IANA maintained YANG modules and submodules are to include a YANG
Semver version identifier for all new revisions, as defined in Semver version identifier for all new revisions, as defined in
Section 4. Section 4.
The YANG Semver version associated with the new revision MUST follow The YANG Semver version associated with the new revision follows the
the rules defined in Section 4.5. rules defined in Section 4.5.
Note: For IANA maintained YANG modules and submodules that have Note: For IANA maintained YANG modules and submodules that have
already been published, versions MUST be retroactively applied to all already been published, versions are retroactively applied to all
existing revisions when the next new revision is created, starting at existing revisions when the next new revision is created, starting at
version "1.0.0" for the initial published revision, and then version "1.0.0" for the initial published revision, and then
incrementing according to the YANG Semver rules specified in incrementing according to the YANG Semver rules specified in
Section 4.5. Section 4.5.
Most changes to IANA maintained YANG modules and submodules are Most changes to IANA maintained YANG modules and submodules are
expected to be backwards-compatible changes and classified as MINOR expected to be backwards-compatible changes and classified as MINOR
version changes. The PATCH version may be incremented instead when version changes. The PATCH version may be incremented instead when
only editorial changes are made, and the MAJOR version would be only editorial changes are made, and the MAJOR version would be
incremented if non-backwards-compatible changes are made. incremented if non-backwards-compatible changes are made.
skipping to change at page 33, line 29 skipping to change at page 34, line 39
[I-D.ietf-netmod-yang-packages] [I-D.ietf-netmod-yang-packages]
Wilton, R., Rahman, R., Clarke, J., and J. Sterne, "YANG Wilton, R., Rahman, R., Clarke, J., and J. Sterne, "YANG
Packages", Work in Progress, Internet-Draft, draft-ietf- Packages", Work in Progress, Internet-Draft, draft-ietf-
netmod-yang-packages-07, 2 March 2026, netmod-yang-packages-07, 2 March 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod- <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
yang-packages-07>. yang-packages-07>.
[I-D.ietf-netmod-yang-schema-comparison] [I-D.ietf-netmod-yang-schema-comparison]
Andersson, P., Wilton, R., and M. Vaško, "YANG Schema Andersson, P., Wilton, R., and M. Vaško, "YANG Schema
Comparison", Work in Progress, Internet-Draft, draft-ietf- Comparison", Work in Progress, Internet-Draft, draft-ietf-
netmod-yang-schema-comparison-07, 5 May 2026, netmod-yang-schema-comparison-08, 27 May 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod- <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
yang-schema-comparison-07>. yang-schema-comparison-08>.
[RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252,
January 2006, <https://www.rfc-editor.org/info/rfc4252>. January 2006, <https://www.rfc-editor.org/info/rfc4252>.
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>. <https://www.rfc-editor.org/info/rfc8340>.
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
skipping to change at page 36, line 26 skipping to change at page 37, line 36
| |
1.1.0-03 1.1.0-03
The draft is standardized, and the new module version becomes 1.1.0. The draft is standardized, and the new module version becomes 1.1.0.
Appendix B. Examples of _COMPAT Modifier Use Appendix B. Examples of _COMPAT Modifier Use
The following scenarios illustrate some situations where the _COMPAT The following scenarios illustrate some situations where the _COMPAT
modifier (i.e., _compatible and _non_compatible) might be used in the modifier (i.e., _compatible and _non_compatible) might be used in the
YANG Semver of a YANG module. While module development is considered YANG Semver of a YANG module. While module development is considered
here, this is appliacable to any YANG artifact. here, this is applicable to any YANG artifact.
In the scenarios below, the X axis represents relative time (date & In the scenarios below, the X axis represents relative time (date &
time) that a module is being published. Module versions to the right time) that a module is being published. Module versions to the right
are more recent than module versions to the left. In scenario 1, for are more recent than module versions to the left. In scenario 1, for
example, the time ordered publishing of module versions is: 2.0.0, example, the time ordered publishing of module versions is: 2.0.0,
2.1.0, 3.0.0, A, B. 2.1.0, 3.0.0, A, B.
It is also useful to consider the leftmost sequence (diagonal column) It is also useful to consider the leftmost sequence (diagonal column)
of versions (going mostly downwards and slightly right) as the "main of versions (going mostly downwards and slightly right) as the "main
branch" in a software development branching scheme, and the sequence branch" in a software development branching scheme, and the sequence
of versions moving rightwards (rows) as bug fixes in released of versions moving rightwards (rows) as bug fixes in published
branches (i.e., maintenance releases in a single major release branches (i.e., maintenance releases in a single major release
stream). stream).
These scenarios are generally more applicable for vendor modules These scenarios are generally more applicable for vendor modules
(which require modifications that are not at the head of the main (which require modifications that are not at the head of the main
branch) and not expected to occur much in modules published by branch) and not expected to occur much in modules published by
standard bodies (which tend to be linear and only update the head of standard bodies (which tend to be linear and only update the head of
the single branch). the single branch).
2.0.0-----A 2.0.0-----A
\ \
\ \
2.1.0------B 2.1.0------B
\ \
\ \
3.0.0 3.0.0
Figure 6: Scenario 1 Figure 7: Scenario 1
For each revision A and B, the following are possible YANG Semver For each revision A and B, the following are possible YANG Semver
versions when the revision is backwards comptible (BC) or non versions when the revision is backwards-compatible (BC) or non-
backwards compatible (NBC): backwards-compatible (NBC):
Revision A (BC): 2.0.1_compatible Revision A (BC): 2.0.1_compatible
Revision A (NBC): 2.0.1_non_compatible Revision A (NBC): 2.0.1_non_compatible
2.2.0 is not allowed for A (see Section 4.4.3), and 4.0.0 is not 2.2.0 is not allowed for A (see Section 4.4.3), and 4.0.0 is not
recommended (likely to cause confusion since it does not have 3.0.0 recommended (likely to cause confusion since it does not have 3.0.0
as an ancestor). as an ancestor).
2.0.0 2.0.0
\ \
\ \
2.1.0----------N 2.1.0----------N
\ \
\ \
2.2.0-----------P 2.2.0-----------P
\ \
\ \
2.2.1-------------Q 2.2.1-------------Q
Figure 7: Scenario 2 Figure 8: Scenario 2
For each revision N, P and Q, the following are possible YANG Semver For each revision N, P and Q, the following are possible YANG Semver
versions when the revision is backwards comptible (BC) or non versions when the revision is backwards-compatible (BC) or non-
backwards compatible (NBC): backwards-compatible (NBC):
Revision N (BC): 2.1.1_compatible Revision N (BC): 2.1.1_compatible
Revision N (NBC): 2.1.1_non_compatible Revision N (NBC): 2.1.1_non_compatible
Revision P: This is a situation that illustrates the limits of Revision P: This is a situation that illustrates the limits of
branching in YANG Semver. It is not recommended to create any new BC branching in YANG Semver. It is not recommended to create any new BC
or NBC version off of 2.2.0. One approach to avoid this situation is or NBC version off of 2.2.0. One approach to avoid this situation is
to avoid only incrementing the PATCH digit in the main branch (i.e., to avoid only incrementing the PATCH digit in the main branch (i.e.,
increment at least the MINOR digit). increment at least the MINOR digit).
 End of changes. 61 change blocks. 
159 lines changed or deleted 212 lines changed or added

This html diff was produced by rfcdiff 1.49. The latest version is available from https://github.com/ietf-tools/rfcdiff