Summary

  • draft-ietf-netmod-yang-schema-comparison-09 compares both parsed statements and the effective compiled data tree, then labels reported changes as editorial, backwards-compatible or non-backwards-compatible.
  • Those labels can support revision review, semantic-version selection and data-conversion planning. They do not prove identical compilation inputs, lossless migration, implementation interoperability, stable NACM behavior, safe rollout order or operational convergence.

A schema diff is attractive because it converts a large body of YANG into a short list of changes. The danger begins when the short list is promoted into a verdict it was never designed to deliver. “No incompatible change found” can become “safe to deploy” in a change ticket, then “upgrade succeeded” on a dashboard, although every step after comparison remains unobserved.

Revision 09, posted on 3 July 2026, gives this problem a serious technical foundation. The IETF Datatracker lists it as an active NETMOD Working Group Internet-Draft, not an RFC. Its current validation summary reports zero errors and zero warnings. Those facts establish the state of a standards document and its tooling surface; they say nothing about whether a vendor implements the algorithm, whether two implementations agree, or whether a live network survived a revision.

One schema has two relevant forms

The draft distinguishes the parsed schema from the compiled schema. The parsed form is close to the loaded statement tree. It retains statements before every reference and transformation has been resolved. The compiled form expands the effective model: imports and submodules are brought into context; uses and typedef references are resolved; augment, deviation and refine take effect; enabled if-feature expressions determine which branches exist.

That difference is operationally important. A one-line typedef change can alter many effective leaves. An augment authored in another module can add nodes below the module being reviewed. A deviation can remove or replace constraints without changing the target module’s source. Comparing source text alone would miss the resulting data tree; comparing only the tree could lose statement-level changes that matter to authors and importers.

Revision 09 therefore compares both forms. It emits compiled data-node changes first, then compares other parsed statements while avoiding duplicate data-node reports. The compiled identity includes the old and new module name and revision, included submodules, enabled features and recursively imported modules. This identity envelope is not administrative decoration. It defines the experiment.

An empty diff is evidence only for those exact inputs. If a device enables a different feature, loads a newer import, applies a vendor deviation or compiles another submodule revision, the original result cannot be carried over by name alone. The first receipt in any upgrade decision should therefore hash the source set and preserve the complete compilation identity.

Three labels answer a schema question

Every change is classified as editorial (ED), backwards-compatible (BC) or non-backwards-compatible (NBC). Editorial changes must leave the valid data-value space and importing modules unaffected. BC changes may expand what is valid, but must not invalidate importers. Everything else is NBC: the valid space contracts or an importing module may break.

The rules catch changes that human review can underestimate. Moving from uint32 to uint64 looks like widening a range. Under RFC 7951 JSON encoding, however, the representation changes from a number to a string. A client that treats the value as numeric can fail even though the mathematical set grew. Revision 09 can therefore classify the change as NBC.

Other statements deliberately begin with conservative defaults. Changes to pattern, when and must default to NBC. Changes to description, reference and presence default to editorial, while an extension instance defaults to BC. Authors can override a default by recording a sticky ed-change-at, bc-change-at or nbc-change-at semantic-version marker.

The override mechanism makes judgment visible and reviewable. It does not make judgment empirical. A reviewer should record which classes came directly from fixed rules, which came from a default, and which were explicitly overridden—along with the rationale and approver. A semantic-version label is then an accountable release statement, not an oracle.

Compatibility is not unchanged behaviour

BC is narrower than “nothing important changed”. Adding an optional leaf expands the schema-valid space and can be correctly classified BC. Yet a server may populate that leaf, a client may serialize or log it, a policy engine may inspect it, and a user interface may react to it. A changed default can alter effective behavior even when stored configuration is untouched. A when or must change can affect validation paths. Deviations and features can change the effective surface exposed by a particular device.

The comparison result describes schema compatibility under its rules. It does not execute RPCs, validate every existing configuration, compare default-expanded datastores or measure client behavior. RFC 8525 can identify the module set, enabled features and deviations a server advertises, but that YANG Library identity is not proof that the server executes them correctly.

The access-control boundary is separate again. RFC 8341 NACM determines what a principal may read or change. A schema diff can be empty while group membership, rules or default-deny behavior changes. Conversely, a schema change can be NBC but unreachable to a given role. A production claim must test the effective NACM matrix rather than infer authorization stability from the model.

Conversion needs a loss ledger

The draft notes that comparison output can help a tool transform old instance data for a newer revision. “Can inform” is the correct strength. A converter still makes choices: remove an obsolete node, map one enumeration to another, insert a default, normalize a representation, split a value, or reject data it cannot preserve.

RFC 9195 provides a useful pattern for identifying instance-data content and provenance. A defensible conversion receipt should bind the old instance hash and schema identity to the converter version and ruleset, then record every dropped, defaulted, normalized, synthesized and rejected node. It should hash the output, validate it against the target compiled schema, and state which round-trip or semantic invariants were tested.

Passing target-schema validation proves syntactic and constraint conformance for that output. It does not prove that meaning was conserved. If two old states map to the same new state, or a default hides an omitted decision, the migration may be valid but lossy. The owner of the data—not the diff tool—must decide whether that loss is acceptable.

The remaining gates are executable

After the diff and conversion come implementation tests. Compare at least two independent parsers or servers where interoperability matters. Replay representative configurations and RPCs. Check error tags, default handling, canonical encodings and feature negotiation. Exercise every affected NACM role. Capture the exact binaries, module set, flags and test vectors so a green result can be reproduced.

Then test deployment order. A rolling upgrade creates mixed-version intervals: old clients against new servers, new clients against old servers, and peers that disagree about feature or deviation sets. The comparison does not choose which component moves first, prove that telemetry stays continuous, or demonstrate that rollback will accept data written by the new version.

Finally observe runtime state. RFC 8342 separates running, intended and operational datastores because configuration, applied intent and observed state are not identical. The diff cannot show that intended state converged, that operational nodes stabilized, that alarms remained quiet, or that external users saw the intended result. Those are measurements from the deployed system.

This is the useful boundary of revision 09: it can turn schema review into a reproducible, attributable receipt. The receipt becomes more valuable, not less, when it is prevented from impersonating the evidence that must follow.

Sources

Primary sources: YANG Schema Comparison revision 09; IETF Datatracker record; YANG 1.1, RFC 7950; YANG Library, RFC 8525; Network Management Datastore Architecture, RFC 8342; NACM, RFC 8341; YANG Instance Data File Format, RFC 9195; YANG Semantic Versioning revision 28; YANG Module Versioning revision 16. Revision chronology: Datatracker history.