Skip to content

Canonical Registry

Reference register — instantiates Source-of-Truth Assignment

Maintains the one official list of entities and their canonical identifiers that every system looks up, with a mapping from aliases and legacy codes back to the canonical entry.

Canonical Registry governs identity and naming: it is the official list of the things everyone refers to — entities, codes, statuses, definitions — each with a stable canonical identifier that other systems dereference instead of storing their own spelling. Its distinguishing job is reference integrity, not attribute truth: the registry makes sure two systems mean the same entity when they say the same code, and that a dozen variant names all resolve back to one canonical entry. It does not decide the entity's changing state — only that there is one agreed identity to hang that state on.

Example

An airline refers to airports across a dozen systems — booking, crew scheduling, baggage, operations. Some use IATA codes (LHR), some carry a legacy internal code, some hold free text ("London Heathrow", "Heathrow Intl"). Baggage routing and booking silently mismatch because "Heathrow" in one system isn't joined to LHR in another. The airline stands up a canonical registry of airports: one entry per airport keyed by its IATA identifier, published for every system to look up, plus an alias map (LHR ← "Heathrow", ← "London Heathrow", ← legacy code 0431). Now every system resolves any of those to the one canonical airport, and the baggage-versus-booking mismatch disappears because both dereference the same identifier rather than string-matching names.

How it works

The registry is a keyed list read by many and written by few. Its contract is the identifier: a new entity is admitted once, given a canonical ID, and thereafter referenced by that ID everywhere. Variant spellings, legacy codes, and merged duplicates are captured as aliases that resolve to the canonical entry, so messy inbound references still land on one thing. The registry publishes this list (as an API, a replicated table, or an export) so consumers dereference rather than reinvent. Its focus is deliberately narrow — which identity, not what is currently true about it.

Tuning parameters

  • Identifier scheme — adopt an external standard (IATA, ISO country codes) or mint internal IDs. External schemes ease interoperability; internal ones give control but must be maintained.
  • Alias tolerance — how generously variant names and legacy codes are mapped in. Generous mapping catches messy inputs but risks collapsing two genuinely distinct entities into one.
  • Admission bar — how much validation a new entry passes before it gets a canonical ID. A high bar keeps duplicates out of the registry itself.
  • Publication freshness — whether consumers query live or hold periodically refreshed copies, trading currency against load and coupling.

When it helps, and when it misleads

Its strength is one dereferenceable identity, which kills a whole class of name-matching bugs and lets independent systems join on meaning rather than spelling. Its failure modes are the mirror images of its job: duplicate entities slipping in (two IDs for one real airport) quietly defeats the point, and users mistaking the registry for a system of state — treating "it's in the registry" as if it settled the entity's current attributes, which the registry never claims to govern. The classic misuse is letting many systems write their own entries, so the "canonical" list forks into several. The discipline that guards against this is a strict admission bar with de-duplication and a single write path, keeping the registry a governed authority rather than a shared scratchpad.

How it implements the components

  • canonical_identifier — mints and holds the stable identifier that is the registry's contract with every consumer.
  • alias_mapping — resolves variant names, legacy codes, and known duplicates back to the one canonical entry.

It does not govern the entity's changing attributes or state (that is System-of-Record Designation), merge conflicting *records of an entity into a consolidated view (that is Golden Record Consolidation), or propagate the list into dependent systems (that is Synchronization Job).*

  • Instantiates: Source-of-Truth Assignment — it supplies the authoritative identity layer the other mechanisms attach state and rules to.
  • Consumes: Golden Record Consolidation often relies on canonical identifiers to recognize which records describe the same entity.
  • Sibling mechanisms: Golden Record Consolidation · Master Data Management · System-of-Record Designation · Authoritative Policy Repository · Official Record Policy · Deprecation and Forwarding Notice · Synchronization Job · Conflict Resolution Workflow · Change Log and Audit Trail · Access and Update Rights Matrix · Source-Control Main Branch

Notes

A canonical registry answers "which entity is this?"; Golden Record Consolidation answers "what is the consolidated truth about it?". They pair naturally — the registry's identifiers are exactly what consolidation uses to cluster duplicate records — but conflating them leaves either identities without agreed attributes or attributes with no stable identity to hang on.