Summary

  • recommended-min-version is a numeric import hint. Revision 28 of the YANG Semantic Versioning draft says comparison ignores _compatible, _non_compatible, prerelease and build metadata, and it intentionally permits a higher major version to qualify.
  • The resolver therefore establishes eligibility, not backward compatibility. A compiler may also warn when it cannot find an eligible version and then continue under RFC 7950 rules, so a completed schema does not prove that the recommendation was met.
  • Before deployment, operators need a resolution receipt tying the request to every candidate, the exact selected bytes, the complete module/package set, features, deviations, warning state, client tests, decision owner and rollback target. This receipt is Daniel Kade’s proposal, not an IETF requirement.

The smallest word in the import line carries the largest assumption

“Minimum” is an inviting word. In procurement it sounds like a threshold below which a product is unacceptable. In security it sounds like an enforced baseline. In ordinary software dependency systems it often suggests that anything greater will preserve what the caller needs, subject to familiar major-version conventions. Put the word beside a semantic version and many readers will supply a promise before reading the algorithm.

The current NETMOD draft is more exact and less comforting. draft-ietf-netmod-yang-semver-28, published on 21 July 2026 and now in the RFC Editor Queue, defines recommended-min-version as an extension under a YANG import statement. Its argument contains only three integers: major, minor and patch. When a resolver compares candidates, it ignores the two YANG-specific compatibility modifiers and all prerelease or build metadata.

The qualifying test is intentionally broad. An exact numeric triplet passes. A larger patch passes when major and minor are the same. A larger minor passes when the major is the same. Any larger major passes, whatever its minor and patch values. For a recommendation of 3.1.0, the draft itself lists 3.1.2 _non_compatible and 4.1.2 among the versions that satisfy the test. The first announces a non-backwards-compatible branch change; the second carries a larger major number, which YANG Semver uses for non-backwards-compatible change. Both remain numerically eligible.

That is not a contradiction in the specification. Section 5.2 explains why the admission is deliberate: the import rule is kept simple, while responsibility for choosing a coherent set of module versions is expected to sit outside the extension, for example in a YANG package. The problem is institutional, not syntactic. Tooling can truthfully report that the recommendation was satisfied while a change board, controller team or automation pipeline hears a different claim: that the resulting schema is compatible with what it already runs.

A version signal is useful precisely because it is not a verdict

YANG Semver adds valuable information. Major changes identify non-backwards-compatible development across the main line. Minor changes generally indicate backwards-compatible additions within a major line. Patch changes without a modifier are editorial. The _compatible and _non_compatible suffixes make limited maintenance branches legible, and the latter becomes sticky within its branch so a later editorial change does not erase the warning.

Those rules can spare a human or tool from opening every file merely to understand the author’s declared change class. The draft also requires the combination of artifact name and semantic version to identify one revision; different content must not reuse the same pair. This is meaningful lifecycle discipline.

But the label remains one input. It is assigned under a versioning policy, not calculated as a proof of every consumer’s behaviour. A backwards-compatible schema change may still expose a bug in generated code, collide with a local naming assumption or alter an application that treated an open enumeration as closed. A technically editorial change can produce different bytes that matter to an overly rigid supply-chain control. A correct _non_compatible label warns loudly, yet the minimum-version comparison is designed not to use that warning.

Even file identity is not the entire object of risk. The draft notes that a submodule’s meaning can change drastically despite no change in its own content or revision, because groupings or typedefs supplied by another submodule may have changed. A single file hash proves which file was received. It cannot, on its own, prove which effective schema the including module produced.

This is why the right reading is modest: a semantic version is structured evidence of the artifact author’s declared lineage. It is not a cryptographic digest, a package lock, a conformance result or a deployment authorization.

Resolution has three different success states

An operations pipeline should distinguish at least three outcomes that dashboards often compress into “resolved”.

The first is recommendation satisfaction. A candidate met the numeric rules in the semver draft. This is the narrowest success and says nothing about the consuming client.

The second is fallback completion. The compiler found no candidate it considered viable, emitted a warning and continued using established RFC 7950 import rules. RFC 7950 makes an explicit revision-date binding exact; without that substatement, the revision is otherwise undefined at the language level. A compiler that completes after warning may have produced a usable schema, but it did not thereby turn fallback into satisfaction of the missing recommendation.

The third is deployment acceptance. The exact resolved schema has been examined and exercised against the clients, controllers, configurations and operational procedures that will depend on it. That judgment belongs to the deployment environment.

These states can diverge. A recommendation can be satisfied by a version that the current controller cannot parse. Fallback can generate a schema that passes a basic syntax check but includes an older typedef than the module author expected. A package can resolve cleanly while an enabled feature changes the nodes visible to a client. If all three appear as a green build, the organization loses the ability to tell whether it honored an import intention, merely completed compilation or proved an operational transition.

The compatibility object is the resolved schema, not one number

RFC 8525’s YANG Library supplies the wider frame. A datastore schema is a union of module sets. A module set includes implemented modules, import-only modules and their submodules; implemented entries also advertise supported features and deviation modules. A content-id changes when the YANG Library content changes. The effective management surface therefore depends on more than the winning revision of one import.

The YANG packages draft makes this composition explicit. A package is a versioned hierarchical structure for modules that collectively define a schema. It can include other packages, implemented modules, import-only modules and enabled features. It can exclude inherited modules or features. Its resolution rules can automatically choose a later module version when packages conflict, which is useful for hot fixes. Selecting an older version requires an explicit refining package rather than passive preference.

Packages improve governance because they give a coherent set a name and a resolvable structure. They do not remove the need to inspect the result. The draft permits incomplete packages for uses such as hot fixes and logical groupings; dependencies can remain to be resolved in context. When packages are bound to a datastore schema, the resolved package schema and additional features must exactly match the YANG Library module set and be referentially complete. That is a strong check, but it is a check on schema composition—not proof that a specific client will behave safely.

Deviations make the distinction concrete. A module revision might be familiar while a server’s deviation set removes, constrains or changes support for nodes a controller expects. Feature selection can similarly alter which branches exist. A package version, module version or content-id is useful only if the change record names the context it identifies.

A schema comparison measures change, not consequence

The companion schema-comparison work provides a vocabulary and machine-readable output for differences between YANG schemas. That can answer questions a version number cannot: which statements changed, and how the change is classified under the comparison model. It belongs in a serious upgrade review.

It still stops before the last mile. A diff does not run a client’s generated bindings. It does not know that an automation script assumes a leaf is always present, that an inventory collector rejects an unfamiliar identity, or that a controller maps an error into a destructive retry. It cannot observe whether representative configurations validate, whether state subscriptions remain stable or whether a rollback restores both model and application state.

Compatibility is relational. It exists between a resolved schema and a consumer under a workload and a set of assumptions. The same schema can be acceptable to a flexible browser and unsafe for a controller compiled against closed types. The evidence must therefore name both sides of the relationship. “Schema 4.1.2 passed comparison” is incomplete unless the record says against which prior schema, under which comparison policy, and for which consumers the result was tested.

Build a resolution receipt before granting deployment authority

A resolution receipt should be produced whenever recommended-min-version influences an import that reaches build, test or production. The receipt is not another global registry and need not slow the resolver. It is a durable account of what the resolver did and what the deployment owner subsequently proved.

Start with the importing module: exact name, revision, full semantic version where present, content hash and source location. Record the requested numeric triplet exactly as written. Then capture the complete candidate inventory visible to the tool, including full version strings and locations. This matters because the decision algorithm discards information. The receipt should state that modifiers and metadata were ignored and retain their original values, allowing a reviewer to see that 3.1.2 _non_compatible beat or accompanied other choices.

For the selected revision, retain exact bytes or a stable content digest, revision date, semantic version and retrieval provenance. Expand the record to the whole resolved set: included and import-only modules, submodules, package inclusions and exclusions, enabled features, deviations, mount context and the YANG Library content-id or an offline equivalent. Mark whether each package was complete before resolution and which conflict rule selected each winner.

Tool behaviour belongs in the same evidence chain. Name the compiler or resolver and version. Preserve warnings. State whether the semantic recommendation was satisfied or whether RFC 7950 fallback continued after failure. Store the schema-comparison baseline, policy and result without promoting that result into a client guarantee.

Finally, record the consumer proof: which controller, agent, generator or validation service was tested; which representative configurations, RPCs, notifications and state paths were exercised; what failed; who accepted the remaining uncertainty; and which prior resolved set is the rollback target. Deployment scope and expiry matter. Approval for one lab controller does not silently authorize every client sharing the repository.

This receipt converts a convenient word—minimum—into an auditable chain. It does not demand that the semver extension solve package management, client testing and organizational authority. It makes visible that those responsibilities exist.

Sources