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.