Why the spreadsheet works until it doesn't
Almost every integration starts the same way. Someone exports a list of codes, pastes it into a mapping file, and wires it into the transformation. It is fast, it is legible, and for a single interface with a stable code list it is genuinely adequate.
The failure is not dramatic. Nothing crashes. What happens is that the national release moves on, the local list does not, and for some months the integration quietly maps a handful of codes to concepts that have been deprecated or redefined. The discovery usually arrives through a report that does not reconcile, at which point the question is not just what went wrong but how far back it goes and which downstream records are affected.
That is the real cost of holding terminology as data in a file: not that it is wrong, but that nothing in the system is responsible for noticing when it becomes wrong. Terminology 101 covers the vocabulary; this piece is about what changes operationally when terminology becomes a service instead of a file.
The four questions a lookup table cannot answer
A table maps a code to a display string. That answers one question. Integrations routinely need four.
Is this code valid in this context? Not whether the string exists somewhere, but whether it is a permitted value for this specific field in this specific message, right now. A table has no concept of context.
What does it actually mean? Properties, designations, the definition, the hierarchy it sits in. A display string is a label, not a meaning, and two systems can agree on a label while disagreeing about what it covers.
What does it map to? The equivalent concept in another system, with the relationship stated rather than assumed. Equivalence and rough correspondence are not the same thing, and a table cannot express the difference.
Which version am I asking about? This is the one that produces the silent failures. A code's meaning is only well defined relative to a release. A table has no version, so every question asked of it is implicitly a question about whenever the file was last edited.
What a terminology server actually does
A terminology server holds code systems, value sets and concept maps, and exposes operations over them through a standard API rather than a file format.
In a FHIR context those operations are defined by the specification rather than invented per vendor, which matters because it means your integrations are not coupled to one implementation. The terminology module sets out the full set. The ones an integration actually uses day to day are narrower:
- $lookup returns what a code means, with its properties and designations.
- $validate-code answers whether a code is permitted in a given value set. This is the one that belongs in flight.
- $expand resolves a value set's rules into the concrete list of codes it currently contains.
- $translate applies a concept map to convert between systems.
- $subsumes answers whether one concept sits above another in the hierarchy, which is how you ask questions about categories rather than individual codes.
WeHub Term hosts the official releases, pulled from the publisher, validated and versioned on the way in, so SNOMED CT, ICD-10 and LOINC are current without anyone maintaining an import process. Every capability it supports is declared in a live CapabilityStatement, which means the honest answer to "does it support X" is something you can check rather than something you have to be told.
Value sets, concept maps and the difference between them
These two get conflated constantly, and the distinction is practical rather than academic.
A value set is the governed shortlist of codes permitted in one particular context. The important property is that it can be defined by rule rather than by enumeration: all descendants of a given concept, everything in a code system with a given property. Defined that way, the value set stays accurate as the underlying terminology changes, because the rule is re-resolved rather than the list being re-typed. That resolution is what $expand returns.
A concept map is the translation between two shortlists. It exists because two systems were designed separately and have to interoperate anyway. The value of stating the map explicitly, with its relationship types, is that the assumptions become reviewable by someone with clinical coding knowledge rather than buried in a transformation.
Both need SNOMED CT and the other national releases underneath them to be current, which is the argument for hosting rather than importing.
Local codes are the normal case, not the exception
There is a tendency to treat local code systems as technical debt to be eliminated. In a real estate they are permanent. Departments have lists that predate the national standards, pathways have categories no standard covers, and services need to record things the published terminology has no concept for.
The useful position is not to eliminate them but to govern them identically: local and custom code systems authored and versioned with the same tools, the same validation and the same canonical URLs as the official releases. A local code that is versioned, validated and mapped is not a problem. An unversioned list in a spreadsheet is a problem regardless of whether its codes are local or national.
This is also what makes the drift described in SNOMED CT explained tractable. Drift is only invisible when nothing is tracking versions.
Validating in flight rather than reconciling later
The operational change worth the effort is where validation happens.
In the common pattern, terminology is checked after the fact: a report is run, it does not reconcile, someone traces the discrepancy back to a code. The data is already in live systems by then, and correcting it means finding every record affected.
The alternative is to validate in flight. The integration calls $validate-code as a step in the workflow, and a message carrying an invalid or deprecated code is rejected at the point of entry, to a named human, with the reason attached. This is the same pre-flight principle applied to terminology specifically, and it composes naturally with the flow structure described in the anatomy of a healthcare integration workflow.
The trade is real and worth stating: validating in flight means some messages that would previously have landed now get rejected. That is the point. A rejection is a question someone can answer this morning. A silently mis-mapped code is a data quality investigation six months from now.
