Abbreviation registry: ownership, versions and index migration

Last updated: 6 Oct 20265 min read

tutorial

A glossary is a versioned decision service. A new expansion can change search results, annotations and generated summaries.

Separate local evidence from approved defaults

An approved registry entry can supply a fallback when a document never defines its own short form. Each entry needs an owner, expansion, domain, validity period, alias status and approval record. Local definitions are still evidence, not an automatic override across domains. Store the selected entry ID, registry version and source document revision on each expansion. Definition scope determines whether a local phrase outranks a registry candidate.

Plan collisions as schema changes

If the operations team introduces RA for Risk Assessment while shipping already uses Return Authorization, do not overwrite the older entry. Add a second domain-scoped sense and mark unqualified uses ambiguous. A renamed team, retired term or merged product can alter prior annotations. Publish a mapping from old IDs to new IDs; leave rows unresolved if the original text cannot distinguish them. Review saved searches and summary templates before activating the mapping.

Rebuild only what the decision affects

A registry update may require expanding affected search index entries, cached suggestions and quality dashboards. Record which documents used the old entry and which relied on local definitions. Reprocess the former first, then compare search results for a frozen query set. A full corpus rebuild is avoidable when dependency records are sound. Index revision auditing supplies a way to verify that visible passages match the new glossary and document revision.

Release with a rollback path

Have the owner approve the new meaning, sample affected documents and freeze an evaluation set containing both domains. Track wrong expansion rate, unresolved cases, index coverage and queries whose top result changes. A sudden drop in unresolved rate may mean the system began forcing a default. Keep the previous registry and index generation until the new version passes review. The glossary project tests this end-to-end.

Implementation

REGISTRY = {
    "RA": [
        {"entry_id": "shipping-ra-r2", "domain": "shipping",
         "expansion": "Return Authorization"},
        {"entry_id": "risk-ra-r1", "domain": "risk",
         "expansion": "Risk Assessment"},
    ]
}

def registry_candidates(short_form, domain):
    entries = REGISTRY.get(short_form.upper(), [])
    return [entry for entry in entries if entry["domain"] == domain]

assert registry_candidates("ra", "shipping")[0]["entry_id"] == "shipping-ra-r2"
assert registry_candidates("ra", "unknown") == []

Performance and operating cost

Scanning k registry entries for one short form is O(k) time and O(k) output space. A keyed index can make domain lookup effectively constant for a small, curated registry. Reindexing d affected documents costs at least O(d) before token processing; keep dependency records so a single glossary edit does not trigger a needless full rebuild.

Common Mistakes

Replacing a colliding entry instead of adding a scoped one.
Forgetting which index rows were built from the previous registry.
Using registry approval as proof that every occurrence has that meaning.
Retiring the old version before the new search results are audited.