Clause 18 — Versioning and compatibility — Building Understanding Standard

18 Versioning and compatibility§

AGREED

18.1 Version identifiers§

This document and its schemas are versioned MAJOR.MINOR. Packages declare the version they conform to in busVersion. Entities separately carry a revision (6.6), which is unrelated.

18.2 Compatibility rules§

Change	Impact	Importer obligation
Adding an OPTIONAL property	MINOR	Preserve it. Ignoring is permitted; discarding is not.
Adding an enumeration member	MINOR	Preserve the value. MUST NOT coerce to a default.
Adding a class, predicate, channel, or symbol role	MINOR	Preserve entities using it. Symbol roles degrade per 13.4.2.
Promoting an extension or property definition to the core	MINOR	Accept both forms. SHOULD emit the core form on re-export.
Deprecating a construct	MINOR	Continue to accept it until a MAJOR change.
Removing or narrowing a construct	MAJOR	Not permitted within a MAJOR version.
Changing the meaning of a construct	MAJOR	Not permitted within a MAJOR version.

An importer MUST refuse a package whose busVersion has a higher MAJOR number and MUST report the version it supports. It MUST accept a package with the same MAJOR and a higher MINOR, preserving what it does not understand and reporting which constructs it ignored.

NOTE Acceptance of a newer MINOR constrains schema validation: a package written under 0.3 may carry enumeration members and properties that the 0.2 schemas reject, and those rejections are unknown constructs to be preserved and reported, never grounds for refusal. Structural checks — digests, referential closure, identifier uniqueness, the completeness declaration — remain strict at every version. The reference implementation initially got this wrong, and test IM-3 exists to catch exactly that mistake.

18.3 Backward interpretability§

The obligation is stronger than backward compatibility of software. It is backward interpretability of packages: a package written correctly under v0.2 MUST remain interpretable under every subsequent version with the same MAJOR number, without the original exporter and without a migration tool only one party can run.

Where a MAJOR change is unavoidable, the governance body MUST publish an open-source, deterministic migration from the previous MAJOR version before the new one takes effect.

NOTE v0.2 is not backward compatible with v0.1 — the property model, the space classes, and the party class all changed. This is permitted only because no v0.1 package exists outside this project. It will not be permitted again.

18.3.1 Two v0.3 requirements that read as narrowing, and why they are not§

Two additions in this version constrain fields that were previously unconstrained, and 18.2 classifies narrowing a construct as a MAJOR change. Both are scoped so that no v0.2 package becomes invalid:

Declared port names — a subjectPort or objectPort MUST name a port its endpoint declares. A v0.2 package carries no ports array, so it cannot fail the check — the requirement applies where an asset declares ports, which no package written before this version does. A receiver reading a v0.2 package MUST continue to treat the string as the opaque label it was.
The figure profile — a figure MUST conform to bus-vector-1. A v0.2 figure was written against a format that was named and never defined, so there was nothing for it to conform to and nothing it can be said to have violated. A receiver meeting a v0.2 figure that would fail the profile MUST refuse to render it under 19.3, and MUST NOT refuse the package.

Stated plainly: this version narrows what a v0.3 exporter may write. It does not narrow what a receiver MUST accept, which is the thing 18.3 actually protects. A requirement that made existing packages invalid would be a MAJOR change however it were graded, and neither of these does.

NOTE This subsection exists because the first draft of v0.3 stated both requirements without scoping them, which put them in direct conflict with 18.2 and 18.3 — and the document said nothing about the conflict. A specification that contradicts itself and does not notice is worse than one that admits a hard case.