Ontology Versioning Policy

Governs every owl:Ontology document under ontology/ — every spec/<layer>.ttl and vocab/<layer>-vocab.ttl, plus the directly-authored ontologies (Persistence, MORK’s Mork.ttl/Executable.ttl, SPC, and applied domain ontologies) that carry their own owl:versionIRI. Decided in ADR-A86; read that ADR first for the why. This document is the how: the checklist a human contributor or an agentic coding assistant applies before committing a change.

Adopts Semantic Versioning 2.0.0 (X.Y.Z — MAJOR.MINOR.PATCH) unmodified. If you have not read semver.md’s summary, read it now; this document only translates its three rules into ontology terms.

The versioning unit

One owl:versionIRI per owl:Ontology document. spec/<layer>.ttl and vocab/<layer>-vocab.ttl are two independently versioned documents — a change to one never bumps the other. A layer’s shapes/ and projection/ directories declare no owl:Ontology, so each directory is a versioning unit of its own: a .version file in the directory holds one semantic version (X.Y.Z) shared by every file in it. A change to any of those files bumps the directory’s .version, and never the spec or vocab version IRI, which move only when the ontology itself changes. The table below classifies a shapes change exactly as it classifies one to an ontology document.

What changes the number

Software semver defines API breakage in terms of function signatures. An ontology’s public API is what a consumer’s data is checked against: what a reasoner or a SHACL engine accepts or rejects, and what a term is documented to mean.

Two categories do not reduce to axiom-diffing:

• Silent semantic redefinition. The IRI and the axioms are unchanged, but the layer’s own “Design decisions” prose now means something different. This is a MAJOR change even when no SHACL shape moves. Classification here is a judgement call against the layer’s own README, made by whoever is authoring the change (human or agentic), and stated with its reasoning in the pull request — not inferred from a diff.
• Cross-layer import pinning. owl:imports in this repository pins an exact owl:versionIRI. Bumping any layer’s version obliges updating every importing layer’s owl:imports statement (and README turtle-spec source, where one mirrors it) in the same change, or the graph stops resolving.
• Import-only changes take the imported level. A document whose only change is an updated owl:imports takes the bump level of the change it imports, applied transitively, because its own consumers see that change through its import closure. Proposed in the ADR-A86 addendum, item 1, and applied since the applied-ontology-readiness unit’s AOR-2.

The import-pinning cascade checklist

Before bumping any layer’s version:

1. Enumerate every importer: grep -rl "owl:imports.*<old-versionIRI-substring>" ontology/ (substitute the exact base, e.g. neuro-semantic/lattice/foundation/) across the whole ontology/ tree, not just the layer’s own directory — an import can live in another layer’s spec/*.ttl, its mirrored README turtle-spec block, an unrelated example/test fixture, or (rarely) a hardcoded string in tools/ reference-implementation code that stamps generated output with an ontology IRI (see tools/surface/src/surface/namespaces.py’s SURFACE_ONTOLOGY constant for a real instance of this last case).
2. Update every one of those references to the new owl:versionIRI in the same change. A bare, unversioned owl:imports target (MORK’s Mork.ttl is imported this way by several of its own example/test fixtures) is a deliberate, separate choice some importers make to always resolve against “whatever Mork currently is” rather than pin a release; leave those alone unless the specific file’s own convention is to pin exactly, matching its siblings.
3. Re-run the enumeration in step 1 after editing — it should return nothing for the old IRI.

Keeping exact-IRI pinning (rather than adopting a dependency-range import mechanism) is this repository’s current, deliberate choice — see ADR-A86’s “Open questions” if the cascade cost ever becomes a real source of friction.

Where the number physically lives

The seven literate-spec layers (Foundation, Vocabulary, Quantification, Party, Eligibility, Instrument, Behaviour) plus Surface: for the layers whose README mirrors the ontology header in its own turtle-spec fenced block (check with grep -l "owl:versionIRI" ontology/<layer>/README.md — today that is Eligibility, Instrument, Behaviour, and Surface), edit the version in both the README and the generated spec//vocab/ file, since tools/literate_extract.py is meant to keep them identical.

A known, pre-existing gap this policy does not paper over: tools/literate_extract.py --check does not currently pass for any of the seven core layers — Foundation’s, Vocabulary’s, and Party’s committed spec/*.ttl predate the extraction tool’s own output conventions entirely (hand-authored/differently-generated Turtle, not a turtle-spec concatenation), and Quantification, Eligibility, Instrument, Behaviour, and Surface’s README turtle-shapes blocks do not agree with the --shapes arguments the tool needs to run without error. This was discovered, not introduced, while implementing ADR-A86’s baseline reset (2026-09-25): the reset edited the version/import lines directly, in both the README and the generated file, by hand, rather than by running the extraction tool, precisely because running it would have overwritten unrelated, already-drifted content with a full, differently-formatted regeneration — well outside this unit’s scope. Treat tools/literate_extract.py --check passing repository-wide as a separate, future remediation unit, not a promise this policy makes.

Persistence, MORK (Mork.ttl, Executable.ttl), SPC, and applied domain ontologies (ontology/applied/*) author their owl:versionIRI directly in the committed .ttl file — there is no README mirror to keep in sync for these.

The one-time baseline reset (2026-09-25)

Every in-scope document was reset to 0.2.0 in the same change that introduced this policy, per ADR-A86. This is an administrative normalisation, not a claim that any layer took seven, or three, or one MINOR release to get there — see the ADR’s “Consequences.” The full before/after table:

Every owl:imports statement anywhere in ontology/ that named one of the “Before” IRIs above was updated to the corresponding “After” IRI in the same change (the cascade checklist above), including the additional example fixture ontology/mork/examples/Governance/GovernanceAndVersioning.ttl and the illustrative MCN snippet in docs/architecture/mork-compact-notation.md. MORK’s own bare (unversioned) owl:imports <http://www.nebularis.org/ontologies/Mork> references, used by several of its example/test fixtures, were deliberately left unversioned — see the checklist’s step 2.

Answered, per ADR-A98 decision 6: applied/insurance/contract.ttl’s namespace family (neuro-semantic/insurance/..., outside the lattice/ tree every other in-scope document uses) was deliberate applied-layer independence, not an oversight. Every insurance module uses the same neuro-semantic/insurance/<module> family; only cross-domain applied modules use the neuro-semantic/lattice/applied/<module> family. The legacy contract document itself was dropped by applied-insurance-reference (epic decision D1, AIR-1.1).

Applying this to a new change

1. Classify the change against the table above. If it is a silent semantic redefinition, say so explicitly in the PR, with the reasoning — do not rely on the table alone to justify a PATCH or MINOR label for a change that actually redefines what a term means.
2. Bump the correct unit(s) only — spec, vocab, and each shapes/ or projection/ directory’s .version are independent. Bumping one because another changed is itself a documentation error.
3. Run the import-pinning cascade checklist for every bump, PATCH included (see “The one subtlety,” below).
4. Where a README mirrors the ontology header, edit both, keeping them identical for that block.
5. Regenerate the catalogs with mise run build:ontology-catalog, since a new version IRI needs a catalog entry before any importer resolves it (ADR-A88).
6. Add release rows with mise run build:ontology-releases. It lists the tags the new versions need.
7. After committing, create and push those tags (next section). An agent never creates them. It ends its handoff with a notice listing them.

Releasing a version

Version IRIs do not dereference yet (ADR-A88 defers serving them). Until they do, a version is released by a git tag on the commit where it is in force, and fetched from GitHub at that tag.

• Tag name: <name>-vX.Y.Z. The name is the version IRI’s path without its version, with neuro-semantic/lattice/, neuro-semantic/ or ontologies/ dropped, segments joined by -, in lower case: foundation-v0.3.0, foundation-vocab-v0.3.0, mork-v0.4.0, applied-capacity-execution-v0.6.0.
• Register: ontology-releases.md, published on the GitHub Pages site, has one row per released version: its name, version, tag, version IRI, and raw links at the tag, of the form https://raw.githubusercontent.com/nebularis/lattice/refs/tags/<tag>/<path>. Rows are written by tools/ontology_releases.py and never edited.
• Artefact directories are released the same way, named after the layer path and the directory (foundation-shapes-v0.1.0, applied-insurance-shapes-v0.1.0, behaviour-projection-v0.1.0), with a row linking every file in the directory and no version IRI.
• Who tags: a person, after committing the change that adds the rows. A tag names a whole commit, so the document, its artefacts, and the import catalog at that tag are all frozen with it. One commit may carry several tags.
• Why this is safe: a version IRI identifies one content only while no document changes without a bump. The checks below enforce that, so a tag never has to move.

The first releases, on 2026-09-26, cover the version current at that date for each document, and each artefact directory’s first version, 0.1.0. Earlier versions are not released.

The one subtlety: PATCH still bumps the version

A PATCH bump changes the version number, even though the change itself was “backward compatible with no visible axiom change” — the version number is what tells a consumer that something changed at all, distinct from the content-level classification of what kind of change it was. Do not confuse “this was a small change” with “this needs no version bump.” The narrow tooling check described next exists specifically to catch this confusion.

Enforcement

No tool in this repository classifies a change as MAJOR/MINOR/PATCH automatically — that is a research problem, not a checklist, and this policy does not attempt it. What is enforced is narrower and purely mechanical: a change to an in-scope .ttl file’s content must be accompanied by a change to that file’s own owl:versionIRI literal, and a change to a file in a layer’s shapes/ or projection/ directory by a change to that directory’s .version. A document under a spec/ or vocab/ directory must also carry an owl:versionIRI at all, and every artefact directory a valid .version. Examples and test fixtures are exempt. Every current version must have a release row, and an existing release tag must name a commit where its document has that version. Missing tags are listed, not failed, since they are created after the commit. Both checks read only files git tracks or would track, so ignored build output is out of scope.

A generated document carries a content-addressed version IRI instead of a semantic version: its ontology IRI followed by the first 16 hex digits of its canonical hash, taken without the version IRI (ADR-A86 addendum, item 5). The Surface compiler stamps it when it writes a module. See tools/ontology_version_check.py, tools/ontology_releases.py and mise run check:ontology-versioning. The platform workflow runs the same checks against origin/main.