Behavioral health teams building HL7v2-to-FHIR pipelines hit the same fork sooner or later. The lab feed is sending local codes for PHQ-9 totals, the EHR is sending DSM-5 codes the billing system wants as ICD-10, and the screening tool is sending its own internal IDs. Two reasonable answers exist. Model the relationships as FHIR ConceptMap resources on a terminology server, or keep a custom code table inside the pipeline and translate during the write. Both work in 2026. The picking signal depends on who maintains the mapping, how often it changes, and what the audit story has to look like.
For broader framing, more FHIR implementation patterns covers the surrounding catalog. The adjacent procurement question is in hosted vs self-hosted terminology servers for behavioral health practices.
The Short Answer
ConceptMap resources win when a clinical lead has to review the mapping, when more than one downstream system needs the same translation, and when audit reviewers expect a versioned artifact. Custom code tables win when the mapping is small, internal, and tied to one pipeline.
A program with fewer than three engineers, no terminology owner, and a single pipeline is faster shipping a custom code table. A program with a clinical informaticist, multiple consumers, and a payer-review audit calendar needs the ConceptMap.
What Each Approach Gives You
ConceptMap resources live on a terminology server. They are FHIR-native artifacts with versions, group structures, and source-target equivalence indicators. A clinical lead can browse them. A $translate call returns the right code with a confidence indicator. Downstream consumers fetch the same artifact and reuse the translation.
Custom code tables live inside the integration pipeline. They are usually a Postgres table or a JSON file, edited by the pipeline owner, applied during message ingestion. The translation runs in the same process that writes the FHIR resource, so the round-trip is one less network hop.
Where Custom Code Tables Win
Custom code tables win on three things. Speed of iteration, because adding a row is a database write rather than a ConceptMap version bump. Pipeline locality, because the mapping runs inline with the FHIR write. Operational simplicity, because there is one fewer service to keep healthy.
Newer entrants such as Interbox treat local LOINC, SNOMED, and ValueSet mapping inside the pipeline as a first-class concern, with the mapping running during HL7v2 ingestion rather than as a separate $translate lookup. For a small behavioral health program with one pipeline and no shared downstream consumers, this style removes a layer of operational work that would otherwise sit on top of ConceptMap upkeep.
Where ConceptMap Wins
ConceptMap wins when the mapping has to be visible. A clinical lead reviewing the DSM-5-to-ICD-10 translation wants to see groups, equivalence relations, and history. A payer auditor asking how a PHQ-9 score became an Observation expects a versioned artifact, not a database row.
It also wins when the mapping is large. Once a custom code table grows past a few hundred rows, the lack of versioning and review tooling starts to bite.
How to Decide for Your Program
Three honest questions usually settle it:
- Who owns the mapping? A clinical informaticist who needs a review surface tips toward
ConceptMap. An integration engineer tips toward a code table. - How many consumers? One pipeline can use either. Two or more usually push toward
ConceptMap. - What does the audit cycle expect? Payer reviews increasingly ask for
ConceptMap-style artifacts.
The best FHIR terminology servers for trauma-related ICD-10 coding covers the server-side picks. Most behavioral health programs land on a mix: ConceptMap for the clinically reviewed mappings, custom code tables for pipeline-local plumbing. The right line between the two is the one the team can defend in the next audit window.
Sources
- HL7 FHIR R6 spec - ConceptMap resource definition with relationship/equivalence semantics