HL7v2 to FHIR translation is not a science; it is a craft with a small set of patterns that show up in almost every integration. Memorizing the patterns is what turns v2-to-FHIR translation from an ad-hoc exercise into a repeatable practice. Six patterns cover most of what a working integration handles day to day.
Naming the patterns is the discipline. For related walkthroughs, more on healthcare data exchange collects the surrounding material.
Pattern One: One Segment, One Resource
The most common pattern is a one-to-one mapping between a v2 segment and a FHIR resource. PID becomes Patient. PV1 (patient visit) becomes Encounter. OBX becomes Observation. AL1 (allergy) becomes AllergyIntolerance.
Every integration starts here. A pass through the site's HL7 v2 segment → FHIR mapping tool surfaces these one-to-one mappings quickly.
Pattern Two: One Message, Multiple Resources
ADT^A01 (admit) carries PID, PV1, IN1 (insurance), OBX (observations at admit), and more. Translating the message produces multiple FHIR resources bundled together: Patient, Encounter, Coverage, and multiple Observations.
FHIR usually expresses this as a transaction Bundle. The Bundle's atomicity captures the "these belong together" semantics that the v2 message implies. For the shape of one such message, reading an HL7v2 message when you only know FHIR covers the anatomy.
Pattern Three: Repeating Segments as Array Fields
Segments that repeat (multiple OBX per message, multiple AL1 per patient) map to arrays in the corresponding FHIR resource or to multiple resources in the Bundle. The choice depends on the semantics: repeating measurements of the same observation are Observation.component; separate observations are separate Observation resources.
Getting the choice right requires reading the v2 semantics carefully. Silent wrong choices produce Observations that look right at first and confuse downstream systems later. For the OBX detail, OBX segments and where they end up in a FHIR Observation covers the routing.
Pattern Four: References Through Identifiers
v2 links resources through identifiers embedded in fields (PID-3.1 referring to a MRN). FHIR links resources through Reference objects (Observation.subject.reference = "Patient/123").
The translation requires the integration to know the FHIR ID of the Patient before it can build the Observation. A common pattern is to assign FHIR IDs during ingestion based on the v2 identifier so subsequent references resolve consistently. For the PID identifier framing, PID vs Patient: what maps and what doesn't covers the field-level detail.
Pattern Five: Coded Values Need Value Sets
v2 uses HL7 tables (like table 0001 for administrative sex) and vendor-specific tables. FHIR expects codes from bound value sets (like administrative-gender).
Every coded field needs a translation table. Translations that are not documented drift; translations that are documented survive team rotations.
Pattern Six: Missing Fields as Data Loss Risk
Not every v2 field has a FHIR home. Silent drops during translation lose data. The v2-to-FHIR mapping project publishes canonical patterns for handling the drops; using them is more durable than inventing house patterns.
Every translation should log the fields it did not map. The log becomes the audit trail that answers "did we lose that data" questions.
Memorizing the six patterns is the shortcut from ad-hoc v2-to-FHIR translation to a repeatable practice. Every integration engineer benefits from having them cached.
Sources
- HL7 Confluence v2-to-FHIR project page with canonical - HL7 Confluence v2-to-FHIR project page with canonical translation patterns