Version it with intent.

The argument, up front

Versioning is not bookkeeping. It is the mechanism that lets an ontology change without betraying the systems, datasets and teams built on top of it. Done well, it is nearly invisible: a new version appears, a changelog explains it, deprecated terms linger with signposts to their replacements, and nothing downstream breaks by surprise. Done badly — a term quietly renamed, a constraint silently tightened — it corrupts data and erodes trust faster than any missing feature.

The rules, at a glance

OWL gives every ontology two identifiers, and the whole discipline rests on keeping them straight. The ontology IRI names the ontology as an evolving thing — it never changes and always denotes “the current release.” The versionIRI names one specific, frozen release, and a new one is minted every time you publish.

Consumers choose which to reference by what they need: the bare ontology IRI to always track the newest release, the versionIRI to freeze a dependency. Both point into the same set of permanent term IRIs — …/policy/Policy is the same identifier in every release. That is the invariant that lets data outlive versions.

# The subject is the permanent ontology IRI; versionIRI names this release.
<https://example.org/ontology/policy/> a owl:Ontology ;
    owl:versionIRI   <https://example.org/ontology/policy/2.1.0> ;
    owl:versionInfo  "2.1.0" ;
    owl:priorVersion <https://example.org/ontology/policy/2.0.0> .

Use a MAJOR.MINOR.PATCH version string, and let the effect on consumers choose which number moves. The test is a single question: could this change invalidate existing data, or alter an inference someone relies on?

The same edit can be safe or catastrophic depending on its effect. This table classifies the common changes; when in doubt, treat it as the more severe.

Removal is a breaking change; deprecation is the humane path to it. Instead of deleting a term, mark it deprecated, keep it in place as a tombstone, point to its replacement, and schedule its actual removal for a future major release — giving consumers a window to migrate.

• Mark it. Add owl:deprecated true (the OWL 2 way; the older owl:DeprecatedClass / owl:DeprecatedProperty still appear in legacy models).
• Signpost the replacement. Link the old term to the new one with dct:isReplacedBy (and dct:replaces the other way), so tools and humans can follow the migration.
• State the timeline. Record when it was deprecated and the earliest release it may be removed — in an annotation and the changelog.
• Remove only later. The actual deletion is itself a major change; do it in a subsequent major release, not the one that deprecated the term.

# Deprecate in 2.1.0 — keep the tombstone, point to the replacement.
policy:premiumAmount a owl:DatatypeProperty ;
    owl:deprecated    true ;
    dct:isReplacedBy  policy:hasPremium ;
    owl:versionInfo   "deprecated in 2.1.0; removed no earlier than 3.0.0" ;
    rdfs:comment      "Use policy:hasPremium instead."@en .

The most consequential versioning decision is where the version number is allowed to appear. The rule: never in a term or namespace IRI. A term’s IRI is a permanent identifier that data everywhere refers to; put a version in it and every new release orphans all existing data. Versions belong to the versionIRI and to document URLs — not to the identifiers themselves.

Each release should carry, on its owl:Ontology node, enough metadata for a consumer to know what this is, what it supersedes, and whether it is safe to adopt.

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<https://example.org/ontology/policy/> a owl:Ontology ;
    owl:versionIRI              <https://example.org/ontology/policy/2.1.0> ;
    owl:versionInfo             "2.1.0" ;
    owl:priorVersion            <https://example.org/ontology/policy/2.0.0> ;
    owl:backwardCompatibleWith  <https://example.org/ontology/policy/2.0.0> ;
    dct:title                   "Policy Ontology"@en ;
    dct:created                 "2023-04-01"^^xsd:date ;
    dct:modified                "2025-11-18"^^xsd:date ;
    owl:imports                 <https://example.org/ontology/core/1.4.0> .  # pinned

A modular ontology versions module by module — each carries its own version and moves on its own clock. Two habits keep a multi-module system coherent.

The workflow’s “record” step needs a home. Capture the changelog at three altitudes and keep one of them authoritative — then generate the others, rather than typing each change into three places.

Tier 2 — the human changelog

# CHANGELOG.md - Policy ontology (one file per module)

## [2.1.0] - 2025-11-18   (minor)
### Added
- policy:hasPremium   (datatype property)
### Deprecated
- policy:premiumAmount → use policy:hasPremium; removed no earlier than 3.0.0
### Fixed
- Corrected the definition of policy:Endorsement

Tier 3 — lightweight change notes on the terms

# Change notes that travel with each term.
policy:hasPremium a owl:DatatypeProperty ;
    skos:historyNote "Introduced in 2.1.0."@en ;
    dct:modified     "2025-11-18"^^xsd:date .

policy:premiumAmount a owl:DatatypeProperty ;
    owl:deprecated   true ;
    skos:changeNote  "Deprecated in 2.1.0; use policy:hasPremium."@en ;
    dct:isReplacedBy policy:hasPremium .

Tier 3 — a structured version chain & change records

# A version chain (PROV-O) + reified change records.
<https://example.org/ontology/policy/2.1.0> a owl:Ontology, prov:Entity ;
    prov:wasRevisionOf   <https://example.org/ontology/policy/2.0.0> ;
    prov:generatedAtTime "2025-11-18T09:00:00Z"^^xsd:dateTime ;
    prov:wasAttributedTo  policy:working-group .

policy:chg-2.1.0-001 a :ChangeRecord ;
    :inVersion       <https://example.org/ontology/policy/2.1.0> ;
    :affects         policy:premiumAmount ;
    :changeType      :Deprecation ;
    :level           :Minor ;
    dct:date         "2025-11-18"^^xsd:date ;
    dct:isReplacedBy policy:hasPremium ;
    rdfs:comment     "Deprecated; use policy:hasPremium."@en .

The change-record meta-model

Match the altitude to the need

Every change runs the same short path. The detect-and-classify steps at the top are what make the rest mechanical.