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-01with EN label EU Central (Germany) and metadata{ "country": "DE", "status": "available" }
eu-01 without per-account rows.
Effective resolution algorithm
- Resolve codelist: system list by code if present; else account-owned private list.
- Candidate values: active system values + active account extensions when
is_extensible. - Apply account overrides (drop hidden; apply sort/default/metadata).
- Resolve labels via language fallback.
- Return ordered DTOs for pickers and validation.
code as a system list is rejected).
API overview
Effective values example
Hide a value for one account
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