Skip to content

Versioning vs. ODK / OBO Foundry

How ADIRO's versioning scheme compares to the de-facto standard for open scientific ontologies — the OBO Foundry conventions, tooled by the Ontology Development Kit (ODK). ADIRO is not an OBO ontology, but OBO/ODK is the most mature reference point for ontology versioning, so we track it deliberately — matching it where it is sound and diverging where our use case (machine-readable AEC drawings feeding a version-pinned ML pipeline) demands more.

Dimension OBO Foundry / ODK ADIRO Assessment
Version identifier Dated releases (YYYY-MM-DD) preferred; SemVer only "acceptable" (Principle 4) SemVer, per module (x.y.z) Both satisfy Principle 4 (unique, resolvable, versioned IRI). We chose SemVer deliberately — see next row.
Compatibility in the version Not encoded — a date conveys recency, not whether a release breaks consumers Encoded — MAJOR/MINOR/PATCH classified by the compatibility-diff spec and checked in CI ADIRO does better for our purpose. A pinned consumer (a downstream annotation pipeline) reads a MAJOR bump as "your pinned build may break"; OBO consumers must diff releases themselves.
Modularity One ontology → one version and cadence (imports handled as modules) Four independently-versioned modules Trade-off. Per-module suits a layered suite whose parts evolve at different rates; OBO's single number is simpler to track.
Resolvable IRIs OBO PURL (purl.obolibrary.org, .htaccess redirect) + dated version IRI w3id.org/adiro content-negotiating front door + versioned IRI Par — the same pattern (community redirect layer, resolvable versioned IRIs).
Deprecation Never delete; owl:deprecated, replace axioms, replaced_by/consider, obsolete label prefix Never delete; owl:deprecated + replacement mapping (counts as MAJOR) Par — we follow the OBO obsoletion model. (We do not yet use the obsolete label prefix / IAO:0100001 "term replaced by" annotations — a low-cost alignment we could adopt.)
Reasoning + structural QC Bundles ROBOT + reasoners (ELK / HermiT / Konclude); runs reasoning + robot report in CI HermiT (full OWL 2 DL) as a blocking gate + robot report (advisory) Par / slightly stricter — we block on inconsistency / unsatisfiability across the merged suite.
Release products Multiple variants (-base, -simple, -full, extracted imports) via a Makefile Single .ttl per module (unversioned latest + versioned snapshot) ODK does more. We do not yet need variant products; ODK's are valuable at OBO scale.
Import handling SLME module extraction, version-pinned in config Local stub + alignment where possible, else SLME extract + pin + reasoner gate (external-import rule, RES-68) Deliberate divergence — we are lighter. ODK treats an SLME extract as the normal way to reuse an external term; we prefer not importing at all where the external IRI is only an alignment target and our own axioms carry the logic, because every PR is reasoned over the merged suite behind a blocking DL gate. The cost is a term that is a name without a definition — something OBO conventions discourage. Par on the extraction path itself, for the cases where we do extract.
Changelogs / release notes Varies by project; GitHub Releases Keep-a-Changelog per module + top-level rollup + auto-populated Release notes ADIRO more structured.
Tooling maturity Mature, batteries-included (Docker image, Makefile, dashboards, large community) Bespoke scripts, younger, small surface ODK does better — battle-tested and widely adopted.

Net: for the thing that matters most to us — telling a machine consumer whether a new release is safe to adopt — ADIRO is stronger than the OBO default, because we encode compatibility in SemVer and enforce it with the compatibility-diff classifier plus the reasoner gate, rather than leaving consumers to diff dated releases. Where ODK is stronger — a mature, general-purpose release framework with variant products and a large community — we deliberately kept a smaller bespoke setup sized to ADIRO today, while staying close enough to OBO conventions (resolvable versioned IRIs, never-delete deprecation, reasoning + ROBOT QC) that adopting ODK tooling later would be evolutionary, not a rewrite.