practice

Code List Governance

Managing the small shared enumerations — currencies, country codes, statuses, product categories — whose uncontrolled change breaks systems quietly.

Reference data is unglamorous, tiny, and disproportionately dangerous. A new status value added to a source system's enumeration propagates into pipelines that have a CASE statement covering the old values and a fallthrough that silently buckets the new one as "other". Nothing errors; a category simply starts under-reporting.

The controls are proportionate to the size of the problem, which is small. Reference data is versioned with effective dates, so historical facts resolve against the codes in force when they occurred rather than against today's list. Changes go through a review, because adding a value is an interface change for every consumer. Pipelines assert on the known set and fail on an unrecognised value rather than defaulting it — which converts a silent misclassification into a loud, fixable error.

The mapping problem is the other half. Each source has its own codes, and the mapping to the canonical set has to live somewhere versioned and owned rather than inline in a transformation, where it becomes invisible business logic that only one person understands.