Skip to main content

Codelists

Codelists are first-class shared reference dictionaries in SnackBase. They provide stable submission codes (stored in business data) with labels resolved at read time — inspired by CDISC Controlled Terminology concepts, without being a full regulatory CT engine.

Why codelists exist

Per-tenant collection fan-out for shared dimensions (e.g. cloud regions) does not scale: every new account needed a copy of the catalog, and updates required N writes. Codelists store system dictionaries once and resolve an effective set per account using overrides.

Concepts

Example: a regions catalog (operator-created)

Operators (or product seeds such as control-plane) may create catalogs, for example:
  • Codelist regions (is_builtin=true, is_extensible=false)
  • Value eu-01 with EN label EU Central (Germany) and metadata { "country": "DE", "status": "available" }
Any account’s effective list includes eu-01 without per-account rows.

Effective resolution algorithm

  1. Resolve codelist: system list by code if present; else account-owned private list.
  2. Candidate values: active system values + active account extensions when is_extensible.
  3. Apply account overrides (drop hidden; apply sort/default/metadata).
  4. Resolve labels via language fallback.
  5. Return ordered DTOs for pickers and validation.
Account lists cannot shadow system list codes (same code as a system list is rejected).

API overview

Effective values example

Hide a value for one account

Other accounts still see eu-01. Clearing the override restores visibility.

Authz summary

Unauthenticated access is rejected (401/403).

Error codes (aligned with platform HTTP patterns)

Historical inactive values

Inactive values are excluded from pickers (active=true) but labels remain resolvable via GET /api/v1/codelists/{code}/values/{value_code} for display of historical records. Use assert_in_codelist(..., allow_inactive_existing=True) when editing old data.

Non-goals (v1)

  • Full CDISC CT regulatory engine, context bindings, or version pinning beyond schema hooks (external_code, version)
  • Per-account label overrides
  • Anonymous public codelists
  • Dual source of truth with collection-based region catalogs