Code lists
Code lists map synonyms to one canonical code (states, leave types, drug and procedure codes) for hand-off contracts and document scope, with examples, edge cases and the exact format.
Your states, leave types or formulary codes compare as one value however they are written, in hand-offs and document scope.
What it is and what it powers
A code list is a named list of codes, each with its synonyms. It powers two checks:
- Hand-offs carry the facts: a hand-off field of type
codenames a list. The value sent must be a code or synonym of that list, and "short-term disability" sent where the intake agent had "STD" is the same fact. - Right version of the source: the
jurisdictionandproductscope dimensions (and your own text dimensions) compare values after the list. A question about "New Jersey" matches a document scopedUS-NJ.
When it's not set. A contract's code field cannot be saved without its list. A scope dimension without a list compares values as written (ignoring case and spacing), and a mismatch is only a warning: "no code list is declared for jurisdiction, so its values were compared as written; declare one (code_lists, and the dimension's code_list)".

Use cases
Insurance: states and leave types
Leave rules differ by state, and an intake agent writes leave types in words while the adjudication system uses codes.
evaluation_config:
code_lists:
jurisdiction:
US-NJ: ["New Jersey", "NJ"]
US-NY: ["New York", "NY"]
US-CA: ["California", "CA"]
leave_type:
STD: ["short-term disability", "short term disability"]
LTD: ["long-term disability", "long term disability"]
FMLA: ["Family and Medical Leave", "family medical leave"]
PFL: ["paid family leave"]
- A hand-off that sends
leave_type: "short-term disability"where the intake agent's evidence had "STD" passes: both areSTD. - One that sends
"LTD"where the intake agent had "short-term disability" fails as changed. - One that sends
"sick leave"fails as invalid: "which is not a code in leave_type". - A question about "NY paid family leave" answered from the document scoped
US-NJfails Right version of the source when both sides were stated as metadata.
Healthcare: formulary and procedure codes
evaluation_config:
code_lists:
formulary_drug:
RX-0042: ["metformin", "Glucophage"]
RX-0108: ["atorvastatin", "Lipitor"]
procedure:
"99213": ["office visit, established patient, level 3"]
"93000": ["electrocardiogram", "ECG", "EKG"]
A hand-off field {"name": "drugs", "type": "code", "code_list": "formulary_drug", "list": true} accepts "Glucophage" or "RX-0042" for the same drug and refuses a drug that is not on the formulary. Quote numeric codes in YAML ("99213") so they stay text.
Other domains
- Legal: a
jurisdictionlist with "England and Wales", "E&W" →GB-EAW, used by document scope. - Products and plans: a
productlist ("Gold PPO", "PPO Gold" →GOLD-PPO) so a plan's documents match questions however the plan is named. - Finance: cost centres or entity codes in a hand-off between a reconciliation agent and an approval agent.
Edge cases
| Situation | What happens |
|---|---|
| Different case ("new jersey", "NEW JERSEY") | The same code: codes and synonyms match without case. |
| A short term in free text ("NJ", "in") | Terms of three letters or fewer match free text only as written, so the word "in" is never Indiana's "IN". |
| The same synonym under two codes | Refused when saved: Code list "jurisdiction": "Georgia" maps to both "US-GA" and "GE". Use two lists, or qualify the synonym. |
| A value not in the list, sent in a hand-off | The field is invalid ("which is not a code in leave_type"), a failure. |
A value not in the list, in reference metadata or question_scope | Refused when the answer is sent: jurisdiction: "Narnia" is not in the jurisdiction code list. |
* or ALL | Means every value, for example a document that applies in every state. |
An ISO 3166 code your jurisdiction list leaves out (US) | Accepted for jurisdiction; a country covers its subdivisions (US covers US-NJ). |
| Different dashes ("Aetna Select – HMO" vs "Aetna Select - HMO") | Any dash matches any dash. |
| A list a saved contract uses, removed | Refused: "the saved hand-off contracts would no longer be valid: …". Change the contract first. |
How to add it
In the app
- Open Evaluation policy › Advanced settings ▸ › Data definitions › Code lists.
- Click Add list. Enter the Name (lower case, for example
leave_type) and the Codes, one per line, synonyms after a colon:STD: short-term disability, short term disability LTD: long-term disability FMLA - Click Add. The table shows the list and Used by (the contract fields and scope dimensions that use it).
- Or click Import CSV and choose a file of rows
list,code,synonym,synonym…. A header row starting with "list" is skipped; a list with the same name as an existing one is replaced.list,code,synonym,synonym leave_type,STD,short-term disability,short term disability leave_type,LTD,long-term disability jurisdiction,US-NJ,New Jersey,NJ - Publish the draft: Publish vN… › Publish.
In YAML
evaluation_config:
code_lists:
leave_type:
STD: ["short-term disability"]
LTD: []
A code with no synonyms takes an empty list [].
From the SDK
client.set_code_lists(pid, {
"leave_type": {"STD": ["short-term disability"], "LTD": ["long-term disability"]},
"jurisdiction": {"US-NJ": ["New Jersey", "NJ"], "US-NY": ["New York", "NY"]},
}, note="leave types for the 2026 plan year")
The call replaces all code lists with the value you send; {} removes them (refused while a contract uses one).
Paste this into your coding agent
Paste this into Claude Code, Cursor, or whichever agent has your repository open. It writes the lists from your enums and reference tables and checks them with variably policy validate.
Write variA/Bly code lists for this project from the vocabularies already in this repository.
A code list maps each canonical code to the ways people write it, so "short-term disability" and
"STD" read as the same value in hand-off and document-scope checks.
Look first:
1. Find the fixed vocabularies in the code and data: enums, constants, lookup or reference
tables (migrations, seed files, fixtures, CSVs), and label maps used in the UI. List each
with its file path, and ask me which ones to include before you write anything.
Then write them under evaluation_config.code_lists, one list per vocabulary:
evaluation_config:
code_lists:
leave_type:
STD: ["short-term disability"]
LTD: ["long-term disability"]
- The key is the canonical code exactly as the code stores it. Quote numeric codes ("99213")
so they stay text.
- The synonyms are the labels, abbreviations and spellings found in this repository. Do not
invent synonyms that are not in the code or data.
- One synonym must not appear under two codes of the same list.
- The format is described at https://www.variably.dev/docs/data-code-lists.
How to write it, as policy YAML:
1. The variably command comes with the SDK (pip install variably-sdk). It reads
VARIABLY_API_KEY and VARIABLY_BASE_URL from the environment; never hard-code the key or write it into a file.
2. If variably-policy.yaml is not in the repository yet, run `variably policy pull`: it writes
the version in force to variably-policy.yaml. Change only evaluation_config.code_lists in that
file and leave every other key exactly as it is.
3. Verify: run `variably policy validate variably-policy.yaml`. It checks the file as the server would
and saves nothing; each problem is printed as "line N: path: message". Fix every problem and
run it again until it exits 0. Do not guess a key the error does not name: unknown keys are
refused.
4. Run `variably policy diff variably-policy.yaml` and show me what would change.
5. Do not push or publish. Tell me the two ways to save it as a draft: paste the file into
Evaluation policy › YAML and click Apply as draft, or run
`variably policy push variably-policy.yaml --note "<why>"` with a key allowed to change the
evaluation policy. A draft scores nothing until it is published.
When you are done, tell me each list you wrote, where its codes came from, and anything you left
out and why.Common mistakes
| Mistake | What happens | Fix |
|---|---|---|
Numeric codes left unquoted in YAML (99213:) | YAML reads them as numbers; the key is refused with "quote it" | Quote them: "99213": |
| One list for two vocabularies (states and countries together) | A synonym clashes, and the save is refused | One list per vocabulary |
| Adding a code list and expecting a check on its own | Nothing changes: a list is used by hand-off contracts and document scope | Reference the list from a code field or a scope dimension |
| Saving, but not publishing | Answers are still checked with the old lists | Publish the draft |
Format reference
code_lists is an object: list name → (code → list of synonyms).
| Field | Type | Required | Allowed values | Default | Meaning |
|---|---|---|---|---|---|
| list name (key) | text | yes | lower case: a letter, then letters, digits or _; up to 64 characters | none | The name a contract field (code_list) or a scope dimension names |
| code (key) | text | at least one per list | any non-empty text | none | The canonical value checks report |
| synonyms | list of text | yes (may be []) | up to 50 non-empty values | none | Other ways the code is written |
Limits: 50 lists, 5,000 codes per list, 50 synonyms per code.
Minimal:
code_lists:
leave_type:
STD: []
Full:
code_lists:
jurisdiction:
US-NJ: ["New Jersey", "NJ"]
US-NY: ["New York", "NY"]
leave_type:
STD: ["short-term disability", "short term disability"]
LTD: ["long-term disability"]
product:
GOLD-PPO: ["Gold PPO", "PPO Gold"]
Validation messages
| Problem | Message |
|---|---|
| Not an object | code_lists must be an object of lists. |
| Bad list name | Code list "Leave Types": names are lower-case identifiers (letters, digits, _). |
| Empty list | Code list "leave_type" must be a non-empty object of code -> synonyms. |
| Synonyms not a list | Code list "leave_type", code "STD": synonyms must be a list of at most 50 text values. |
| Empty synonym | Code list "leave_type", code "STD": synonyms must be non-empty text. |
| One term, two codes | Code list "leave_type": "disability" maps to both "STD" and "LTD". |
| Too many | 51 code lists; at most 50. / Code list "icd10": 5001 codes; at most 5000. |
Concepts on this page: Data definitions