MajwareMAJWARE

HL7 v2 to FHIR R4: A Practical Conversion Guide

Three worked HL7 v2 to FHIR R4 conversions: ADT to Patient and Encounter, ORM to ServiceRequest, ORU to DiagnosticReport and Observation. See the source message, the field mapping, the real converter output, what gets dropped, and what validation still has to prove.

Majware Team·7 November 2026·15 min read
Read Guide

What this guide covers

  • ADT to Patient and Encounter, ORM to ServiceRequest, ORU to DiagnosticReport and Observation, each from a synthetic message
  • Field-by-field mapping, the actual output, and what the converter silently leaves behind
  • Why references in the output need rewriting before a server can resolve them
  • The difference between producing JSON, passing validation and having a working interface
  • A checklist for moving from a converted sample to a real interface
15 min read
Reading time
10
Topics covered

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 messageFHIR R4 resourcesSegments read
ADTPatient, EncounterPID, PV1
ORM, OMG, OMLPatient, ServiceRequestPID, ORC, OBR
ORUPatient, DiagnosticReport, ObservationPID, OBR, OBX
Anything else with a PIDPatient, with a warningPID

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.

Guide example: ADT^A01 (synthetic)Open example in converter →
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 v2Value in this messageFHIR R4
PID-3SYN-MRN-1001, authority SYNTH_HOSP, type MRPatient.identifier
PID-5Testpatient^Alex^QPatient.name, with the middle initial as a second given
PID-719800214Patient.birthDate
PID-8FPatient.gender = female
PID-11100 Example Way^^Testville^CA^90000^USAPatient.address
PID-13(555)010-0100Patient.telecom, home
PID-16MPatient.maritalStatus
PV1-2IEncounter.class = IMP
MSH-9 triggerA01Encounter.status = in-progress
PV1-34E^401^B^SYNTH_HOSPEncounter.location, as display text
PV1-79001^Example^Robin^^^DrEncounter.participant, as display text
PV1-19SYN-VN-2001Encounter.identifier, type VN
PV1-4420260310143000+0000Encounter.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.contact or a RelatedPerson.
  • 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.

Guide example: ORM^O01 (synthetic)Open example in converter →
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 v2Value in this messageFHIR R4
ORC-1NWServiceRequest.status = active, and intent is always order
ORC-2SYN-PLAC-3001ServiceRequest.identifier, type PLAC
ORC-3SYN-FILL-4001ServiceRequest.identifier, type FILL
ORC-920260310120000+0000ServiceRequest.authoredOn
ORC-129001^Example^Robin^^^DrServiceRequest.requester, as display text
OBR-436643-5^XR Chest 2 Views^LNServiceRequest.code, with LN mapped to http://loinc.org
OBR-5SServiceRequest.priority = stat
OBR-720260310130000+0000ServiceRequest.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.

Guide example: ORU^R01 (synthetic)Open example in converter →
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 v2Value in this messageFHIR R4
OBR-3SYN-FILL-6001DiagnosticReport.identifier, type FILL
OBR-424323-8^Comprehensive metabolic panel^LNDiagnosticReport.code
OBR-720260310144500+0000effectiveDateTime on the report and on every Observation
OBR-25FDiagnosticReport.status = final
OBX-2NM, SN, STChooses valueQuantity or valueString
OBX-32345-7^Glucose^LNObservation.code
OBX-5105Observation.valueQuantity.value
OBX-6mg/dL^mg/dL^UCUMvalueQuantity.unit and code, with the UCUM system
OBX-770-99Observation.referenceRange.text
OBX-8HObservation.interpretation
OBX-11FObservation.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 has Quantity.comparator for this, and the converter does not fill it in. The same structured-numeric path also omits the UCUM system and code.

These were also dropped without a note:

  • NTE: the note asking for a repeat in 24 hours. It could go in DiagnosticReport.conclusion or Observation.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-99 does not become low and high, so it cannot be computed with.
  • Categories: neither DiagnosticReport.category nor Observation.category is 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:

  1. Rewrite each reference to the urn:uuid: form, such as urn:uuid:<id>, so it matches a fullUrl.
  2. Change the Bundle type to transaction, and give each entry a request that says what to do with it.
  3. Replace POST with 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:

AspectWhat it checksDone by the converter?
StructureAll content is described by the specification, with nothing extraNo
CardinalityMinimum and maximum counts of each propertyNo
Value domainsValues fit their types, and enumerated codes are validNo
Coding bindingsCodes and displays are valid for their value setsNo
InvariantsCo-occurrence and other rulesNo
ProfilesThe rules of any profile or implementation guide you needNo
Business rulesDuplicates, whether references resolve, authorizationNo

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:

  1. 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.
  2. 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.
  3. Fix identifiers. Use real, stable system values rather than urn:id:..., for patients, encounters and orders. Identifiers are what make replays and updates safe.
  4. Decide on update behaviour. A08, A40 merges, order cancellations and corrected results must change or link existing resources.
  5. 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, I10 and CPT. Other mnemonics pass through as written.
  6. Handle clinical edge cases deliberately. Comparators, cancelled results, free text and Z-segments all need rules of their own.
  7. 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.
  8. 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

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.

View Product