HL7 v2.5.1 ↔ FHIR R4 converter

What this does, and what it doesn't

HL7 v2.5.1 and FHIR R4 do not line up one-to-one. v2 is a positional, segment-oriented wire format with a lot of site-local convention baked in; FHIR is a resource graph with required codings and canonical value sets. Any converter has to make choices, so this one makes them visible: the Mapping trace tab lists every element it read and where it put it, and the Not carried over tab lists every populated field it did not read. If a field matters to you and it shows up in that second list, the conversion lost it.

Segments understood

MSH MSA ERR EVN PID PV1 AL1 DG1 IN1 MRG ORC OBR OBX NTE SCH ZDS — the segment set defined in the HL7 v2.5.1 reference MCP server, which is where the field names and code tables used here come from. Segments outside that set are reported as unmapped rather than dropped quietly.

Message types

ADT A01/A02/A03/A04/A05/A08/A11/A13/A28/A31/A40, ORM^O01, ORR^O02, ORU^R01, SIU^S12 and ACK. Structure validation (required segments present, segment order) runs against those definitions.

Bundle shape

HL7 → FHIR emits a Bundle of type: "message": a MessageHeader built from MSH, followed by the resources it produced, each with a fullUrl. Resource ids are derived deterministically from the content, so converting the same message twice gives byte-identical output — useful for diffing two messages through the converter. FHIR → HL7 accepts that Bundle, any other Bundle, or a single bare resource.

Known simplifications

• Local coding systems (anything that isn't LN, SCT, I9C, I10, CPT, and similar) become urn:hl7:codesystem:NAME placeholders, and assigning authorities become urn:hl7:namespace:NAME. Substitute your own canonical URLs before using the output anywhere real.
• Timestamps without a UTC offset are emitted without one. v2 permits that; FHIR instant does not, so Bundle.timestamp gets Z appended when MSH-7 carries no offset, and that is flagged in Issues.
• Phone numbers split across XTN-6/XTN-7 (area code and local number) are joined into a single ContactPoint.value, and come back in XTN-1. Same number, different components.
• NTE-2 (source of comment) has no home in a FHIR Annotation; it is left unread, so it shows up in Not carried over.
• OBX-2 is re-derived from value[x] on the way back. For the string types the original is kept in an extension so ST and TX survive the trip; for everything else the value determines the type.
• Race (PID-10) and ethnicity (PID-22) use the US Core extensions, with the original code kept in ombCategory. If you are not on US Core, drop them.
• Only the segments listed above are converted. RGS, AIS, AIP, NK1, GT1, PR1 and the rest are reported, not mapped — and when a structure requires one of them, the reverse direction says so instead of pretending.
• OBR-18 (Placer Field 1) is mapped as an accession identifier (type ACSN, system urn:hl7:namespace:accession) on ServiceRequest and/or DiagnosticReport. That is an IHE Radiology convention, not an HL7 rule — sites also put the accession in OBR-2, OBR-3 or ORC-3. Placer/filler order numbers (OBR-2/3) stay separate identifiers with types PLAC/FILL.
• Z segments have no FHIR equivalent. ZDS is carried as an identifier with system urn:dicom:uid; other Z segments are reported, not converted.
• This is a mapping aid, not a certified interface engine. Nothing here is validated against a FHIR server or a conformance profile.

How faithful is it?

Press Round-trip check on any sample. Five of the six built-in messages come back byte-identical apart from the simplifications listed above; the SIU sample loses its RGS and AIS segments, which this converter does not map, and says so. The check is the honest answer to "can I trust this?" for your message, not just for the samples.