All docs
Evaluation policyData definitionsCode listsdashboard

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.

What you'll have

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 code names 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 jurisdiction and product scope dimensions (and your own text dimensions) compare values after the list. A question about "New Jersey" matches a document scoped US-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)".

Data definitions: Code listsData definitions: Code lists

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 are STD.
  • 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-NJ fails 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 jurisdiction list with "England and Wales", "E&W" → GB-EAW, used by document scope.
  • Products and plans: a product list ("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

SituationWhat 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 codesRefused 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-offThe field is invalid ("which is not a code in leave_type"), a failure.
A value not in the list, in reference metadata or question_scopeRefused when the answer is sent: jurisdiction: "Narnia" is not in the jurisdiction code list.
* or ALLMeans 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, removedRefused: "the saved hand-off contracts would no longer be valid: …". Change the contract first.

How to add it

In the app

  1. Open Evaluation policy › Advanced settings ▸ › Data definitions › Code lists.
  2. 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
    
  3. Click Add. The table shows the list and Used by (the contract fields and scope dimensions that use it).
  4. 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
    
  5. 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.

Prompt for your coding agent
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

MistakeWhat happensFix
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 refusedOne list per vocabulary
Adding a code list and expecting a check on its ownNothing changes: a list is used by hand-off contracts and document scopeReference the list from a code field or a scope dimension
Saving, but not publishingAnswers are still checked with the old listsPublish the draft

Format reference

code_lists is an object: list name → (code → list of synonyms).

FieldTypeRequiredAllowed valuesDefaultMeaning
list name (key)textyeslower case: a letter, then letters, digits or _; up to 64 charactersnoneThe name a contract field (code_list) or a scope dimension names
code (key)textat least one per listany non-empty textnoneThe canonical value checks report
synonymslist of textyes (may be [])up to 50 non-empty valuesnoneOther 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

ProblemMessage
Not an objectcode_lists must be an object of lists.
Bad list nameCode list "Leave Types": names are lower-case identifiers (letters, digits, _).
Empty listCode list "leave_type" must be a non-empty object of code -> synonyms.
Synonyms not a listCode list "leave_type", code "STD": synonyms must be a list of at most 50 text values.
Empty synonymCode list "leave_type", code "STD": synonyms must be non-empty text.
One term, two codesCode list "leave_type": "disability" maps to both "STD" and "LTD".
Too many51 code lists; at most 50. / Code list "icd10": 5001 codes; at most 5000.

Concepts on this page: Data definitions