Reference data at a glance
The pieces
| Piece | Is |
|---|---|
| Lookup type | One controlled list |
| Lookup value | One entry: a stable code and a readable label |
| Transcode map | Turns a source system's code into the canonical one |
| Hierarchy | A levelled classification for rollup |
Code versus label
| Stored | Changeable | |
|---|---|---|
| Code | Yes — on every record | No — changing it orphans stored data |
| Label | No — resolved when reading | Yes, freely |
This separation is why relabelling a value in the interface does not rewrite a single record.
The one confusion worth pre-empting
| Concept | Links | Called |
|---|---|---|
| A record → a source system's identifier for it | Records | Crosswalk |
| A source system's code value → the canonical one | Values | Transcoding |
Some platforms use "crosswalk" for the second. This documentation reserves it strictly for the first.
Why transcoding comes before loading
A code that does not resolve against its lookup type is rejected on write.
The record does not land carrying a bad value — the load fails. So a source
sending USA where the lookup holds US costs you a failed load, not a
quietly mis-scored match.
Transcoding is what turns that rejection into a successful load, by mapping the source's code to the canonical one first.
The source-system mapping is consulted when a record is created or patched one at a time and the caller identified its source system. A bulk load resolves codes strictly and directly, so translate values before submitting them.
Retire, do not delete
A value in use keeps resolving on historical records after retirement. Deleting it leaves those records displaying a bare code — the records are not wrong, the vocabulary is now incomplete.
Two things both called hierarchy
| Concept | Is | Used for |
|---|---|---|
| Value tree | A value referencing a parent value | Constraining permitted values |
| Levelled hierarchy | A named structure with ordered levels | Classification and rollup |
Both are legitimate; they answer different questions.
Next
Last verified against commit 1e1de1ad (2026-08-03)