If you must rename `:Customer` to `:Client`, what's the SAFEST migration step?

Keep :Customer with owl:deprecated true and owl:equivalentClass :Client for at least one release, alongside changelog notes

Rename and publish a new versionIRI

You released v2.0 of your ontology with three breaking renames. Six months later three downstream teams are still on v1.0 because the migration was opaque. What should you have shipped *with* v2.0?

A migration SHACL shape that detects v1.0 IRIs in a consumer's graph + a changelog mapping every old IRI to its replacement + bridge axioms for one release

Nothing — it's the consumers' problem

A migration SHACL shape that detects v1.0 IRIs in a consumer's graph + a changelog mapping every old IRI to its replacement + bridge axioms for one release

Versioning, Deprecation & Migration

owl:versionIRI, owl:deprecated, SHACL migration shapes — keep downstream consumers alive across releases.

0/4 done

Overview

Versioning, Deprecation & Migration

owl:versionIRI, owl:deprecated, SHACL migration shapes — keep downstream consumers alive across releases.

Why it matters

An ontology with no versioning policy will break every downstream consumer the first time a class is renamed. owl:versionIRI + a deprecation policy is the minimum viable practice.

Going deeper

The minimum viable versioning policy, three habits:

Always set owl:versionIRI — a separate, monotonically-changing IRI from the ontology IRI itself, so consumers can pin to a specific release.
Deprecate, don't delete — mark removed terms with owl:deprecated true and rdfs:isDefinedBy <prev-version-IRI>. Provide a bridge axiom (owl:equivalentClass or owl:equivalentProperty) for at least one full release cycle.
Publish a changelog with semantic-version semantics — MAJOR for any breaking change (deletion, semantic narrowing); MINOR for additions; PATCH for labels/comments only.

A SHACL migration shape is the 'codemod' of ontology versioning: ship a shape that detects the old terms in a consumer's data and reports them, so consumers can run the shape and find every place they still reference deprecated IRIs.

Analogy

Versioning an ontology is changing a public API — not changing your personal notes.

If you ship a Python library and rename Customer to Client, every project that imports your library breaks the moment they upgrade. The civilised response is not 'they should rename their code'; it's 'leave Customer in place as a deprecated alias for one or two minor releases, with a clear changelog and migration guide'.

Ontologies are no different — except the consumers are knowledge graphs, SPARQL queries, downstream reasoners, dashboards. Each of them has 'imported' your IRIs. owl:deprecated true + an owl:equivalentClass bridge + a fresh owl:versionIRI is the equivalent of the deprecation cycle.

Tools & resources

W3C OWL 2 — versioning section: https://www.w3.org/TR/owl2-syntax/#Versioning_of_OWL_2_Ontologies
owl:deprecated convention: https://www.w3.org/2002/07/owl#deprecated
ROBOT release workflow — industry-standard versioned releases for OBO ontologies: http://robot.obolibrary.org/release
PURL.org — stable redirected IRIs so versioning doesn't move your address: https://purl.org/
OWL Diff / Bubastis — tools that compute the diff between two ontology versions: https://www.ebi.ac.uk/efo/bubastis/

Make it stick

Use the prompts below to anchor versioning, deprecation & migration to a real ontology you care about.

›Does every ontology your team publishes have a `owl:versionIRI`? If not, your consumers can't pin and your releases are silently breaking changes.
›Where in your last ontology release did you *delete* a term rather than deprecating it? What did that cost downstream?
›What's the smallest version of a deprecation policy you could roll out next sprint?

Reading in progress · 0 of 4 activities done

Overview

Versioning, Deprecation & Migration

Why it matters

Going deeper

Analogy

Tools & resources

Tools & resources

💭Make it stick

Make it stick