Codelists & Controlled Terminology

Why this matters

If five vendors send five different ways of saying the same thing—Male, M, male, 1, MALE—you spend weeks recoding and reconciling. Every unstandardized value multiplies downstream effort (extract‑transform‑load (ETL) programs, listings, SDTM/ADaM mapping) and risks analysis errors. Controlled terminology fixes this at the source: you define the allowed answers once, version them, and require every system and vendor to map to those lists. The payoff is cleaner data entry, faster integrations, fewer queries, and easier cross‑trial comparisons.

Core concepts & definitions

• Codelist (controlled terminology): A pre‑defined, versioned list of allowed values for a field. Each entry has a code (what the database stores) and a decode/label (human‑readable). Example: CL_SEX v1.0 with codes M, F, U (labels: Male, Female, Unknown).

• Sponsor standard vs. external dictionaries:

  • Sponsor standard codelists cover common fields across studies (e.g., sex, race, visit type, disposition, completion status, units). Where CDISC Controlled Terminology has a codelist for the field, the sponsor list uses or maps to its terms; CDISC marks each codelist extensible (terms not already covered may be added) or non‑extensible.
  • External dictionaries (e.g., MedDRA for adverse events (AEs) and medical history, WHODrug for medications) are separate: outside organizations maintain them, and the sponsor picks the version but cannot add or change terms. Versioning and governance apply in the same way.

• Map table (value translation): A table that translates source values (from sites, devices, labs) to sponsor codes. Map tables sit in the vendor’s data transfer specification (“transfer spec”) and are under change control. A mapping is one‑to‑one when each source value has its own sponsor code (Male → M) and many‑to‑one when several share one (SOD, Sodium → NA); a source value that could mean two codes goes back to the vendor.

• Value‑level metadata: Extra rules tied to specific values—e.g., if TEST = Sodium then allowed UNIT = mmol/L and expected range is defined.

• Effective dating: Every codelist version and mapping has a clear “effective from” date (and, if retired, an “effective to” date) so you can audit what was valid when.

• “Other—specify” pattern: A controlled value OTHER plus a paired free‑text field for specifics. This preserves structure while allowing rare cases.

• Null semantics: Distinguish UNKNOWN, NOT DONE, NOT APPLICABLE, and actual missing values. The first three are separate codes—never lump them together; a blank (missing) field has no code and is queried, not auto‑filled.

The process, step‑by‑step

1. Design the sponsor library

   • Identify common fields (sex, race, visit status, disposition, protocol deviations, units, test codes).
   • For each: define code, label, definition, status (active/retired), and version (MAJOR.MINOR, e.g., v2.1).
   • Document null semantics (U, ND, NA) and when each is appropriate. Codes are scoped by codelist: NA is Not Applicable here, sodium in Example 1’s test list.

2. Publish + register

   • Store in a central terminology service or a simple source‑controlled table (even a spreadsheet under change control) with effective dates.
   • Assign stable IDs (e.g., CL_SEX, CL_UNIT_CHEM, CL_VISITTYPE) so CRFs, edit checks, and ETL can reference them.

3. Bake into design

   • CRFs/EDC: Use dropdowns/radios limited to the codelist. Enable OTHER—specify only if justified.
   • Edit checks: Reject any value not on the list; ensure OTHER requires text; validate null codes are used correctly.
   • Value‑level rules: Tie fields together (e.g., TEST "Sodium" → allowed UNIT "mmol/L").

4. Vendor alignment (before first file/first patient)

   • In the transfer spec, add a Mapping Annex for every coded field: Source Value → Sponsor Code.
   • Provide example payloads and run a documented test transfer (a small test file checked against the spec) to prove mappings work end‑to‑end; sponsor and vendor approve the spec before the first production file.

5. Monitor & alert

   • In ingestion, log all distinct incoming values for mapped fields.
   • Alert when an unmapped value appears (e.g., new device firmware introduces Nonbinary for sex). Never guess a code: route the value through change control.

6. Govern changes

   • If a new value is approved (e.g., I for “Intersex” in the sex list), release a new version (CL_SEX v1.1), update and test CRFs and mappings, and communicate the go‑live date. By a common convention an added value is a minor version; a retired or renamed one is major (v2.0).
   • Keep an audit trail: who proposed and who approved the change, rationale, impacted studies, effective dates, back‑mapping or migration approach.

7. Cross‑study reuse

   • Reuse the same codelist IDs across studies. If a study needs a special value, consider whether it belongs in the global list or a study‑local extension (still versioned). A study‑local value still maps to a global one, so pooled data stay comparable.

What good looks like

• A master codelist library (IDs, versions, effective dates, definitions) referenced by CRFs, edit checks, and ETL.
• Transfer specs with Mapping Annexes, example files, and pass/fail criteria.
• Automated monitors that flag unmapped values within an agreed time (e.g., 24 hours of arrival).
• Consistent null semantics across all studies (e.g., U=Unknown, ND=Not Done, NA=Not Applicable).
• A simple, documented change‑control workflow (request → impact assessment → approval → release notes → effective date).
• Value‑level constraints linking tests to allowed units and conversions (or explicit statement that conversions are not performed).

Worked examples

Self‑contained scenarios you can copy into a study playbook.

Example 1 — Normalizing lab electrolytes

Goal: Ensure sodium results land with a consistent code and unit.

Inputs (from central lab):

• Analyte Name: SOD, NA, Sodium
• Unit: mmol/L, mEq/L

Sponsor standard:

• Codelist CL_TEST_CHEM v1.3: NA (label: Sodium)
• Codelist CL_UNIT_CHEM v2.0: mmol/L (canonical)

Map table (transfer spec annex):

Checks:

• Hold any record with an unrecognized analyte in the Unmapped Value Queue (quarantine): it is not loaded, discarded, or guessed.
• Convert mEq/L → mmol/L only for monovalent electrolytes (Na, K, Cl). For a divalent ion such as calcium, 2 mEq/L = 1 mmol/L.
• Emit an alert if a new unit appears.

Outcome: Analytics receive TEST=NA, UNIT=mmol/L consistently. The lab’s original name, result, and unit are kept beside the mapped ones for traceability.

Example 2 — Device sex field harmonization

Inputs (from wearable vendor): Male, Female, Unk

Sponsor codelist CL_SEX v1.0: M, F, U

Map table:

Rule: If source sends a value not in the table (e.g., Nonbinary), hold the record in the quarantine queue, notify data management (DM) and the codelist’s owner, and start change control. Nobody edits the received value or guesses a code. Decision options:

• Decide first what the value means: “Nonbinary” is a gender identity, not a sex, so it gets no CL_SEX code; the vendor clarifies and re‑sends the sex value, and gender identity, if the study collects it, goes in a separate field with its own codelist; or
• If a value does belong to the list’s concept, add it with a definition in a new CL_SEX version (v1.1) and update the map table.

Example 3 — Null semantics in visit disposition

Codelist CL_DISP v3.2: COMPL (Completed), WD (Withdrawn), EOS (End of Study), ND (Not Done), U (Unknown)

Scenario: Site leaves disposition blank.

Preferred handling: Do not auto‑fill. Trigger a query. The site answers the query and enters the value itself: ND if the visit did not happen, U only if the status truly cannot be established. DM never fills in the field, and no placeholder is entered: it stays blank with the query open until the site answers.

Reason: ND ≠ missing ≠ U. Each means something different in analysis.

Pitfalls & misconceptions

• “We’ll fix it in ETL.” Late recoding is slow, error‑prone, and often diverges by study. Put mappings in the transfer spec and enforce at ingestion.
• Silent changes. Adding or renaming a value without a version bump breaks traceability. Always version and document. Never delete a value or reuse its code for a new meaning: retire it, so existing data keep their meaning.
• Overusing “Other—specify.” As a rule of thumb (not a standard), more than about 5–10% OTHER suggests the codelist is incomplete: review the specify texts and add recurring answers through change control.
• Ignoring null semantics. Unknown, Not Done, and Not Applicable must be different codes.
• Unit chaos. Allowing multiple units without conversion rules leads to bad analyses. Choose a canonical unit or define safe conversions.
• Case/whitespace drift. male, Male, MALE—treat them as the same via trim/upper during ingestion (a rule written in the transfer spec) and load the sponsor code; the file stays archived as received, so the source value stays traceable.
• Mid‑study switch without migration plan. When moving from v1 to v2, specify: effective date, whether to back‑map historicals, and how listings flag the mix. Collected values are never rewritten by hand: back‑mapping is a documented, validated step that keeps the original value and its audit trail; where the new code needs judgement (e.g., an OTHER text that now has its own code), DM queries and the site re‑enters the value.

Practice in the wild (checklist)

• A master codelist library exists with IDs, versions, definitions, and effective dates.
• CRFs use controlled fields; OTHER—specify is rare and justified.
• Transfer specs include mapping tables and example payloads that pass validation.
• Ingestion monitors alert on unmapped values within the agreed time (e.g., 24 hours).
• Null semantics (U, ND, NA) are defined and used consistently.
• Units have a canonical choice; any conversions are documented and validated.
• Change control covers requests, approvals, release notes, and communication to sites/vendors.
• Audit trail shows who changed what, when, and why—per list and per mapping.
• Cross‑study reuse: same codelist IDs used across studies; study‑local extensions are versioned.
• Metrics tracked monthly: % unmapped values, time‑to‑map, OTHER usage rate.

Key points to remember

• What it is: A codelist is a versioned set of allowed values (code + label + definition); controlled terminology is using those codelists consistently across systems and studies.
• Align early: Agree sponsor codelists and vendor mappings before first patient/first file.
• Where mappings live: Keep vendor→sponsor map tables in the transfer spec (Mapping Annex), not buried in ad‑hoc ETL.
• Design & enforcement: Build codelists into CRFs/EDC and block off‑list entries at ingestion; allow OTHER—specify only when justified and auditable.
• Versioning & effective dating: Maintain versions with release notes and clear effective‑from (and, if retired, effective‑to) dates.
• Governance & change control: Route additions/changes through justification, impact assessment, approval, version bump, effective date, and communication.
• Null semantics: Give Unknown, Not Done, and Not Applicable distinct codes; a blank (true missing) field is none of them: DM queries it and the site enters the answer.
• Units: Choose a canonical unit per analyte and define explicit, validated conversion rules—or prohibit conversion.
• Value‑level metadata: Certain values constrain other fields (e.g., test → allowed unit/range); encode and validate these rules.
• Monitoring: Log distinct incoming values; alert on unmapped/unexpected and handle via incident/change‑control.
• Cross‑study reuse: Reuse global lists for comparability; if a study needs extras, use versioned study‑local extensions.
• Auditability: Be able to show which codelist version was effective on a given date, where the vendor mapping is maintained and approved, and how unmapped values are detected and resolved.
• Keep it tight: Prefer small, clear, well‑defined code sets over sprawling lists.