Reference data and code lists: keeping shared values consistent

Reference article · 7 min read

Every agency runs on small lists of allowed values. Finance has fund codes and object codes. Permitting has land use categories and application statuses. A court or prosecutor system has case types and charge codes. A service request portal has categories the public picks from. These lists are short, they change slowly, and in many agencies nobody is formally responsible for them. That combination is why the same word means different things in different systems, and why a report that joins two systems produces a number nobody can defend in a budget hearing.

The work of fixing this is not technically hard. It is mostly a matter of naming an owner for each list, writing down what each value means, changing values in a controlled way with effective dates, and giving every consuming system one place to get the current list. What follows is a practical approach agency staff can apply without waiting for a large data governance program.

Reference data is not master data

The two are often lumped together, but they need different handling.

• Reference data is a controlled list of permitted values used to classify or describe something: department codes, fund codes, case types, offense codes, land use categories, permit statuses, disposition codes. The list is small, shared across systems, and changes because someone makes a policy decision.
• Master data is the record of an actual entity: the vendor, the parcel, the employee, the person, the asset. It changes because something happened in the real world, and the hard problems are matching, merging, and deciding which source wins.

Master data governance is about identity resolution. Reference data governance is about meaning: who may add a value, what it means, when it takes effect, and how every system that uses it finds out. Treating a code list like master data leads to overbuilt tooling. Treating it like a configuration screen leads to drift.

Write down what each value means

A code list that exists only as dropdown options in an admin screen is not documented. For each list, keep a record with at least these fields for every value: the code, the display label, a one or two sentence definition with an example of what belongs and what does not, the owner, the status (active or retired), the effective start date, the effective end date if retired, and the successor value if there is one.

Two habits prevent most future pain. Keep codes short, stable, and free of embedded meaning, because a code like a department abbreviation becomes wrong the moment a department is renamed or reorganized. Never reuse a retired code for a new meaning, since historical records still carry it.

Assign an owner, and know which lists are not yours

The owner of a list should be the program office that sets the underlying policy, not the IT department. The budget office owns fund and object codes. The clerk or court administrator owns case types. Planning owns land use categories. IT is the steward: it maintains the register, publishes the list, and enforces the process, but it does not decide what a category means.

Publish a single register of lists that records, for each one, the owner, where the authoritative copy lives, which systems consume it, and how to request a change. Then define the change process: who may request, who approves, and what notice is given.

Some lists are not the agency's to define. Offense and incident classifications used for state and national crime reporting, education data elements reported to a state department of education, road classifications used in federal highway reporting, and many grant reporting categories are set by an external program. Those definitions and submission requirements change over time, so confirm the current version with the official source or program office rather than relying on what a system was configured with years ago.

Version changes with effective dates

The most common failure is editing a value in place. Someone renames a category, and every historical record silently reclassifies, so last year's report no longer matches last year's published number.

• Retire, do not delete. Set an end date and mark the value inactive so it cannot be selected on new records while remaining valid on old ones.
• Add effective dates to every value. Systems and reports should select values valid as of the transaction date, not as of today.
• Separate a correction from a change. Fixing a typo in a label is a correction. Splitting one category into two is a change and needs a mapping from the old value to the new ones.
• Keep a changelog. Record what changed, who approved it, when it takes effect, and why. This is what lets an analyst explain a break in a trend line.

Distribute updates from one source

Decide where the authoritative copy lives, then make it easy to consume. Publish the list through an API and as a plain file export from the same place, so systems that can call a service and systems that can only ingest a file both work from the same source. Announce changes before the effective date, with enough lead time for vendors and integration owners to act.

Have each consuming system record which version of the list it holds, and run a periodic reconciliation that compares each copy against the source and reports differences. For a hosted product that genuinely cannot consume a feed, document the manual update procedure, assign it to a named role, and let the reconciliation report catch what gets missed. Where a system cannot adopt the shared list at all, build an explicit crosswalk table and own it like any other list, rather than letting a translation live inside one report query.

What to ask vendors and put in the contract

Questions for a demonstration or a written response:

• Can code lists be imported from an external source, or must values be entered by hand?
• Are effective dates supported on values, and can a value be retired without altering historical records?
• Is each list available through an API or scheduled export in a nonproprietary format?
• Which lists are system defined and cannot be changed by the agency, and what happens to them during an upgrade?
• Are any values hard coded in reports, workflow rules, or interfaces?

Contract terms worth requiring: a current data dictionary of every code list delivered at implementation and maintained through the life of the agreement, agency ownership of the values and definitions, export of all lists on request and at termination, advance notice before a vendor changes a system defined list, and clarity on whether routine list changes are configuration the agency can perform or billable services.

How to start

Pick three systems that feed one shared report. Inventory their lookup lists and put them side by side. Look for the same label meaning different things, different labels meaning the same thing, and values that exist in one system with no counterpart in another. Choose the single list causing the most rework, name its owner, write the definitions, publish it in one place with effective dates and a changelog, and point the systems at it. Then carry the requirements into the next procurement so the next system inherits the discipline instead of adding another private copy.

HQT works with state and local government agencies on data architecture, system integration, and the governance practices that keep shared values consistent across applications.

Frequently asked questions