skip to content

Why must every published change to a YANG module add a new revision statement, while its name and namespace stay fixed?

level: middleimportance: should knowfreq 14%

answer

  1. the date is the version
  2. newest revision goes first
  3. importers pin by revision-date
  4. incompatible means a new identifier

basics

~20 s

A YANG module's revision date is its version: importers pin it and servers report it, so each published change needs a new, later date. Name and namespace are permanent identity; an incompatible change needs a new identifier.

solid answer

~50 s

In YANG, a `revision` statement carries a `YYYY-MM-DD` date, and the sequence lists the newest first, so the first revision names the version a file holds. RFC 7950 §11 makes this a MUST: for any published change a new `revision` goes in front, and the module name and `namespace` MUST NOT change, because other modules import by name and every XML element is qualified by the namespace. The update rules then limit what a new revision may do — add enums without renumbering, widen ranges, add non-mandatory nodes, deprecate rather than delete — and anything that changes the meaning of a definition MUST become a new definition with a new identifier. Obsolete definitions are never removed. RFC 9907 adds that every published revision has a `reference` to its document and that a changed module gets a later date.

go deeper

for a junior

Recall that the newest revision date is a module's version and that the module name and namespace never change once published.

for a middle

Walk through RFC 7950 §11: what a new revision may add or relax, and why a semantic change needs a new identifier rather than an edit.

for a senior

Use the rules to review a vendor's model update: spot renumbered enums, new mandatory nodes, deleted objects and reused revision dates before they break automation.

for a principal

Set policy for an organization's private modules: revision discipline, a deprecation window, and when a new module beats stretching an old one.

## The revision date is the version A YANG module has no version number. Its version is the date in the newest `revision` statement (RFC 7950 §7.1.9): - Each `revision` takes a date in the form `YYYY-MM-DD` and may carry `description` and `reference`. - For every published editorial change a new one goes **in front**, so the list runs in reverse chronological order and the **first** revision is the version this file holds. - The file-naming convention (§5.2) uses that date: `[email protected]`. Everything that refers to a specific version uses this date: an `import` or `include` with `revision-date`, a server's report of which revision it implements, and the YANG library that lists modules by name and revision. If two different texts carried the same newest date, all of those references would become ambiguous. The history is **descriptive only**. A file keeps the dates and descriptions of earlier revisions, not their definitions; you cannot reconstruct the 2013 text of a module from its 2025 file. ## What §11 fixes in place RFC 7950 §11 opens with the principle: changes to published modules are not allowed if they could cause interoperability problems between a client using the original and a server using the update. From that come the fixed points: 1. **A new `revision` statement MUST be added** in front for any published change (or one added, if none existed), and `organization` and `contact` updated as needed. 2. **The module name MUST NOT change** — other modules reference definitions by importing the module by name. 3. **The `namespace` MUST NOT change** — every XML element is qualified by it. 4. **Obsolete definitions MUST NOT be removed** — other modules may still reference their identifiers. They are marked with `status deprecated` or `status obsolete` instead. ## What a new revision may and may not do §11 then lists the changes a revision may make under the same name. A selection: | Allowed in a new revision | Not allowed (needs a new identifier) | |---|---| | Add an enum, keeping existing values | Renumber or reorder existing enums without explicit values | | Widen a `range`, `length` or `pattern` | Narrow a value space, or change `int8` to `int16` | | Add non-mandatory nodes, typedefs, groupings, identities | Add a mandatory node to an existing node | | Remove or relax `must`, `when`, `mandatory true` | Change what an existing leaf means | | Change `status` current → deprecated → obsolete | Delete a published definition | | Split the module into submodules, definitions unchanged | Rename the module or change its namespace | Anything not on the allowed list that changes semantics "MUST be achieved by a new definition with a new identifier". Data definition substatements also must not be reordered. RFC 9907, the authoring BCP, adds the lifecycle advice: do not jump from `current` straight to `obsolete`, and keep a deprecated object for at least a year first. ## The publishing rules on top (RFC 9907) RFC 9907 (obsoletes RFC 8407) tightens the conventions for published modules: - A `revision` statement MUST be present for each published version, and it MUST have a `reference` naming the document that contains the module. - Published revision statements are never removed or reused; if the contents change, the new date MUST be later than the previous one. - During drafts, only the latest unpublished revision needs recording. - When submodules are used, the main module's revision date must be equal to or later than that of any submodule it includes. `ietf-yang-types` shows the result: its RFC 9911 text lists `2025-12-22` (RFC 9911), `2013-07-15` (RFC 6991) and `2010-09-24` (RFC 6021), each with a reference — one module, one namespace, three versions. ## Why this discipline matters to operators - **Pinning works.** An importer that pins `revision-date 2013-07-15` keeps exactly those typedefs, whatever is published later. - **Unpinned importers can usually float.** Because a new revision may only add or relax, a module that floats to the newest revision is meant to keep compiling and old instance data to stay valid — though compatible is not unchanged: a grouping that gains nodes changes the importer's tree. - **Breakage is visible.** A real semantic change shows up as a new node or a new module, not a silent reinterpretation of an old one. The common mistake is the opposite reflex from software versioning: "bump the namespace to v2". In YANG that creates a different module that every importer and every stored instance would have to follow.

  • A module's enumeration lists `up` and `down` without explicit values; a new revision inserts `testing` between them. Is that allowed?
    Not as written. RFC 7950 §11 allows new enums only if old values do not change, and inserting before an existing enum renumbers it unless values are assigned explicitly. Appending `testing` at the end, or assigning explicit values that keep `up` and `down` at their old values, keeps the change legal.
  • Your vendor shipped two different module files with the same newest revision date; why is that a defect?
    The revision date is the only version identifier, so imports with revision-date, server conformance reports and the YANG library can no longer tell the texts apart. RFC 9907 requires a later date whenever contents change, so one of the files is mislabelled.

saying these in an interview costs you the question

  • Each new revision of a YANG module should get a new namespace URI.
  • The last revision statement in the file is the current version.
  • Obsolete definitions should be deleted from the next revision to keep the module clean.
  • A module file keeps the full definitions of every earlier revision it lists.
  • Changing a leaf from int8 to int16 is fine because it only widens the range.