Vocabularies need versioning and change records as the domain evolves

What it is

Domains rename, merge, split, and retire. If the vocabulary is only “whatever is current,” objects tagged yesterday with an old preferred term become untagged or mistagged today, and retrieval and nav cannot explain why they moved. Versioning and a change record require that every preferred-term rename, merge, and split leave behind: when, who, from which ids to which ids, how the old word redirects. A version is a migration graph for machines and for later people, not a release-note sentence that “classification was improved.”

Updating a vocabulary with no change record is anonymously rewriting the coordinates of every historical object.

Why it happens

A vocabulary is a foreign key that objects point at. Change the preferred term and not the references, and the UI is a field of old words; change the references and leave no mapping, and old queries and bookmarks die. Merging two concepts is a many-to-one data migration; splitting is one-to-many and usually needs human retagging. Retirement is not deleting the node; it is marking it historical and naming a successor, or objects linked to that term fall into an empty class. Version numbers let the index, the nav, and help declare which vocabulary they were compiled against, so the three channels do not each eat a different snapshot.

Change also has social memory: old words users already learned must keep mapping to the new node for a while, and that window is itself version information.

Studying it

Take controlled rename / merge / split events and measure whether objects, queries, and bookmarks still arrive.

• Paradigms: on an experimental vocabulary, perform rename, merge, split, retire; run known-item retrieval and tree tests with and without a migration graph; audit whether a live vocabulary’s commit log is enough to rebuild an object’s coordinate history.
• Independent variables: whether old ids are kept, how long old words remain non-preferred, whether splits force retagging.
• Dependent variables: survival of pre-change queries, objects landing in empty classes, whether three channels share a vocabulary version, whether “what was this object tagged last year” can be answered.
• Methodological note: looking only at the post-release current tree treats migration failure as “users cannot learn the new classes.” Treat the change as an experimental event. If production has no log, add the log before claiming governance maturity.

Where it stops holding

Candidate terms never referenced by an object can be hard-deleted without entering version history. Same-day spelling fixes that were never referenced need not be a major version, but they should appear in the commit message so they do not recur. External statutory vocabularies (industry classification codes) have their own version cycles; the local vocabulary should record which external version it aligns to, not invent a mutually unintelligible numbering. Personal folk tags have no global version; do not manage private words with vocabulary versions.

Applying it

• Stamp a version on every vocabulary release. Encode rename / merge / split / retire as machine-readable mappings; migrate object references; keep the old word in retrieval mapping for a declared window.
• Nav, help, and the search index declare the vocabulary version they depend on. Release checks that the three channels share one number.
• Splits must carry a retagging task. Do not change the tree and leave every object piled on one child.
• Verify with one real rename and one merge, replaying pre-change queries and bookmarks. Arrival at the new node plus the ability to say “what it used to be called” means the version layer is wired. A new tree plus zero hits on old words means the vocabulary update happened only in a document.

Related

• Within the group: G1.10.1 A controlled vocabulary gives each concept one preferred term; others point to it · G1.10.2 A thesaurus describes hierarchy and association with broader, narrower, and related terms · G1.10.3 Authority files hold canonical names for entities and resolve homographs and aliases · G1.10.4 Controlled vocabularies are staff-maintained, unlike folksonomies · G1.10.5 At retrieval, non-preferred terms map to the preferred term and yield the same results
• Adjacent: G1.11 Architectural scalability and evolution · G1.08 Terminology consistency · T3.03 Content freshness and maintenance
• Search terms: vocabulary versioning · concept migration · thesaurus change management