HL7 v2 to FHIR: An AI-Native Migration Guide
Why HL7 v2 isn’t going away, how v2 segments map to FHIR resources, and how AI-assisted mapping turns a months-long interface backlog into days of reviewable work.
There is a persistent myth that FHIR is replacing HL7 v2. It is not — at least not soon. Most hospitals still run large HL7 v2 estates for their real-time operational flows, and they will continue to for years. What has changed is that the 21st Century Cures Act now makes a standardized FHIR API non-optional for every certified EHR, and CMS rules pile FHIR obligations on payers.
The result is not migration in the “rip and replace” sense. It is coexistence: organizations must expose FHIR while still running v2. That “must expose FHIR, still run v2” gap is the defining integration problem of this decade — and it is bidirectional by nature, because data has to flow both ways.
This guide walks through why the coexistence problem exists, how v2 messages map to FHIR resources concretely, where the work is genuinely hard, and how an AI-native, human-in-the-loop workflow compresses an interface backlog measured in months into work measured in days.
Why v2 and FHIR have to coexist
HL7 v2 is optimized for high-throughput, event-driven messaging inside and between hospitals. When a patient is admitted, an ADT message fans out to labs, pharmacy, billing, and analytics in real time. Decades of infrastructure depend on this, and it works.
FHIR is optimized for something different: API access, patient-facing apps, payer data exchange, and bulk analytics. The Cures Act’s information-blocking provisions and the §170.315(g)(10) certified-API requirement push every certified EHR, provider, and HIE toward FHIR — while their day-to-day operational reality stays on v2.
So the job is not to pick a winner. It is to translate reliably between the two, in both directions, so a v2-native estate can present a FHIR face to the outside world and consume FHIR from partners without abandoning what already runs.
How v2 segments map to FHIR resources
The clearest way to understand the translation is to follow a single message. Take an HL7 v2.5.1 ADT^A01 admission. It is built from delimited segments, and each meaningful segment maps to one or more FHIR resources.
- MSH (message header) → provenance and Bundle metadata for the FHIR output.
- PID (patient identification) → a FHIR Patient resource: identifiers (MRN), name, gender, birth date, address.
- PV1 (patient visit) → a FHIR Encounter resource: class (inpatient), location, admission details.
- DG1 (diagnosis) → a FHIR Condition resource: a coded diagnosis such as ICD-10 E11.9 (Type 2 diabetes mellitus without complications), or E11.65 with hyperglycemia.
- OBX (observations, in result messages) → FHIR Observation resources with LOINC-coded values and UCUM units.
The hard part isn’t the shape — it’s the meaning
Mapping a segment to a resource structurally is the easy 60%. The hard 40% is semantic fidelity: making sure the data means the same thing on both sides. Two problems dominate.
First, terminology. A v2 message might carry a local lab code or a local problem code that has to be normalized to the standard system US Core binds — LOINC for observations, ICD-10-CM or SNOMED CT for conditions, RxNorm for medications. Getting this wrong produces FHIR that is well-formed but clinically misleading.
Second, profile conformance. Producing generic FHIR is not enough; regulation and trading partners expect US Core profiles with required elements populated. A Patient without a required identifier, or a Condition without a coded value in the right system, will fail validation even though the JSON parses.
Round-trip fidelity and the reverse direction
Because coexistence is bidirectional, translation cannot be a one-way lossy transform. A robust engine must also go FHIR → v2 — for example, taking a FHIR order or result from a partner and emitting the v2 message a downstream hospital system expects.
This raises the bar on mapping design: mappings should be versioned and round-trippable, so that a value converted v2 → FHIR → v2 survives intact, and so that a mapping can be rolled back if a partner changes their format. Custom Z-segments and proprietary variants — which are everywhere in real hospital feeds — have to be handled explicitly rather than dropped.
The AI-native workflow, step by step
This is where an AI-native engine changes the economics. Instead of a consultant hand-building each interface over weeks, AI agents do the first draft and a human reviews it. The workflow is concrete and auditable.
- 1. Learn from samples — the Onboarding Agent ingests real sample messages and infers a partner’s format, including custom segments, to bootstrap the first interface.
- 2. Draft the mapping — the Mapping Agent proposes field-level v2 ↔ FHIR mappings using semantic schema matching and retrieval over prior mappings.
- 3. Normalize terminology — the Terminology Agent crosswalks local codes to LOINC/ICD-10/SNOMED/RxNorm with confidence scores.
- 4. Validate — the Conformance Agent checks output against US Core and explains any failure in plain language with a suggested fix.
- 5. Human review — your team approves, edits, or rejects each mapping. AI accelerates; humans decide. Every change is versioned and audited.
What changes when mapping goes from weeks to days
The headline benefit is throughput: an interface backlog that was measured in months becomes work measured in days, because the slow, manual mapping and terminology steps are drafted by AI and merely reviewed by people.
The second benefit is defensibility. Because every mapping is versioned, every terminology decision is scored, and every output is validated against US Core with a conformance report, you get an audit trail suitable for procurement and security review — which matters enormously when the data is clinical. Speed without auditability is a liability in healthcare; this workflow delivers both.
Key takeaways
- HL7 v2 isn’t going away — the Cures Act forces FHIR exposure while operations stay on v2, so the real job is bidirectional v2 ↔ FHIR translation, not replacement.
- Segment-to-resource mapping is concrete: in an ADT^A01, PID → Patient, PV1 → Encounter, and DG1 (e.g. ICD-10 E11.9) → Condition.
- The genuinely hard work is semantic — terminology normalization to US Core-bound value sets and profile conformance — not the structural shape.
- Coexistence is bidirectional, so mappings must be versioned, round-trippable, and able to handle custom Z-segments rather than dropping them.
- An AI-native, human-in-the-loop workflow (learn → draft → normalize → validate → review) compresses months of interface work into days while preserving the audit trail clinical data requires.
See it applied to your own data
The fastest way to go from this playbook to a plan is a live walkthrough on your own message types and systems. Book a free demo — no obligation.
Security & Compliance
Enterprise-grade trust, stated honestly
Protecting PHI is non-negotiable. Here's exactly where our certifications stand — no overclaiming.
Compliant · BAAs available
Audit in progress
On roadmap
Native, by design
AWS HIPAA-eligible infrastructure · Business Associate Agreements (BAAs) · Encryption in transit & at rest · See our security details →
Ready to turn months of interface work into days?
See a live HL7 v2 ↔ FHIR translation on your own message types. No obligation.