YANG Semantic Versioning

4.1. Relationship Between SemVer and YANG Semver

[SemVer] is completely compatible with YANG Semver in that a SemVer semantic version number is legal according to the YANG Semver rules (though the inverse is not necessarily true). YANG Semver is a superset of the SemVer rules, and allows for limited branching within YANG artifacts. If no branching occurs within a YANG artifact (i.e., you do not use the compatibility modifiers described below), the YANG Semver version label will appear as a SemVer version number.¶

4.2. YANG Semantic Version Extension

The ietf-yang-semver module defines a "version" extension -- a substatement to a module or submodule's "revision" statement -- that takes a YANG semantic version as its argument and specified the version for the given module or submodule. The syntax for the YANG semantic version is defined in a typedef in the same module and described below.¶

4.3. YANG Semver Pattern

YANG artifacts that employ semantic versioning as defined in this document MUST use a version identifier that corresponds to the following pattern: 'X.Y.Z_COMPAT'. Where:¶

• 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 integer value) and MUST NOT contain leading zeroes,¶
• The '.' is a literal period (ASCII character 0x2e),¶
• The '_' is an optional single literal underscore (ASCII character 0x5f) and MUST only be present if the following COMPAT element is included,¶
• COMPAT, if specified, MUST be either the literal string "compatible" or the literal string "non_compatible".¶

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 YANG Semver string after a trailing '-' character. Build metadata MAY be appended after a trailing '+' character. If both pre-release and build metadata are present, then build metadata MUST follow pre-release metadata. While build metadata MUST be ignored when comparing YANG semantic versions, pre-release metadata MUST be used during module and submodule development as specified in Section 6. Both pre-release and build metadata are allowed in order to support all the [SemVer] rules. Thus, a version lineage that follows strict [SemVer] rules is allowed for a YANG artifact.¶

The ietf-yang-semver module included in this document defines an extension to apply a YANG Semver identifier to a YANG artifact as well as a typedef that formally specifies the syntax of the YANG Semver.¶

4.4. Semantic Versioning Scheme for YANG Artifacts

This document defines the YANG semantic versioning scheme that is used for YANG artifacts. The versioning identifier has the following properties:¶

• The YANG semantic versioning scheme is extended from version 2.0.0 of the semantic versioning scheme defined at semver.org [SemVer] to cover the additional requirements for the management of YANG artifact lifecycles that cannot be addressed using the semver.org 2.0.0 versioning scheme alone.¶
• Unlike the [SemVer] versioning scheme, the YANG semantic versioning scheme supports updates to older versions of YANG artifacts, to allow for bug fixes and enhancements to artifact versions that are not the latest. However, it does not provide for the unlimited branching and updating of older revisions which are documented by the general rules in [I-D.ietf-netmod-yang-module-versioning].¶
• YANG artifacts that use the [SemVer] versioning scheme are fully compatible with implementations that understand the YANG semantic versioning scheme defined in this document.¶
• If updates are always restricted to the latest revision of the artifact only, then the version identifiers used by the YANG semantic versioning scheme are exactly the same as those defined by the [SemVer] versioning scheme.¶

Every YANG module and submodule versioned using the YANG semantic versioning scheme specifies the module's or submodule's semantic version as the argument to the 'ys:version' statement.¶

Because the rules put forth in [I-D.ietf-netmod-yang-module-versioning] are designed to work well with existing versions of YANG and allow for artifact authors to migrate to this scheme, it is not expected that all revisions of a given YANG artifact will have a semantic version identifier. For example, the first revision of a module or submodule may have been produced before this scheme was available.¶

YANG packages that make use of this YANG Semver will reflect that in the package metadata.¶

As stated above, the YANG semantic version is expressed as a string of the form: 'X.Y.Z_COMPAT'.¶

• 'X' is the MAJOR version. Changes in the MAJOR version number indicate changes that are non-backwards-compatible to versions with a lower MAJOR version number.¶
• 'Y' is the MINOR version. Changes in the MINOR version number indicate changes that are backwards-compatible to versions with the same MAJOR version number, but a lower MINOR version number and no "_compatible" or "_non_compatible" modifier.¶
• 'Z' is the PATCH version. Changes in the PATCH version number can indicate an editorial change to the YANG artifact. In conjunction with the '_COMPAT' modifier (see below) changes to 'Z' may indicate a more substantive module change. An editorial change is defined to be a change in the YANG artifact's content that does not affect the semantic meaning or functionality provided by the artifact in any way. Some examples include correcting a spelling mistake in the description of a leaf within a YANG module or submodule, non-significant whitespace changes (e.g., realigning description statements or changing indentation), or changes to YANG comments. Note: restructuring how a module uses, or does not use, submodules is 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., not valid in [SemVer] ), that indicates backwards-compatible, or non-backwards-compatible changes relative to versions with the same MAJOR and MINOR version numbers, but lower PATCH version number, depending on what form modifier '_COMPAT' takes:¶

  • If the modifier string is absent, the change represents an editorial change.¶
  • If, however, the modifier string is present, the meaning is described below:¶
  • "_compatible" - the change represents a backwards-compatible change¶
  • "_non_compatible" - the change represents a non-backwards-compatible change¶

The '_COMPAT' modifier string is "sticky". Once a revision of a module has a modifier in the version identifier, then all subsequent modules in that branch (i.e., those with the same X.Y version digits) will also have a modifier. The modifier can change from "_compatible" to "_non_compatible" in a subsequent version, but the modifier MUST NOT change from "_non_compatible" to "_compatible" and MUST NOT be removed. The persistence of the "_non_compatible" modifier ensures that comparisons of versions do not give the false impression of compatibility between two potentially non-compatible versions. If "_non_compatible" was removed, for example between versions "3.3.2_non_compatible" and "3.3.3" (where "3.3.3" was simply an editorial change), then comparing versions "3.3.3" to "3.0.0" would look like they are 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 revision of said artifact. There MUST NOT be multiple instances of a YANG artifact definition with the same name and YANG semantic version but different content (and in the case of modules and submodules, different revision dates).¶

There MUST NOT be multiple versions of a YANG artifact that have the same MAJOR, MINOR and PATCH version numbers, but different patch modifier strings. E.g., artifact version "1.2.3_non_compatible" MUST NOT be defined if artifact version "1.2.3" has already been defined.¶

      3.5.0 -- 3.6.0 (add leaf foo)
        |
        |
      3.20.0 (added leaf bar)

         0.1.0
           |
         0.2.0
           |
         1.0.0
           |
         1.1.0 -> 1.1.1_compatible -> 1.1.2_non_compatible
           |
         1.2.0 -> 1.2.1_non_compatible -> 1.2.2_non_compatible
           |  \
         2.0.0 \
           |    \--> 1.3.0 -> 1.3.1_non_compatible
         3.0.0         |
           |         1.4.0
         3.1.0

4.5. YANG Semantic Version Update Rules

When a new version of an artifact is produced, then the following rules define how the YANG semantic version for the new artifact is calculated, based on the changes between the two artifact versions, and the YANG semantic version of the original artifact from which the changes are derived.¶

The following four rules specify the RECOMMENDED, and REQUIRED minimum, update to a YANG semantic version:¶

1. If an artifact is being updated in a non-backwards-compatible way, then the artifact version "X.Y.Z[_compatible|_non_compatible]" SHOULD be updated to "X+1.0.0" unless that version has already been used for this artifact but with different content, in which case the artifact version "X.Y.Z+1_non_compatible" SHOULD be used instead.¶

2. If an artifact is being updated in a backwards-compatible way, then the next version number depends on the format of the current version number:¶

   i

   "X.Y.Z" - the artifact version SHOULD be updated to "X.Y+1.0", unless that version has already been used for this artifact but with different content, when the artifact version SHOULD be updated to "X.Y.Z+1_compatible" instead.¶

   ii

   "X.Y.Z_compatible" - the artifact version SHOULD be updated to "X.Y.Z+1_compatible".¶

   iii

   "X.Y.Z_non_compatible" - the artifact version SHOULD be updated to "X.Y.Z+1_non_compatible".¶

3. If an artifact is being updated in an editorial way, then the next version identifier depends on the format of the current version identifier:¶

   i

   "X.Y.Z" - the artifact version SHOULD be updated to "X.Y.Z+1"¶

   ii

   "X.Y.Z_compatible" - the artifact version SHOULD be updated to "X.Y.Z+1_compatible".¶

   iii

   "X.Y.Z_non_compatible" - the artifact version SHOULD be updated to "X.Y.Z+1_non_compatible".¶

4. YANG artifact semantic version identifiers beginning with 0, i.e., "0.X.Y", are regarded as pre-release definitions and need not follow the rules above. Either the MINOR or PATCH version numbers may be updated, regardless of whether the changes are non-backwards-compatible, backwards-compatible, or editorial. See Section 6 for more details on using this notation during 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, which specify the recommended (and minimum required) update to the version identifier, the following rules MAY be applied when choosing a new version identifier:¶

1. An artifact author MAY update the version identifier with a more significant update than described by the rules above. For example, an artifact could be given a new MAJOR version number (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 number (i.e., X.Y+1.0) even if the changes were only editorial.¶
2. An artifact author MAY skip versions. That is, an artifact's version history could be 1.0.0, 1.1.0, and 1.3.0 where 1.2.0 is skipped.¶

Although YANG Semver always indicates when a non-backwards-compatible, or backwards-compatible change may have occurred to a YANG artifact, it does not guarantee that such a change has occurred, or that consumers of that YANG artifact will be impacted by the change. Hence, tooling, e.g., [I-D.ietf-netmod-yang-schema-comparison], also plays an important role for comparing YANG artifacts and calculating the likely impact from changes.¶

[I-D.ietf-netmod-yang-module-versioning] defines the "rev:non-backwards-compatible" extension statement to indicate where non-backwards-compatible changes have occurred in the module revision history. If a revision entry in a module's revision history includes the "rev:non-backwards-compatible" statement then that MUST be reflected in any YANG semantic version associated with that revision. 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 Label

  module example-versioned-module {
    yang-version 1.1;
    namespace "urn:example:versioned:module";
    prefix "exvermod";

    import ietf-yang-revisions { prefix "rev"; }
    import ietf-yang-semver { prefix "ys"; }

    description
      "to be completed";

    revision 2017-08-30 {
      description "Backport 'wibble' leaf";
      ys:version 1.2.2_non_compatible;
    }

    revision 2017-07-30 {
      description "Rename 'baz' to 'bar'";
      ys:version 1.2.1_non_compatible;
      rev:non-backwards-compatible;
    }

    revision 2017-04-20 {
      description "Add new functionality, leaf 'baz'";
      ys:version 1.2.0;
    }

    revision 2017-04-03 {
      description "Add new functionality, leaf 'foo'";
      ys:version 1.1.0;
    }

    revision 2017-02-07 {
      description "First release version.";
      ys:version 1.0.0;
    }

    // Note: YANG Semver rules do not apply to 0.X.Y labels.
    // The following pre-release revision statements would not
    // appear in any final published version of a module. They
    // are removed when the final version is published.
    // During the pre-release phase of development, only a
    // single one of these revision statements would appear

    // revision 2017-01-30 {
    //   description "NBC changes to initial revision";
    //   ys:version 0.2.0;
    //   rev:non-backwards-compatible; // optional
    //                         // (theoretically no
    //                         // 'previous released version')
    // }

    // revision 2017-01-26 {
    //   description "Initial module version";
    //   ys:version 0.1.0;
    // }

    //YANG module definition starts here
  }

{
  "ietf-yang-instance-data:instance-data-set": {
    "name": "example-yang-pkg",
    "content-schema": {
      "module": "ietf-yang-packages@2022-03-04"
    },
    "timestamp": "2022-12-06T17:00:38Z",
    "description":  ["Example of a Package  \
       using YANG Semver"],
    "content-data": {
      "ietf-yang-packages:packages": {
        "package": [
          {
            "name": "example-yang-pkg",
            "version": "1.3.1",
            ...
          }
        ]
      }
    }
  }
}

5.1. The recommended-min-version Extension

The ietf-yang-semver module defines a "recommended-min-version" extension -- a substatement to the "import" statement -- that takes a YANG semantic version as its argument and specifies that the minimum version of the associated module being imported SHOULD be greater than or equal to the specified value. The specific conditions for determining if a module's version is greater than or equal is defined in Section 5.2 below. Multiple recommended-min-version statements MAY be specified. If there are multiple recommended-min-version statements, they are treated as a logical OR. Removing recommended-min-version statements is considered a backwards compatible change. An example use is:¶

        import example-module {
            ys:recommended-min-version 3.0.0;
        }

5.2. Import by YANG Semantic Version Rules

A module to be imported is considered viable with recommended-min-version if it meets one of the following conditions:¶

1. Has the same MAJOR and MINOR version numbers and same or greater PATCH number.¶
2. Has the same MAJOR version number and greater MINOR number. In this case the PATCH number is ignored.¶
3. Has a greater MAJOR version number. In this case MINOR and PATCH numbers are ignored.¶

In all cases, the "_compatible" and "_non_compatible" version modifiers are ignored.¶

If the recommended-min-version is specified as 3.1.0, the following examples would be viable:¶

• 3.1.1 (by condition 1 above)¶
• 3.2.0 (by condition 2 above)¶
• 4.1.2 (by condition 3 above)¶
• 3.1.1_compatible (by condition 1 above, noting that modifiers are ignored)¶
• 3.1.2_non_compatible (by condition 1 above, noting that modifiers are ignored)¶

If an import by recommended-min-version cannot locate a module with a version that is viable according to the conditions above, the YANG compiler SHOULD emit a warning, and then continue to resolve the import based on established [RFC7950] rules.¶

6.1. Pre-release Version Precedence

As a module or submodule is developed, the scope of the work may change. That is, while a released module or submodule with version 1.0.0 is initially intended to become 2.0.0 in its next released version, the scope of work may change such that the final version is 1.1.0. During the development cycle, the pre-release versions could move from 2.0.0-some-pre-release-tag to 1.1.0-some-pre-release-tag. This downwards changing of version identifiers makes it difficult to evaluate semantic version rules between pre-release versions. However, taken independently, each pre-release version can be compared to the previously ratified version (e.g., 1.1.0-some-pre-release-tag and 2.0.0-some-pre-release-tag can each be compared to 1.0.0). Module and submodule developers SHOULD maintain only one revision statement in a pre-released module or submodule that reflects the latest revision. IETF authors MAY choose to include an appendix in the associated draft to track overall changes to the module or submodule.¶

6.2. YANG Semver in IETF Modules

All published IETF modules and submodules MUST use YANG semantic versions in their revisions.¶

Development of a new module or submodule within the IETF SHOULD begin with the 0 MAJOR number scheme as described above. When revising an existing IETF module or submodule, the version MUST use the target (i.e., intended) MAJOR and MINOR version components with a 0 PATCH version number. If the intended RFC release will be non-backwards-compatible with the current RFC release, the MINOR version number MUST be 0.¶

12.1. YANG Module Registrations

This document requests IANA to register URIs in the "IETF XML Registry" [RFC3688]. Following the format in RFC 3688, the following registrations are requested.¶

• URI: urn:ietf:params:xml:ns:yang:ietf-yang-semver¶
• Registrant Contact: The IESG.¶
• XML: N/A, the requested URI is an XML namespace.¶

• URI: urn:ietf:params:xml:ns:yang:ietf-yang-library-semver¶
• Registrant Contact: The IESG.¶
• XML: N/A, the requested URI is an XML namespace.¶

The following YANG modules are requested to be registered in the "IANA Module Names" [RFC6020]. Following the format in RFC 6020, the following registrations are requested:¶

The ietf-yang-semver module:¶

• Name: ietf-yang-semver¶
• XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-semver¶
• Prefix: ys¶
• Reference: [RFCXXXX]¶

The ietf-yang-library-semver module:¶

• Name: ietf-yang-library-semver¶
• XML Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library-semver¶
• Prefix: yl-semver¶
• Reference: [RFCXXXX]¶