HL7v2 to FHIR - what you get per message

An HL7v2 message is one flat list of segments, while FHIR splits the same information into separate resources - the patient in PID becomes a Patient, the visit in PV1 an Encounter, each OBX result an Observation. The tables below spell that mapping out, segment by segment and message family by message family.

What a converted bundle contains follows the segments actually present in the message, not a fixed list per message type. Every bundle opens with the MessageHeader built from MSH, followed by the Organization resources for the sending and receiving facilities from MSH-4 and MSH-6, which the header references as sender and receiver.

Segments and their resources

Repeating segments become multiple resources - three NK1 segments produce three RelatedPerson resources, five OBX segments five Observations, and so on.

Practitioner, Location and Organization resources are created on demand when a field references one, e.g. the attending doctor in PV1-7 or the assigned location in PV1-3, and identical entities are deduplicated across the whole bundle. A PL location such as WARD1^101^A^GENHOSP becomes a hierarchy of Location resources - the facility, the point of care, the room and the bed, each partOf the one before it and carrying its physicalType - and the Encounter points at the most specific one, which also takes the PL-5 location status as operationalStatus and the PL-6 person location type as type.

Any standard segment without a mapping of its own, and an enriching segment that arrives without the resource it enriches - a PV2 with no PV1, an RXR with no pharmacy segment - becomes a Basic resource the same way a Z-segment does.

Message families

The message structure from MSH-9 selects a conversion family, which determines how order-related segments group together:

An ORU^R01 example

from zato.hl7v2 import parse_hl7

raw = (
    'MSH|^~\\&|LAB|FACILITY|EHR|FAC|20260315101112||ORU^R01^ORU_R01|CTL002|P|2.9\r'
    'PID|||12345^^^HOSP^MR||SMITH^JOHN^A||19800115|M\r'
    'ORC|RE|PLACER001|FILLER001\r'
    'OBR|1|PLACER001|FILLER001|24331-1^Lipid panel^LN|||202603150930||||||||||||||||||F\r'
    'OBX|1|NM|2093-3^Cholesterol^LN||187|mg/dL^^UCUM|<200|N|||F\r'
    'NTE|1||Fasting sample\r'
    'OBX|2|NM|2085-9^HDL cholesterol^LN||62|mg/dL^^UCUM|>40|N|||F\r'
    'OBX|3|NM|2571-8^Triglycerides^LN||145|mg/dL^^UCUM|<150|N|||F\r'
    'SPM|1|SPM001||SER^Serum\r'
)

msg = parse_hl7(raw, validate=False)
bundle = msg.to_fhir()

for entry in bundle.entry:
    print(entry.resource.resource_type)

MessageHeader
Organization
Organization
Patient
ServiceRequest
DiagnosticReport
Observation
Observation
Observation
Specimen

Each Observation has a valueQuantity - 187, 62 and 145 mg/dL - and the NTE comment is stored in the first one's note. The DiagnosticReport is final from the F in OBR-25, lists all three Observations in result and the Specimen in specimen, and everything points back at the Patient.

Observation values

The OBX-2 value type determines how OBX-5 is represented:

A valueQuantity carries system and code only when OBX-6 names a coding system, e.g. mg/dL^^UCUM. Units with no system keep the unit text alone, as the FHIR invariant on Quantity requires.

A value type the parser does not recognize is read as ST, so the value arrives as valueString. A recognized type outside this table, e.g. MO or CP, has no FHIR element to go to, so the type and the value are preserved as unmapped/OBX-2 and unmapped/OBX-5 extensions. Either way the value stays in the output.

See also

Learn more