How to deprecate and replace ontology terms safely

Executive Summary

An ontology term is a promise about what its identifier denotes. To deprecate and replace a term safely, a steward must first compare the referents admitted by the old definition and axioms with those admitted by the proposal. A spelling or clarity edit that preserves that set can keep the term IRI. A narrower, broader, or otherwise different set calls for a new IRI under OBO Foundry Principle 19; the old identifier remains discoverable with an explicit retirement state and replacement guidance. This is an OBO community rule, not a universal law: Dublin Core independently distinguishes minor editorial corrections from changes that materially affect functional semantics. ^{[1] [2]}

The operational choice is among retain, deprecate with one exact replacement, deprecate with candidates for review, and deprecate without a replacement. The exact branch requires evidence that every use of the old term can be interpreted under the proposed successor without changing the proposition conveyed. Candidate mappings signal a decision still belongs to a consumer. A deprecated marker by itself is metadata: Web Ontology Language (OWL) annotations do not change logical consequences or rewrite stored assertions. The migration notice therefore needs old and new definitions, a referent comparison, affected uses, a release identifier, an owner, an effective date, a reason, and an explicit data action. ^{[1] [3]}

The release has two identities to preserve. A term IRI identifies the concept. An ontology IRI identifies the ontology series, while a version IRI identifies one release of that series. OBO Foundry calls for a unique, resolving version IRI for each official release and says released artifacts must remain unchanged. Consumers need to pin the release they tested and retain access to earlier artifacts. Merely increasing a version number cannot prove their queries, shapes, reports, or classifications are compatible. ^{[3] [4]}

Published impact evidence is substantial but narrow. In one historical Gene Ontology study, the term count rose from 16,139 in February 2004 to 40,810 in January 2015, with 2,356 terms and 553 relationships mapped to new terms or relationships in two branches. The same study found that median consistency against its 2015 reference changed from 0.27 with the 2004 ontology to 1 with the 2015 ontology while annotations were held constant. Neither result estimates the prevalence of term retirement across ontologies. A local impact count should instead state its inventory denominator, measured old-IRI uses, and unknown consumers separately. ^[5]

Introduction and Background

Term retirement is a consumer contract problem. A label may change while the concept remains stable; a plausible new definition may silently exclude records previously classified under the term. In the first case a new identifier creates unnecessary churn. In the second, reusing the identifier lets two releases assign different meanings to the same stored assertion. OBO Foundry names the criterion directly: a proposed definition that substantially changes referents requires a new term and IRI. Its policy also treats logical axioms and elucidations as possible changes to meaning. ^[1]

This report is for ontology stewards and application owners approving a term edit. It uses referent set to mean the real-world things that satisfy the term under a specified definition and logical context. Here, semantic change means an edit that changes that set, whether through wording or logical axioms. Equality of words is neither necessary nor sufficient for equality of referents. A grammar correction can leave the set unchanged. Adding an exclusion such as “only externally published” can remove members even if the old label is retained. Dublin Core's namespace policy similarly keeps a URI after minor editorial correction and changes it when meaning changes with substantial functional impact. ^[2]

A stable identifier does not imply a frozen label, and a version identifier does not absolve a publisher from explaining changed meaning. OWL 2 distinguishes the ontology IRI from the version IRI, whose combination identifies a particular version. The W3C Data on the Web Best Practices recommend persistent identifiers, version histories, and access to earlier versions. Those are publication conditions; a consumer still needs to assess each term-level migration. ^{[3] [6]}

The practical unit of review is therefore one proposed edit and its known consumers. The review should record the prior artifact, proposed artifact, old and new definitions, a small discriminating set of examples, the IRI choice, the replacement assertion if any, and an acceptance result for each known consumer. The absence of a discovered use is a measured finding about the searched inventory, not proof that no external user exists. OBO Academy advises checking annotations and dependent children before obsoletion and notifying affected groups. ^[7]

Term identity and the referent-change test

Three identifiers, three questions

A term IRI answers which concept an assertion uses. The ontology IRI identifies the evolving ontology. The version IRI identifies the artifact against which a statement or test was interpreted. OWL 2 says the ontology and version IRIs together identify one version, and recommends older documents remain accessible through their version IRIs. TDWG's maintained vocabulary specification likewise distinguishes a persistent current term IRI from dated term-version IRIs that can expose historical definitions. ^{[3] [8]}

An assertion such as :record42 a :PublicSourceStatement depends on the meaning of :PublicSourceStatement; changing only a label does not alter that assertion. If a publisher narrows the concept to statements from public web pages, old assertions drawn from public print archives may become false under the new interpretation. The identity test asks whether the same entities qualify before and after the proposed change. For each boundary case, record inclusion under both definitions and the reason. A new label or synonym is a separate usability decision. OBO Foundry explicitly allows minor clarity, grammar, and punctuation edits while preserving a term's referents. ^[1]

A steward should inspect more than the text field. Subclass placement, restrictions, property domains and ranges, and imported axioms can change inferred membership or practical query results. OBO's stability principle includes logical axioms when assessing meaning. A term whose definition is too vague, restrictive, misused, or misunderstood may need obsoletion rather than another invisible edit. The test is contextual: record the release and imports under which the old and proposed referent sets were judged. ^[1]

A reproducible review packet

• Capture identity. Record the full term IRI, old label, textual definition, axioms, ontology IRI, and version IRI.
• Specify boundary cases. Include at least one old-only, one new-only if possible, and one shared referent; explain why each belongs.
• Compare inference. Diff asserted and inferred relationships relevant to applications, not only text labels.
• Classify the edit. State whether the referent set is unchanged, changed, or too uncertain to establish equivalence.
• Record evidence. Keep the prior version artifact, proposed artifact, review date, reviewer, and issue or decision record.
• Ask consumers. Check annotation corpora, other ontologies, query text, validation shapes, user interfaces, exports, and cached mappings.

A semantic diff is useful evidence, but its result is not the policy decision. ROBOT's diff command compares ontologies while ignoring textual serialization differences. Query and verification tools can then test specific assertions or rules. The steward must still justify whether the altered entailments change the intended referents. ^{[9] [10]}

Decision table: retain, replace, consider, or retire

Table 1 is a term-level approval table. “Exact” means the replacement can be substituted for all intended old uses in the stated scope, not merely that two labels resemble one another. A candidate signals a human decision. OBO's replaced_by and consider guidance distinguishes these paths; LinkML similarly separates exact from possible replacement metadata. ^{[11] [12]}

The row for a changed meaning preserves the old IRI as the identity of the old concept. It does not require immediate obsoletion if the old concept remains useful. When it is obsolete, OBO guidance says to set owl:deprecated to true in OWL or is_obsolete: true in OBO format, remove its logical axioms and internal usages, and retain its textual definition for readers. Gene Ontology likewise keeps an obsolete term's identifier while removing relationships to other terms. ^{[1] [14]}

Replacement vocabularies are not interchangeable. OBO format's replaced_by maps to IAO:0100001, while consider maps to a separate OBO-in-OWL property. Dublin Core's dcterms:isReplacedBy names a superseding resource; Schema.org's supersededBy names a superseding term; TDWG uses dcterms:isReplacedBy in its vocabulary publication rules. A project should publish the actual property IRI and the intended semantics, rather than relabeling a loose mapping “exact.” ^{[15] [16] [17] [8]}

Simple Knowledge Organization System (SKOS) mapping predicates answer a different question. skos:exactMatch expresses high confidence of interchangeability across a wide range of information retrieval uses; skos:closeMatch is weaker and application dependent. Neither alone says that old data must be rewritten, nor does a successor relation assert strict identity. If mapping metadata is sparse, consumers cannot infer the scope, evidence, or review status of the migration. ^{[18] [19]}

Release and migration procedure

Discover consumers before choosing a date

A term inventory should search for the old IRI and compact identifier in data assertions, ontology imports, annotation exports, SPARQL queries, SHACL shapes, user-interface labels, rule files, reports, and mapping tables. Count the number of known consuming systems, not merely triples: one application can repeat an IRI millions of times, while one query in a smaller system may be critical. Record the search method, timestamp, owners, and access boundaries. OBO Academy specifically advises checking annotations and children and discovering use in other ontologies before obsoletion. ^[7]

• Direct assertions. Search all known RDF graphs for subject, predicate, or object occurrences of the IRI.
• Indirect effects. Inspect subclass descendants, property restrictions, and reasoning-dependent reports.
• Code and configuration. Search query repositories, mapping files, forms, validation shapes, and export transforms.
• External dependencies. Check other ontologies and public mapping registries, then mark unreachable consumers unknown.
• Owner confirmation. Have each known consumer confirm its use, expected meaning, and test owner.
• Denominator discipline. State the number of systems in the inventory, the number checked, and the number using the term.

SPARQL 1.1 provides COUNT over bound expression values; ROBOT can run ASK, SELECT, and CONSTRUCT queries over an ontology. Those tools help measure known usage, but a count of assertions is not a count of affected consumers or semantic errors. This distinction matters when a term is imported as a superclass yet never directly asserted. ^{[20] [21]}

Publish a release that can be revisited

Choose an effective release only after the decision packet and consumer inventory are reviewable. OBO Foundry Principle 4 requires a unique version IRI that resolves to each official release and prohibits changing official release content after publication. W3C recommends a complete version history. A notice should link both the old and new artifacts, including checksum or retrieval information where available, so a consumer can reproduce which definition it tested. ^[4]

A pre-release notification is part of the migration, not an afterthought. OBO Foundry Principle 13 recommends at least seven days of advance notice for material changes. That is a community recommendation, not a universal service-level guarantee; local contracts may require more time. OBO Academy notes that each ontology can have its own obsoletion procedure and advises notifying affected groups. ^{[22] [7]}

Migration notice template

• Decision ID and owner: stable issue or decision reference; named steward and contact route.
• Old term: IRI, label, exact old definition and axioms, and old version IRI.
• Proposed state: retain, active old concept plus new concept, deprecated with exact replacement, deprecated with candidates, or deprecated without replacement.
• New term: IRI, label, exact new definition and axioms, with a plain-language boundary example.
• Referent change: old-only, shared, and new-only cases; state whether equivalence was demonstrated or remains unknown.
• Machine-readable notice: owl:deprecated Boolean and the project's precise replacement property, or the OBO-format tags where applicable.
• Effective release: version IRI, expected publication date, access to prior release, and earliest consumer action date.
• Known use: inventory denominator, affected consumer IDs and owners, usage counts, search coverage, and separately listed unknown consumers.
• Required action: substitute, classify record by record, retain legacy meaning, or stop new assignment; include mapping rules and exceptions.
• Compatibility evidence: query, SHACL, inference, export, and historical replay results; name each test and responsible owner.
• Review path: feedback channel, unresolved cases, rollback criteria, and decision deadline.

The notice is a governance record, not a data transformation. OWL 2 describes owl:deprecated as an annotation on an IRI, and annotations are ignored when computing logical consequences. A consumer has to implement any rewrite, reject new uses, or display warning explicitly. SHACL can validate a data graph against a shapes graph but leaves both unchanged. ^{[3] [23]}

Test compatibility at the consumer boundary

• Query test. Re-run saved queries against the old and candidate releases; compare the result sets, not only query success.
• Shape test. Validate old and migrated data against the old and new shapes; explain intentional failures.
• Inference test. Compare class membership and constraints under the recorded import closure.
• Export test. Inspect serialized IRIs and mappings consumed by downstream systems.
• History test. Reproduce a record under the prior release and verify its old interpretation remains available.
• Exception test. Sample ambiguous old assertions and document individual decisions.
• Rollback test. Restore the previous release and mapping state if acceptance criteria fail.

ROBOT report can run quality-control SPARQL queries; verify evaluates SELECT-based rules. A release's version label is useful routing information but not evidence of downstream compatibility. Semantic Versioning itself requires a declared public application programming interface (API); ontology consumers must define their own compatibility surface. ^{[24] [10] [25]}

Worked term decision (Hypothetical Example)

Suppose a fictional ontology defines ex:SourceStatement as “a statement appearing in an externally available source.” A proposal changes it to “a statement appearing on a publicly accessible web page.” The new wording excludes statements from print archives that were externally available but not on the web. That is a narrower referent set. Under the OBO stability test, the steward cannot reuse the old IRI for the narrowed concept. ^[1]

Table 2 records the decision. The example is hypothetical; its identifiers and quantities are illustrative, not observed adoption data.

The alternative cosmetic edit is “statement in an externally available source,” changing only grammar. If reviewers show the same cases qualify and the relevant axioms are unchanged, the term IRI stays. The distinction rests on members of the referent set, not on the editor's intention or the apparent size of the text diff. Dublin Core's editorial policy reaches the same practical split for minor corrections versus functional semantic change. ^[2]

If the old definition was actually ambiguous, the steward should not manufacture an exact successor merely to make automated migration easy. Record disputed cases and consider multiple alternatives. OBO Foundry provides consider for inexact candidates; LinkML separately labels a possible replacement. A no-replacement decision is legitimate when no successor can preserve the old proposition. ^{[12] [13]}

Data Analysis and Evidence

Evidence for impact has two levels: historical ontology studies and the local consumer inventory. The historical studies demonstrate that ontology evolution can alter analysis, but their results are not a cross-domain retirement rate. In a Gene Ontology analysis of February 2004 to January 2015, the reported term count increased from 16,139 to 40,810, a change of 24,671 terms by subtraction. The authors reported 2,356 terms and 553 relationships mapped to new terms or relationships in two branches; these are not counts of obsolete terms and should not be labeled as such. ^[5]

In that Gene Ontology analysis, with 2015 annotations held fixed, median consistency against the 2015 reference was 0.27 with the 2004 ontology and 1 with the 2015 ontology. Another longitudinal study used 15 Gene Ontology versions over seven years. These are study-specific demonstrations that release dependencies matter, not a basis for predicting the percentage of a company's records that require migration. ^{[26] [5]}

A consumer inventory gives a better operational denominator. In the following deliberately hypothetical inventory, six registered consumers were checked for ex:SourceStatement: three have direct assertions, one has a query or shape dependency, and two show no known use. Two other possible external consumers lack access for inspection and are recorded separately as unknown. The number of known affected consumers is 4 of 6 checked, or 66.7% by calculation; the total potential affected count is unresolved because the two external consumers have unknown use. The three direct-use systems contain 120, 24, and 6 old-IRI assertions respectively, totaling 150 occurrences. These invented figures illustrate the method only.

Table 3 shows why a count of occurrences cannot be substituted for a count of systems.

The defensible metric is therefore a vector, not one adoption number: checked systems 6, known affected 4, direct occurrences 150, unknown external systems 2, and a named search date and method. SPARQL COUNT can compute occurrences in a graph; owner confirmations and dependency search establish systems. A release should report both. ^{[20] [7]}

No representative public estimate of the probability that any ontology term will be retired, or that a given consumer will break, was established by the reviewed sources. The studies above use particular biomedical ontologies and analysis tasks. The historical values support a risk model in which ontology and annotation versions are held fixed during tests, then varied deliberately. They do not warrant a universal percentage or an unqualified claim that every meaning change causes application failure. ^{[5] [26]}

Implications and Future Directions

Term lifecycle governance is strongest when a machine can discover the state and a person can understand the reason. TDWG's vocabulary standard distinguishes persistent current term IRIs from dereferenceable version IRIs and provides a replacement relation for deprecated terms. As of September 2026, Schema.org publishes dated snapshots and a supersededBy relation; the European Union Publications Office makes prior vocabulary versions and release notes available. These are different publication designs, but each exposes the change rather than making the consumer infer it from a new label. ^{[8] [27]} (Source: op.europa.eu)

The next practical improvement is a structured notice whose old/new definition, evidence, effective release, and owner can travel with exported values. W3C PROV-O's attribution pattern can identify an agent responsible for a notice, while W3C Data on the Web guidance calls for discoverable feedback and version history. Such metadata makes a challenge and correction path explicit; it does not decide equivalence automatically. ^{[28] [6]}

For organizations that need to defend values derived from changing vocabularies, the prior state must remain inspectable. Reliable Context describes a canonical record with a verbatim, cited, dated source behind every value and a reproducible past state; those observable properties can support an application owner's review of what a value meant at a prior ontology release. They do not replace the ontology steward's obligation to issue the term decision or the consumer's compatibility test.

Mappings need their own evidence. Matentzoglu and colleagues reported that mappings often lack metadata needed for correct interpretation. A future release process can attach the mapping author, scope, justification, source and target versions, confidence or review state, and exceptions. Where a successor is only a candidate, it should remain a candidate in both human notice and machine-readable data. ^{[19] [12]}

Frequently Asked Questions (FAQs)

When should an ontology term be retired rather than clarified?

Retire it when the concept is no longer a sound active category, or when its intended repair would change what the old IRI denotes. A clarity edit can retain the IRI only after the referent comparison supports unchanged membership. A changed meaning should receive a new IRI, while the old term may remain active for its old meaning or be deprecated if no longer maintained. OBO Principle 19 includes both textual and logical changes in that judgment. ^[1]

Is deprecated the same as obsolete?

No single universal terminology controls all vocabularies. In OWL, owl:deprecated true is an annotation on an IRI. OBO format uses is_obsolete: true for an obsolete stanza; OBO Foundry maps its OWL obsoletion practice to owl:deprecated. A project's notice must state its lifecycle state and whether new assignments are allowed. Neither marker deletes old data by itself. ^{[3] [1]}

Can an ontology term be replaced automatically?

Only after the publisher and consumer establish the scope of exact substitution. An OBO replaced_by assertion or LinkML exact-replacement annotation is stronger guidance than consider or possible replacement. Even then, test context-sensitive queries, shapes, inference, and exports before rewriting records. If old records split among successors, classify each record or preserve its legacy IRI until resolved. ^{[11] [1] [10]}

Does a new ontology version solve a changed term meaning?

A new version identifies the changed artifact and enables retrieval of the prior artifact. It does not give a changed concept a new identity or ensure consumer compatibility. OBO requires distinct official version IRIs and immutable release files; OWL 2 distinguishes version IRIs from ontology IRIs. Semantic version labels require a declared public API if their compatibility implications are to be meaningful. ^{[4] [25]}

How should a team handle an unknown external consumer?

List it as unknown, name why usage cannot be inspected, publish the notice at a stable location, and provide a feedback route. Count only consumers in the declared inventory when reporting migration impact. W3C Data on the Web Best Practices recommends a discoverable feedback mechanism, and OBO Academy advises notification of affected groups. ^{[6] [7]}

Conclusion

A safe term edit begins with a referent comparison, not a version-number choice. If the old and proposed definitions and axioms admit the same things, document the clarification and retain the IRI. If they admit different things, publish a new IRI for the new concept. Decide separately whether the old concept remains active or becomes obsolete, and whether any successor is exact, merely a candidate, or absent. OBO Foundry's term-stability principle states that rule for its community; Dublin Core's namespace policy illustrates the same distinction in another vocabulary setting. ^[2]

The release must let consumers reconstruct the decision. Keep the old identifier and definition discoverable, publish an immutable versioned artifact, state the machine-readable retirement and replacement relation, and give a notice with an owner, effective date, rationale, and examples. Search for use in data and code, then test queries, shapes, inference, exports, and prior-state retrieval against the releases actually used. Count affected systems only from the declared inventory, with inaccessible consumers explicitly unknown. ^{[1] [7] [23]}

The decisive acceptance question is concrete: can every known old assertion still be interpreted truthfully after the proposed migration? If yes, an exact replacement may be defensible within the documented scope. If not, preserve the old meaning, use candidate guidance, or review assertions individually. A deprecation annotation communicates the decision, while tested consumer action completes it. ^[3]