Managing reference data
Reference data is the set of controlled vocabularies your governed records are governed against: countries, currencies, status codes, industry classifications. Managing it centrally is what stops the same concept being spelled three ways in three systems.
You may know reference data as lists of values, code lists, or lookups.
The three pieces
The reference data screen, where the controlled vocabularies below are defined and versioned.
| Piece | What it does |
|---|---|
| Lookup type | One controlled list |
| Lookup value | One permitted entry: a stable code and a human-readable label |
| Transcode map | Turns a source system's code into the canonical one |
Codes and labels
A lookup value separates its code from its label. The code is stable and is what gets stored; the label is what people read and can be translated or reworded without touching stored data.
This separation is why renaming a country in the interface does not rewrite every record that references it.
Attributes bound to a lookup type accept only its codes. The platform resolves codes to labels when reading, so every consumer displays the same thing.
Transcoding
Source systems disagree about codes. One sends US, another USA, a third
840. Transcoding maps each to a single canonical value on the way in.
A crosswalk links a record to a source system. Transcoding maps a code value to a canonical one. Some platforms use the word "crosswalk" for this second idea — this documentation reserves it strictly for the first.
Without transcoding, matching sees US and USA as a disagreement and scores
two records of the same person as evidence against a match.
Hierarchies
Some reference data is a levelled classification rather than a flat list — an industry taxonomy, a geographic rollup, a product category tree. Hierarchies model those, so entities can be classified at a leaf and aggregated at any level above it.
Two distinct ideas are easy to conflate:
| Concept | What it is |
|---|---|
| Value tree | A lookup value referencing a parent lookup value — a nested list |
| Levelled hierarchy | A named structure with ordered levels that entities are classified into |
Both are legitimate; they answer different questions. A value tree constrains what values are permitted; a levelled hierarchy supports rollup and analysis.
Effective dates
Reference data changes: a country splits, a status code is retired. Lookup values carry effective windows so historical records keep resolving correctly rather than displaying a blank where a retired code used to be.
Advice
- Seed from standards where they exist. ISO country, currency, and language codes are solved problems.
- Bind attributes early. Retrofitting a controlled vocabulary means cleaning every existing value.
- Transcode at the boundary. Map on the way in, so everything downstream sees one vocabulary.
- Retire rather than delete. A code in use by historical records must keep resolving.
Next
Last verified against commit 315eb047 (2026-08-03)