On this page
Separate a label list from an ontology contract
The source dates shown in this guide identify documentation checks on 22 October 2026, not original publication dates. Follow each citation for the vocabulary being discussed. Start by naming the annotation unit: a document, span, image region, audio interval, row, or event. Then define whether a label is a class, a property value, a relation, a workflow state, or a temporary review status.
The W3C, (opens in a new tab) describes a concept scheme with preferred and alternative labels, notes, and semantic relations. Borrowing those distinctions helps a review record say whether two strings are synonyms, translations, deprecated labels, or genuinely different concepts. It does not supply a domain taxonomy. The owner must define scope and examples.
| Ontology item | Record | Question |
|---|---|---|
| Concept identity | Stable id and human label | Can old annotations still name this concept? |
| Preferred label | Display string and language | Which label is shown to annotators? |
| Alternative label | Alias, abbreviation, or synonym | Is it equivalent or merely related? |
| Definition | Positive and negative examples | What boundary makes the label apply? |
| Relation | Broader, narrower, related, or mapped | What does the relation mean? |
| Scope note | Exclusions and uncertainty | When should an annotator abstain? |
| Version | Codebook id and effective range | Which contract governed a record? |
Do not treat a display label as evidence of a concept definition. “Other,” “unknown,” and “not reviewed” can be workflow states rather than domain categories. Keep them separate so a later reader does not confuse missing annotation with a substantive class.
Make ontology versions reproducible
A version should identify the codebook artifact, effective interval, change summary, approver role if the owner uses one, and the annotation batches to which it applies. A date alone is not a version. Preserve the prior contract and publish an explicit migration note when a concept is renamed, split, merged, or retired.
| Change type | Mapping question | Safe default |
|---|---|---|
| Rename | Did meaning remain stable or only the display text? | Keep the stable concept id and record the label change |
| Alias added | Is the new string equivalent in this language? | Add an alternative label with a scope note |
| Split | Which old records map to each new concept? | Map only with evidence; preserve ambiguous state |
| Merge | What distinctions are lost? | Retain old ids and record information loss |
| Retire | Can old data still be interpreted? | Keep a deprecated id and a replacement note |
| Hierarchy changed | Did broader or narrower meaning move? | Recheck dependent rules and examples |
| Definition changed | Which annotations need re-review? | Create a new version and identify affected batches |
Use World Wide Web Consortium, (opens in a new tab) as a vocabulary for the record itself: a source annotation set is an entity, a migration is an activity, and the resulting release is another entity. A provenance edge can show derivation without pretending that the migration preserved every meaning. Record the agent or role responsible when the owner has that evidence.
Synthetic ontology change ledger
concept_id | v1_label | v2_state | mapping | evidence
synthetic:parcel | parcel | renamed:package | direct | definition unchanged
synthetic:status | active | split:active,paused | ambiguous | source examples missing
synthetic:other | other | deprecated | none | preserve historical rows
synthetic:region | region | narrower:region.local | review | hierarchy changedKeep mappings and abstentions visible
A migration table needs a one-to-one, one-to-many, many-to-one, or no-mapping state. A blank mapping hides the difference between a deleted concept and an unresolved one. Keep the source id, destination ids, mapping type, confidence or evidence note, and whether a human decision is still required.
- Compare definitions and examples before comparing strings.
- Test hierarchy and exclusivity rules after each mapping.
- Route split and merge cases to an explicit review state instead of forcing a label.
- Keep deprecated identifiers readable in historical annotations.
- Record which rows, spans, or regions were migrated and which remain on the old version.
| Mapping state | Meaning | Report wording |
|---|---|---|
| direct | One concept keeps its meaning | Mapped under the stated definition |
| alias | Only the display or alternate label changed | Same concept, label history retained |
| split | One source concept has several possible targets | Ambiguous without additional evidence |
| merge | Several source concepts collapse to one target | Information distinction may be lost |
| retired | No replacement is asserted | Historical id preserved; current use unavailable |
| unmapped | No defensible destination was supplied | Needs owner or annotator decision |
Use a synthetic fixture before touching source annotations
Exercise the migration with invented ids and short examples. Include a stable rename, a split, a merge, a deprecated label, a changed hierarchy, and an unknown mapping. Do not use private text, customer names, locations, or raw annotation payloads to prove that the codebook changed.
| Check | Evidence field | Hold condition |
|---|---|---|
| Version identity | Codebook id and digest | Version cannot be reproduced |
| Effective scope | Batch, time, or source partition | Affected annotations are unknown |
| Definition diff | Old and new boundary notes | Only strings were compared |
| Mapping type | Direct, split, merge, retired, or unmapped | One state is hidden in a blank |
| Example coverage | Positive, negative, and abstain examples | Examples missing for a changed concept |
| Migration result | New id, old id, and unresolved state | Original id overwritten |
Keep ontology evidence separate from downstream decisions
Ontology versioning can show which definitions and mappings were used. It cannot establish that labels are accurate, that an annotation was authorized, that a dataset is private, or that a collection is suitable for a use. Keep provenance, privacy, rights, and owner decisions in separate records.
Pair this guide with missing-value and label consistency review for state semantics and the data provenance log for artifact history. After supported non-health scope, authority to describe the collection, and a controlled codebook packet are established, the qualified appraisal request path may be a next preparation step. It does not host an ontology, relabel data, create a quote, match a buyer, issue a legal opinion, or grant a license.
Takeaways
- Give concepts stable identities and keep preferred, alternative, and deprecated labels distinct.
- Version definitions, hierarchy, examples, effective scope, and migration evidence together.
- Represent split, merge, retired, and unresolved mappings explicitly.
- Use synthetic fixtures before exposing source annotations or private text.
- Keep ontology evidence separate from accuracy, privacy, rights, and downstream-use decisions.