Deprecation Workflows for Obsolete Ontology Classes and Properties

An ontology is never finished the day it goes into production. The moment a class or property starts getting used, the business it describes keeps moving, and the vocabulary that's supposed to track that business starts falling behind. Classes and properties are load-bearing: every downstream component, from properties and relationships to axioms and AI agent reasoning, depends on the stability of that core vocabulary. Shift a class definition without governing the change, and every component built on top of it inherits the confusion.

Picture a business that redefines what counts as an "active" customer or an "active" account, a routine policy change that happens inside a product or operations meeting with no ontology team in the room. The ontology doesn't get the memo. The classification rules downstream keep running against the old definition. Queries return numbers nobody trusts, AI agents reason over stale categories, and analytics dashboards produce figures that satisfy no team, because three different systems are quietly answering three different questions using the same term.

That's semantic drift, and it has no visible trigger. Nothing in the data layer raises a flag when a term stops matching reality. The term just sits there, technically valid, practically wrong. Deprecation is the mechanism that makes this kind of drift visible on purpose. It converts a silent mismatch into a governed transition, one with a named owner, a stated replacement path, and a bounded window for everyone downstream to move. The rest of this piece is a walk through how that transition actually gets built, step by step, from the formal marker on the term to the review process that decides how much scrutiny each change deserves.

What OWL and W3C Actually Provide, and Where Formal Standards Stop

OWL 2 gives practitioners a real mechanism for marking a term obsolete: an annotation property called owl:deprecated, set to the literal value "true"^^xsd:boolean, marks a specific IRI as deprecated. Together, those two signals tell any tool or person reading the ontology that this identifier shouldn't show up in new documents built against it.

That's where the formal guarantee ends. owl:DeprecatedClass and owl:DeprecatedProperty carry no additional logical force. Nothing in OWL 2 stops a developer from writing new code against a term marked deprecated, and nothing forces an existing system to stop using one. The standard gives practitioners a marker, not a lock.

This matters more at the ontology layer than people coming from ordinary software versioning tend to expect. An ontology change at the formal layer alters query results, API payloads, and the reasoning behavior of any AI agent built on top of it. That's a contract change, not a wording tweak, and it should be handled with the same discipline as a breaking change to a public API.

Two other standards sit next to OWL and are worth placing correctly. SHACL closes part of the enforcement gap OWL leaves open: it's a language for validating RDF graphs against shapes that define expected properties, value types, cardinality, and patterns, and a SHACL shape can be written to flag any use of a deprecated term before that data reaches production.

Put together, OWL declares intent, and SHACL can check compliance against that intent. Neither one builds the organizational process that decides who gets to deprecate a term, who approves the successor, and who's accountable when a downstream team misses the migration window. That process is what the rest of this workflow builds.

Who owns what: the role and authority structure before any deprecation begins

A deprecation workflow with no named authority behind it tends to default to paralysis. OBO Foundry best practice addresses this directly by prescribing a named locus of authority for every ontology under its governance: a specific person who is identifiably in charge, with explicit obligations around maintenance and responsiveness to the community using the ontology.

A workable structure splits that authority across three distinct functions rather than concentrating it in one overloaded role. Platform teams operationalize the mechanics, running the testing, publication, and rollout once a decision has been made.

Read access and write access to the ontology repository need to be treated as genuinely separate permissions, not just a technical detail of the version control system. Anyone with domain knowledge should be able to propose a deprecation, but only a smaller set of people should be able to merge and publish one. That separation is what gives an approval gate its meaning; without it, "approval" is just a formality on the way to a commit that was going to happen anyway.

One more role deserves a name before any of this starts: whoever owns exceptions. Some downstream consumer, somewhere, will need more time than the stated deadline allows, and someone has to have the standing authority to grant that extension and accept the risk that comes with it. The deprecation annotation itself should record the name or role of the approving authority alongside the date, so the decision trail survives personnel turnover and still makes sense to someone reading it two years later.

Identifying candidates for deprecation: triggers, signals, and the case review

A deprecation should start from a defined condition that someone can point to, not from a hallway conversation about a term that "feels off." Four trigger categories give practitioners something concrete to check against.

The first is a business rule change: the concept a term was built to describe no longer matches how the organization actually defines that thing, the "active entity" scenario described earlier. The second is an upstream ontology change, where a parent or reference ontology that the team imports from has revised or removed a term, forcing downstream alignment. The third category is redundancy, where a more precise child term has grown to cover everything the parent term used to handle. The fourth category covers structural errors, where the term was placed incorrectly in the hierarchy from the start, something the True-Path Rule is built to catch, since it requires that every parent of a term apply wherever the term itself applies.

Once a candidate surfaces under one of these triggers, it needs a case review, and that review should be brief and documented rather than a drawn-out committee hearing. The record should state what the term currently does, why it no longer serves that purpose, which downstream consumers actually use it, and whether a successor term already exists or still needs to be built before the deprecation can move forward. That dependency mapping matters because business logic built on a term tends to live scattered across many tools at once, and tracking where sensitive information and logic actually flow is what the case review is for, done before the annotation gets written rather than discovered after the fact when something breaks.

Two different reasons lead a term into this review: some terms are obsolete but were modeled correctly all along. They simply aren't needed anymore. Others were structurally wrong from the start, and those require fixing whatever depends on them before retirement, not just a clean handoff to a successor.

Writing the deprecation annotation: required fields and successor mapping

An annotation that states only owl:deprecated "true"^^xsd:boolean tells a downstream consumer that something changed and nothing about what to do next. The annotation has to carry enough context that a team encountering it for the first time can migrate without ever tracking down whoever wrote the original term.

Start with the formal marker itself, owl:deprecated "true"^^xsd:boolean, since that's the piece tools and reasoners actually recognize. Add a pointer to the successor term using a standard annotation property, commonly dcterms:isReplacedBy or an equivalent ontology-local property, and if no successor exists yet, state that along with the expected timeline for one to arrive. Finally, record the version number in which the deprecation takes effect, so teams that aren't ready yet can pin their imports to the last pre-deprecation release while they work on migrating.

None of this replaces the standard anatomy every ontology term already carries under NIEHS best practice: label, ID, definition, parent term, synonyms, reference, and comment. The deprecation annotation builds on top of that anatomy rather than overwriting it, and the original definition has to stay exactly where it was, because consumers reading old data still need to know what the term meant when it was applied.

Successor mapping carries the most weight in the whole annotation. If a term splits into two replacements, both have to be named explicitly. If a term gets absorbed into an existing term, the absorbing term's IRI has to be cited directly. If a term is simply being removed with nothing replacing it, that has to be stated outright, along with the reasoning behind removing it rather than replacing it.

One detail gets missed often enough to deserve its own emphasis: never recycle the IRI of a deprecated term. That identifier has to stay permanently resolvable, and it has to resolve to something useful, typically the deprecated record itself, though a redirect to the successor can work as long as the deprecated record's own metadata stays reachable from somewhere. This preserves the validity of every piece of existing data tagged with the old term, and it makes an audit possible later, when someone needs to know what a given piece of data meant at the time it was annotated.

Successor term creation and semantic alignment before publication

Publishing a deprecation before its successor is ready leaves downstream teams with two bad options: freeze in place until something arrives, or build their own replacement on the spot. The second option is worse than the drift the deprecation was meant to fix, since it scatters the organization's definition of the same concept across however many teams decided they couldn't wait.

A new successor class has to clear the same bar as any other new ontology term before it gets published alongside the deprecation notice. That means a label, a unique ID, a precise definition, a correctly placed parent term, synonyms where they apply, and a supporting reference, the full term anatomy, not a shortcut version because it's replacing something rather than introducing something new. A successor that skips this check doesn't resolve the structural debt the deprecation was meant to retire. It just creates a fresh one at the exact moment the old one was supposed to close.

Where a term splits into multiple successors, each one has to stand on its own as a valid term in its own right, not lean on the others for coherence. Where a term gets absorbed into something that already exists, the absorbing term's definition may need to be broadened to actually cover the ground the old term used to, and that broadening is its own ontology change, carrying its own review obligation rather than riding in quietly on the back of the deprecation.

Successor placement can reach well beyond the domain that proposed it. The governance board needs to be in the loop before publication, not after, because a single domain steward has no way to see that kind of cross-domain consequence from inside their own area, which is the whole reason the architecture function exists.

Before anything ships, run automated consistency checks against both halves of the change: the deprecated term in its newly annotated state, and the successor term in its new position in the hierarchy. Tooling such as ROBOT is built for exactly this kind of check, and its repair functions can update references to a deprecated class once that class carries an annotated suggested replacement. A deprecation that introduces a new inconsistency into the ontology shouldn't go out the door, no matter how urgent the underlying business reason for the change happens to be. Standard practice is to stage the successor and its deprecation pointer on a development branch first, reviewed by at least one other person before it ever reaches the production release, with automated tooling in the CI/CD pipeline running integration tests to catch inconsistencies before they ship.

Risk classification: how to route a deprecation through the right level of review

Not every deprecation deserves the same level of scrutiny, and treating them as if they do wastes the governance capacity that ought to be reserved for the changes that can actually do damage.

A sound risk classification sorts deprecations by the scope of what depends on the term. A term used only inside internal documentation or a single team's queries is low risk, and a lightweight sign-off from the domain steward is enough to move it through. A term referenced by multiple downstream systems, APIs, or AI agents reasoning over it in production sits at a higher tier, and that tier should route through the governance board, with a validated successor and a full case review before publication. A term with cross-domain reach, the kind the IDO ecosystem ran into when a single extension's term turned out to matter to several sibling ontologies, needs the broadest review of all, since no single steward or board sitting inside one domain has visibility into every system the change will touch.

The tier a deprecation lands in should determine how many of the steps in this workflow get applied in full force and how many get a lighter pass. Low-risk changes still need the annotation fields, the sunset date, and the successor mapping. High-risk changes need all of that plus the architecture board's sign-off, the automated consistency checks, and a staged rollout through a development branch before anything reaches production. What risk classification buys an ontology team is the ability to run this governance process continuously, on every obsolete term as it surfaces, rather than saving it for the rare emergency and letting the rest of the vocabulary quietly drift out of date in the meantime.