Introduction
Most hospitals are not replacing HL7 v2 with FHIR. They are adding FHIR beside it, so someone has to work out how a v2 message becomes a set of resources. This guide does that with three common messages and the free HL7 to FHIR Converter, which runs in your browser.
It is a guide to reading a conversion critically. Every output below comes from the converter itself, and the point of each example is as much what it leaves out as what it produces. All identifiers are synthetic.
The converter is a way to see and discuss a mapping. It is not an interface engine, and its output is a starting point. A real interface needs mapping decisions specific to your senders and receivers. For a fuller reference than one tool can give, see HL7's V2-to-FHIR Implementation Guide.
What the Converter Covers
| HL7 v2 message | FHIR R4 resources | Segments read |
|---|---|---|
| ADT | Patient, Encounter | PID, PV1 |
| ORM, OMG, OML | Patient, ServiceRequest | PID, ORC, OBR |
| ORU | Patient, DiagnosticReport, Observation | PID, OBR, OBX |
| Anything else with a PID | Patient, with a warning | PID |
The result is always a FHIR Bundle of type collection, with a new random UUID for each resource on every run. A collection is a package of resources for reading. It is not an instruction to a server to store them, and that difference matters below.
Example 1: ADT^A01 to Patient and Encounter
An inpatient admission, with next of kin, an allergy and a diagnosis.
MSH|^~\&|SYNTH_ADT|SYNTH_HOSP|FHIR_GW|SYNTH_HOSP|20260310143000+0000||ADT^A01^ADT_A01|SYN-ADT-0001|P|2.5.1 EVN|A01|20260310143000+0000 PID|1||SYN-MRN-1001^^^SYNTH_HOSP^MR||Testpatient^Alex^Q||19800214|F|||100 Example Way^^Testville^CA^90000^USA||(555)010-0100|||M NK1|1|Testcontact^Sam|SPO|||(555)010-0101 PV1|1|I|4E^401^B^SYNTH_HOSP||||9001^Example^Robin^^^Dr|||MED||||ADM|||9001^Example^Robin^^^Dr|INP|SYN-VN-2001|||||||||||||||||||||||||20260310143000+0000 AL1|1||70618^Penicillin^RXNORM DG1|1||J18.9^Pneumonia, unspecified organism^I10
Field mapping
| HL7 v2 | Value in this message | FHIR R4 |
|---|---|---|
| PID-3 | SYN-MRN-1001, authority SYNTH_HOSP, type MR | Patient.identifier |
| PID-5 | Testpatient^Alex^Q | Patient.name, with the middle initial as a second given |
| PID-7 | 19800214 | Patient.birthDate |
| PID-8 | F | Patient.gender = female |
| PID-11 | 100 Example Way^^Testville^CA^90000^USA | Patient.address |
| PID-13 | (555)010-0100 | Patient.telecom, home |
| PID-16 | M | Patient.maritalStatus |
| PV1-2 | I | Encounter.class = IMP |
| MSH-9 trigger | A01 | Encounter.status = in-progress |
| PV1-3 | 4E^401^B^SYNTH_HOSP | Encounter.location, as display text |
| PV1-7 | 9001^Example^Robin^^^Dr | Encounter.participant, as display text |
| PV1-19 | SYN-VN-2001 | Encounter.identifier, type VN |
| PV1-44 | 20260310143000+0000 | Encounter.period.start |
Output
The converter generates new UUIDs on each run. They are shown here as readable placeholders.
{
"resourceType": "Patient",
"id": "patient-id",
"identifier": [
{
"value": "SYN-MRN-1001",
"system": "urn:id:SYNTH_HOSP",
"type": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR" } ] }
}
],
"name": [ { "use": "official", "family": "Testpatient", "given": [ "Alex", "Q" ] } ],
"birthDate": "1980-02-14",
"gender": "female",
"address": [
{ "line": [ "100 Example Way" ], "city": "Testville", "state": "CA", "postalCode": "90000", "country": "USA" }
],
"telecom": [ { "system": "phone", "value": "(555)010-0100", "use": "home" } ],
"maritalStatus": { "coding": [ { "code": "M" } ], "text": "M" }
}
{
"resourceType": "Encounter",
"id": "encounter-id",
"status": "in-progress",
"class": {
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "IMP",
"display": "inpatient encounter"
},
"identifier": [
{
"value": "SYN-VN-2001",
"type": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "VN" } ] }
}
],
"subject": { "reference": "Patient/patient-id" },
"participant": [
{
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "ATND",
"display": "attender"
}
]
}
],
"individual": { "display": "Dr Robin Example" }
}
],
"location": [ { "location": { "display": "Ward 4E, Room 401, Bed B" } } ],
"period": { "start": "2026-03-10T14:30:00+00:00" }
}
Notes, warnings and what was not mapped
The Conversion Notes tab shows one line: Mapped ADT^A01 → Patient + Encounter. There are no warnings, and that does not mean nothing was lost. These were dropped without a note:
- NK1: the next of kin. It could become
Patient.contactor aRelatedPerson. - AL1: the penicillin allergy. It could become an
AllergyIntolerance. - DG1: the diagnosis. It could become a
Condition. - EVN and MSH details, including who sent the message and when.
- PV1-10 hospital service, PV1-14 admit source, PV1-17 admitting doctor and PV1-18 patient type.
Losing the allergy is the kind of gap that matters clinically. Decide what happens to each segment your sender actually transmits, and do not assume that anything absent from the output was unimportant.
References and next step
Encounter.subject points at the Patient. Both the attending doctor and the location are display text only, because the converter creates no Practitioner or Location. Before using this in anger, decide whether your server needs real references to those resources, and how you will match them to existing ones.
Then try changing A01 to A03 in the MSH and EVN segments. Encounter.status becomes finished, which shows that the trigger event carries meaning. An A08 update should change the existing Encounter rather than create a second one, and this converter cannot do that for you.
Example 2: ORM^O01 to ServiceRequest
A new stat order for a chest X-ray.
MSH|^~\&|SYNTH_CPOE|SYNTH_HOSP|SYNTH_RIS|SYNTH_HOSP|20260310120000+0000||ORM^O01^ORM_O01|SYN-ORM-0001|P|2.5.1 PID|1||SYN-MRN-1001^^^SYNTH_HOSP^MR||Testpatient^Alex^Q||19800214|F PV1|1|I|4E^401^B^SYNTH_HOSP||||9001^Example^Robin^^^Dr||||||||||||SYN-VN-2001 ORC|NW|SYN-PLAC-3001|SYN-FILL-4001||||||20260310120000+0000|||9001^Example^Robin^^^Dr OBR|1|SYN-PLAC-3001|SYN-FILL-4001|36643-5^XR Chest 2 Views^LN|S||20260310130000+0000|||||||||9001^Example^Robin^^^Dr NTE|1||Synthetic order note: portable if the patient cannot stand.
Field mapping
| HL7 v2 | Value in this message | FHIR R4 |
|---|---|---|
| ORC-1 | NW | ServiceRequest.status = active, and intent is always order |
| ORC-2 | SYN-PLAC-3001 | ServiceRequest.identifier, type PLAC |
| ORC-3 | SYN-FILL-4001 | ServiceRequest.identifier, type FILL |
| ORC-9 | 20260310120000+0000 | ServiceRequest.authoredOn |
| ORC-12 | 9001^Example^Robin^^^Dr | ServiceRequest.requester, as display text |
| OBR-4 | 36643-5^XR Chest 2 Views^LN | ServiceRequest.code, with LN mapped to http://loinc.org |
| OBR-5 | S | ServiceRequest.priority = stat |
| OBR-7 | 20260310130000+0000 | ServiceRequest.occurrenceDateTime |
Output
{
"resourceType": "ServiceRequest",
"id": "service-request-id",
"intent": "order",
"status": "active",
"code": {
"coding": [ { "system": "http://loinc.org", "code": "36643-5", "display": "XR Chest 2 Views" } ],
"text": "XR Chest 2 Views"
},
"identifier": [
{
"value": "SYN-PLAC-3001",
"type": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "PLAC" } ] }
},
{
"value": "SYN-FILL-4001",
"type": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "FILL" } ] }
}
],
"subject": { "reference": "Patient/patient-id" },
"occurrenceDateTime": "2026-03-10T13:00:00+00:00",
"authoredOn": "2026-03-10T12:00:00+00:00",
"requester": { "display": "Dr Robin Example" },
"priority": "stat"
}
The Bundle also holds a Patient built from the PID, in the same form as Example 1.
Notes, warnings and what was not mapped
The only note is Mapped ORM^O01 → ServiceRequest resources. These were dropped without a note:
- PV1: there is no Encounter in this output, and no
ServiceRequest.encounter. The link between the order and the admission is lost. - NTE: the order note saying the film may be portable. It could go in
ServiceRequest.note. - ORC-7 and TQ1 timing: only OBR-5 sets the priority, and only OBR-7, OBR-36 or ORC-15 set the time. A sender that uses TQ1 gets neither.
The time mapping deserves a check against your sender. OBR-7 is the observation date and time, which not every system fills in when an order is placed, so read what your own feed means by it before trusting occurrenceDateTime.
References and next step
ServiceRequest.subject points at the Patient. Nothing else is linked. The identifiers are the important part here: PLAC and FILL are what connect this order to its later result, but they have no system, so they are not yet unique across senders. Add one for your own placer and filler before treating them as real identifiers.
Next, try changing ORC-1 from NW to CA. status becomes revoked, which shows that a cancellation arrives as the same kind of resource. A real interface has to find and update the original order using those identifiers.
Example 3: ORU^R01 to DiagnosticReport and Observation
A laboratory result with four different kinds of OBX.
MSH|^~\&|SYNTH_LAB|SYNTH_HOSP|FHIR_GW|SYNTH_HOSP|20260310150000+0000||ORU^R01^ORU_R01|SYN-ORU-0001|P|2.5.1 PID|1||SYN-MRN-1001^^^SYNTH_HOSP^MR||Testpatient^Alex^Q||19800214|F OBR|1|SYN-PLAC-5001|SYN-FILL-6001|24323-8^Comprehensive metabolic panel^LN|||20260310144500+0000|||||||||9001^Example^Robin^^^Dr||||||20260310150000+0000|||F OBX|1|NM|2345-7^Glucose^LN||105|mg/dL^mg/dL^UCUM|70-99|H|||F OBX|2|NM|2951-2^Sodium^LN||140|mmol/L^mmol/L^UCUM|136-145|N|||F OBX|3|SN|1920-8^AST^LN||>^500|U/L^U/L^UCUM|10-40|H|||F OBX|4|ST|8251-1^Service comment^LN||Synthetic comment: sample slightly haemolysed.||||||F NTE|1||Synthetic note: repeat in 24 hours.
Field mapping
| HL7 v2 | Value in this message | FHIR R4 |
|---|---|---|
| OBR-3 | SYN-FILL-6001 | DiagnosticReport.identifier, type FILL |
| OBR-4 | 24323-8^Comprehensive metabolic panel^LN | DiagnosticReport.code |
| OBR-7 | 20260310144500+0000 | effectiveDateTime on the report and on every Observation |
| OBR-25 | F | DiagnosticReport.status = final |
| OBX-2 | NM, SN, ST | Chooses valueQuantity or valueString |
| OBX-3 | 2345-7^Glucose^LN | Observation.code |
| OBX-5 | 105 | Observation.valueQuantity.value |
| OBX-6 | mg/dL^mg/dL^UCUM | valueQuantity.unit and code, with the UCUM system |
| OBX-7 | 70-99 | Observation.referenceRange.text |
| OBX-8 | H | Observation.interpretation |
| OBX-11 | F | Observation.status = final |
Output
{
"resourceType": "DiagnosticReport",
"id": "diagnostic-report-id",
"status": "final",
"code": {
"coding": [ { "system": "http://loinc.org", "code": "24323-8", "display": "Comprehensive metabolic panel" } ],
"text": "Comprehensive metabolic panel"
},
"subject": { "reference": "Patient/patient-id" },
"effectiveDateTime": "2026-03-10T14:45:00+00:00",
"identifier": [
{
"value": "SYN-FILL-6001",
"type": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "FILL" } ] }
}
],
"result": [
{ "reference": "Observation/observation-1-id" },
{ "reference": "Observation/observation-2-id" },
{ "reference": "Observation/observation-3-id" },
{ "reference": "Observation/observation-4-id" }
]
}
The numeric result, glucose:
{
"resourceType": "Observation",
"id": "observation-1-id",
"status": "final",
"code": {
"coding": [ { "system": "http://loinc.org", "code": "2345-7", "display": "Glucose" } ],
"text": "Glucose"
},
"subject": { "reference": "Patient/patient-id" },
"effectiveDateTime": "2026-03-10T14:45:00+00:00",
"valueQuantity": { "value": 105, "unit": "mg/dL", "code": "mg/dL", "system": "http://unitsofmeasure.org" },
"referenceRange": [ { "text": "70-99" } ],
"interpretation": [
{ "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation", "code": "H" } ] }
]
}
The structured numeric result, AST, which the source message reports as greater than 500:
{
"resourceType": "Observation",
"id": "observation-3-id",
"status": "final",
"code": {
"coding": [ { "system": "http://loinc.org", "code": "1920-8", "display": "AST" } ],
"text": "AST"
},
"subject": { "reference": "Patient/patient-id" },
"effectiveDateTime": "2026-03-10T14:45:00+00:00",
"valueQuantity": { "value": 500, "unit": "U/L" },
"referenceRange": [ { "text": "10-40" } ],
"interpretation": [
{ "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation", "code": "H" } ] }
]
}
The text result, a service comment, becomes "valueString": "Synthetic comment: sample slightly haemolysed." on its own Observation.
Notes, warnings and what was not mapped
The only note is Mapped ORU^R01 → DiagnosticReport + Observation resources. Read the AST result again, because this is the most important limitation in this guide:
- The comparator is lost. OBX-5 says
>^500, meaning greater than 500. The output says the value is exactly 500, with no warning. FHIR hasQuantity.comparatorfor this, and the converter does not fill it in. The same structured-numeric path also omits the UCUMsystemandcode.
These were also dropped without a note:
- NTE: the note asking for a repeat in 24 hours. It could go in
DiagnosticReport.conclusionorObservation.note. - OBR-2: the placer order number. Nothing links this report back to the order in Example 2, and there is no
DiagnosticReport.basedOn. - OBR-22: the results date. There is no
DiagnosticReport.issued. - OBR-16: the ordering provider, and any performing laboratory. There is no
performer. - OBX-14: each Observation takes its time from OBR-7, even if an OBX carries its own.
- Reference ranges stay as text.
70-99does not becomelowandhigh, so it cannot be computed with. - Categories: neither
DiagnosticReport.categorynorObservation.categoryis set. Base R4 does not require them, but implementation guides often do.
References and next step
DiagnosticReport.result points at each Observation, and everything points at the Patient. The order of the OBX segments is preserved, but anything that grouped results below the OBR level is not.
Try removing the > from the third OBX, leaving ^500, and compare the two outputs: they are identical, which is why this needs a rule of your own. If your laboratory sends SN results, test the comparators your feed really uses before trusting a converted value.
The Reference Problem: Why This Bundle Will Not Load as It Is
In all three examples, entries look like this:
fullUrl: urn:uuid:<id>
reference: Patient/<id>
These two forms do not connect. FHIR R4's rules for resolving references in a Bundle convert a relative [type]/[id] reference to an absolute URL only when the entry's fullUrl is a RESTful URL. With a urn:uuid fullUrl, the specification says the reference has no defined meaning within the Bundle.
So a program reading the output can match references by eye, or by your own code, but a conforming resolver will not. To load these into a server:
- Rewrite each reference to the
urn:uuid:form, such asurn:uuid:<id>, so it matches afullUrl. - Change the Bundle
typetotransaction, and give each entry arequestthat says what to do with it. - Replace
POSTwith a conditional create or update keyed on a real identifier. Otherwise replaying a message creates duplicates, because every run invents new UUIDs.
Timestamps Need an Offset
The examples here all carry +0000. That is deliberate. If a v2 timestamp has a time but no offset, as many feeds do, the converter outputs a time with no zone, such as 2026-03-10T14:30:00. R4's dateTime type requires a time zone whenever hours and minutes are present, so that value is invalid.
The converter's built-in sample buttons show this, because their messages have no offsets: their output fails the check described below. Date-only values such as a birth date are not affected. In a real interface, decide which zone a sender's local times are in, and add it explicitly.
JSON, Validation and Integration Are Different Things
The converter produces JSON that has the shape of FHIR. It does not validate that JSON. FHIR R4's validation page lists what validating a resource involves:
| Aspect | What it checks | Done by the converter? |
|---|---|---|
| Structure | All content is described by the specification, with nothing extra | No |
| Cardinality | Minimum and maximum counts of each property | No |
| Value domains | Values fit their types, and enumerated codes are valid | No |
| Coding bindings | Codes and displays are valid for their value sets | No |
| Invariants | Co-occurrence and other rules | No |
| Profiles | The rules of any profile or implementation guide you need | No |
| Business rules | Duplicates, whether references resolve, authorization | No |
Different tools cover different parts of this. The same R4 page shows that JSON Schema checks structure, cardinality and values, but not bindings or invariants. The HL7 Validator and the $validate operation go further, but not to business rules, and the page is clear that static testing is not enough to prove conformance.
What we checked for this guide. The three example Bundles pass the official R4 JSON Schema. That is a narrow result. It means the JSON has a legal shape. We did not run them through the HL7 Validator, a terminology server, a US Core or other profile, or a FHIR server, so none of those is claimed here. For example, the bare M in maritalStatus passes the schema, yet it has no code system at all.
Integration is a further step again. A resource can be valid and still wrong for your receiver. A working interface also has to handle the same patient arriving twice, updates, merges, cancellations, corrections, ordering, failures and retries. Passing validation shows none of that. Use your own test environment and real, de-identified message samples.
From a Converted Sample to a Real Interface
Work through these before you build:
- Choose your profiles first. US Core, a national profile or a vendor's rules decide which elements and code systems are required. Map to those, not just to base R4.
- List the segments and fields your sender really uses. Take a sample of real traffic, de-identified. Give each field a decision: mapped, deliberately dropped, or carried in an extension.
- Fix identifiers. Use real, stable
systemvalues rather thanurn:id:..., for patients, encounters and orders. Identifiers are what make replays and updates safe. - Decide on update behaviour. A08, A40 merges, order cancellations and corrected results must change or link existing resources.
- Map your terminology. Local codes need a mapping to LOINC, SNOMED CT or your required value sets. The converter recognises only a few system names, such as
LN,SCT,I10andCPT. Other mnemonics pass through as written. - Handle clinical edge cases deliberately. Comparators, cancelled results, free text and Z-segments all need rules of their own.
- Validate and test in stages. Start with a validator configured with your profiles, then a test server, then end-to-end tests with the receiving system.
- Protect the data. Real messages hold patient data. The converter runs in your browser and sends nothing to a server, but a saved file, a shared link or a ticket attachment is a disclosure risk. Use synthetic or de-identified messages wherever you can.
To see where this sits in a wider architecture, open the FHIR integration architecture template, which shows an interface engine feeding a FHIR server. For the v2 side, the HL7 Integration Guide and the HL7 Message Viewer help you check a message before you convert it.
Sources
- HL7 FHIR R4: Validating Resources · Bundle, including resolving references · Data types
- HL7 FHIR R4 resources: Patient · Encounter · ServiceRequest · DiagnosticReport · Observation
- HL7: V2-to-FHIR Implementation Guide
The output in this guide was produced by the converter on the date at the top. The tests in the site's repository regenerate it and fail if it changes. No part of it is a claim of conformance, certification or production readiness.
Referenced Product
HL7 to FHIR Converter
Built for the work covered in this guide, from the same real-world deployment experience.