Manage lookup types and values
Before you start
rdm.lookup-type.create and rdm.lookup-value.create to build a list,
rdm.transcode-map.create to map source codes onto it, and the matching
.update codes to change them later.
1. Create the lookup type
Creating a lookup type. A draft list can be built up before anything binds to it.
Name the list for the concept it controls, not for where it is first used.
country outlives customer_country, and one list serves every attribute that
needs countries.
2. Add values
A lookup type's values. The code is what records store and cannot be edited; the label can.
Each value has a code and a label.
| Purpose | Changeable | |
|---|---|---|
| Code | Stored on records; stable identifier | No — changing it orphans stored data |
| Label | What people read | Yes, freely |
Choose codes from a standard where one exists. Inventing codes for countries or currencies creates a mapping problem for every integration that follows.
3. Bind attributes to it
An attribute bound to a lookup type accepts only its codes. The platform resolves codes to labels when reading, so every consumer displays the same thing.
Search accounts for this: searching a bound attribute matches the resolved label as well as the stored code, so a person can be found by the name of their municipality rather than by its number.
4. Map source codes
Where sources use their own codes, add transcode mappings so each becomes the canonical value on the way in.
Do this before loading. Without it, matching sees one source's US and
another's USA as a disagreement, and scores two records of the same person as
evidence against a match.
5. Retire a value
Do not delete a value that records reference. Retire it instead: it stops being offered for new records while continuing to resolve for existing ones.
Records keep the code. Removing the value it resolves to makes historical records display a bare code where a label used to be — and the records are not wrong, the vocabulary is now incomplete. Retirement exists precisely for this.
6. Verify
- A record can be created with a valid code, and rejected with an invalid one.
- Reading it returns the resolved label.
- A source code arrives and is stored as its canonical equivalent.
- A retired value still resolves on an existing record.
Next
Last verified against commit a0765982 (2026-08-03)