HL7 & FHIR Interoperability Testing

1 The Hook

A fictional NZ private laboratory, Tui Diagnostics, sent test results to GP practices as HL7 v2 messages. For years it worked. Then a GP practice upgraded its patient management system, and within days a result came through that read as a sodium level of 145 when the lab had reported 14.5. The decimal point had moved.

The cause was small and entirely structural. The lab’s message put the result value and its units in separate fields of the observation segment. The new practice system read the value field but parsed the units field as part of the number on certain messages, because the two systems disagreed about exactly which delimiter separated those pieces. Most results were whole numbers and survived. Results with a decimal place — a minority — came through wrong.

No system crashed. Both ends believed they were speaking the same language. The lab’s message was, by its own rules, valid. The practice’s parser was, by its own rules, working. The defect lived in the gap between two systems’ interpretations of the same message — and only a tester who read the message structure itself, and tested the decimal-place case, would have caught it before a clinician did.

Here is the lesson hidden in that story. The integration had been tested by sending a result and seeing a result appear. That is testing the happy path of the channel, not the structure of the message. Interoperability testing is reading the segments and fields, validating them against an agreed profile, and deliberately sending the awkward cases — the decimal, the missing field, the unexpected repeat — that expose where two systems quietly disagree.

2 The Rule

3 The Analogy

4 HL7 v2 Messages

HL7 version 2 is the older but still dominant messaging standard in health. It is a text-based format that carries events between systems — a patient admitted, a result ready, an order placed. You do not need to memorise the specification, but you must be able to read the shape of a message and reason about its parts.

An HL7 v2 message is a series of segments, one per line, each starting with a three-letter code. Within a segment, fields are separated by a delimiter (commonly the pipe character), and fields can themselves be split into components by a sub-delimiter. A simplified result message looks like this:

Reading it as a tester:

• MSH is the message header — who sent it, who receives it, the message type (here ORU^R01, an observation result), and the HL7 version. A wrong version or message type is an immediate structural fail.
• PID is the patient identifier segment — this is where the NHI lives (the ZAB1234^^^NHI component). From Lesson 1, this is the field a patient-safety tester scrutinises most.
• OBR is the observation request — what test was ordered.
• OBX is the observation result itself — the value (14.5), its units (mmol/L), its reference range (135-145), and an abnormal flag (L for low). The Tui Diagnostics decimal bug lived exactly here, in the boundary between the value and the units.

The structural concepts a tester checks are cardinality (how many times a segment or field may or must appear — is PID required, can OBX repeat?), data type (is OBX-2 declared NM for a numeric result, and does the value actually parse as one?), and delimiters (are the field and component separators consistent, the exact disagreement that bit Tui). Reading the message and asking “is each field where the structure says it should be, and does its value match its declared type?” is the core of HL7 v2 testing.

5 FHIR Resources

FHIR — Fast Healthcare Interoperability Resources — is the modern standard, and it is where NZ health interoperability is heading, including the national Hira platform. Where HL7 v2 is pipe-delimited text, FHIR represents the same clinical concepts as structured resources, usually exchanged as JSON or XML over a web API. The sodium result above, as a simplified FHIR Observation resource, looks like this:

Notice how the same pieces reappear, now as named structured fields rather than positional ones. For a tester, the key concepts are:

• resourceType: which kind of resource this is — Patient, Observation, Encounter, ServiceRequest. The wrong type, or a type the receiver does not handle, is a structural fail.
• References between resources: the subject points to a Patient resource. A FHIR record is a web of linked resources, and a reference to a patient who does not exist, or to the wrong patient, is the FHIR version of the Lesson 1 wrong-patient risk.
• valueQuantity and coded values: the value carries an explicit unit and a unit code, and the test is identified by a coding system. Because the unit is its own named field, the FHIR design makes the Tui decimal-and-units confusion harder — but you still test that the value parses as a number and the unit is the one expected.
• status and required elements: an Observation has a required status (final, preliminary, amended). A result marked preliminary treated as final, or a missing required element, is a meaningful defect.

6 Conformance Profiles

A base standard like HL7 v2 or FHIR is deliberately broad — it has to serve every country and every use. A conformance profile narrows it for a specific context: which segments or resources are required, which fields are mandatory, what code sets and identifier systems must be used, and what the cardinalities are. It is the agreed contract that turns “valid HL7” into “valid for our exchange.”

This distinction is the heart of conformance testing. A message can be perfectly valid against the base standard and still violate the profile that two NZ systems agreed to. For example, the base FHIR Patient resource does not require any particular identifier, but an NZ profile will require the NHI as a specific identifier system. A patient resource with no NHI is valid base FHIR and a profile failure — and from Lesson 1 you know it is also a patient-safety risk.

So conformance testing happens at two levels, and you test both:

• Against the base standard: is this structurally a legal HL7 v2 message or FHIR resource at all — correct segments, valid data types, parseable structure?
• Against the agreed profile: does it meet the stricter local contract — the NHI present as the required identifier, the mandated code system used (such as a recognised terminology for the test or diagnosis), required fields populated, cardinalities respected?

The profile is your test oracle. When you have one, “is this message correct?” becomes a concrete, checkable question rather than a judgement call. When a project does not have a written profile, surfacing that absence is itself a valuable testing outcome — because without an agreed contract, two systems will eventually disagree, exactly as Tui Diagnostics and the practice did.

7 Negative and Edge Cases

Happy-path interoperability testing — send a clean result, see it arrive — catches almost none of the defects that matter. The real failures live in the cases a healthy sender rarely produces but a real-world sender eventually will. A serious interoperability test suite is mostly negative and edge cases:

• Missing required field: a message with no NHI, no result status, or no units. Does the receiver reject it clearly, or silently accept a half-message?
• Wrong data type: a numeric result field carrying text (“see comment”), or a date in the wrong format. Does it error, or guess?
• Boundary values: the Tui decimal — values with decimal places, very large numbers, negative values, zero, and empty strings.
• Unexpected repeats and cardinality: two PID segments, an Observation with multiple values, a referral with no patient. Does the receiver handle the count the profile allows, and reject the count it does not?
• Encoding and special characters: macrons in NZ names (ā, ē, ī, ō, ū), the delimiter character appearing inside a data value, and non-ASCII content. Does the name survive the round trip intact?
• Status and amendment: a preliminary result later amended or cancelled. Does the receiver update or supersede the earlier value, or leave a stale result on the record?
• Out-of-order and duplicate messages: an amendment arriving before the original, or the same message delivered twice. Does the record end up correct?

The macron case deserves special weight in NZ. A name like Māori or Ngāti that loses its macron in transit is both a data-quality defect and a respect-and-accuracy issue, and character encoding is a classic place for it to break silently between two systems.

8 Building Interoperability Test Cases

A strong interoperability test case names the standard and profile, asserts on specific segments or fields, and states the expected receiver behaviour — including rejection for the bad cases. The assertion is at the field level, not “the result appeared.”

Here is a worked test case for the Tui Diagnostics decimal bug:

Notice what makes this catch the Hook bug: it asserts on specific fields (OBX-5 and OBX-6) and their exact values, it includes the decimal boundary as the primary case with negative variants, and it demands the field-level stored values plus a validator report as evidence — not a screenshot of a result on a screen. The standard and profile are named at the top, so the reviewer knows the contract being tested.

9 Common Mistakes

10 Now You Try

Three graded exercises across HL7 v2, FHIR, and conformance. Write your answer, run it for AI feedback, then compare to the model answer.

There are at least four real defects here; any three well-explained earns full marks.

1. PID NHI is empty — the NHI component before ^^^NHI is blank, so the patient has no reliable identifier. Impact: the result may be matched by name+DOB and land on the wrong patient (the Lesson 1 risk). A profile requiring the NHI would reject this.

2. OBX-2 declared TX (text) for a numeric result — the value type is TX but the value is a quantitative measurement. Impact: a numeric glucose is stored as free text, so it cannot be trend-graphed, range-checked, or reliably parsed; it should be NM.

3. Value and units merged in OBX-5 — "7.8 mmol/L" sits in the value field with OBX-6 (units) empty, instead of value 7.8 and units mmol/L in their own fields. Impact: the value will not parse as a number; this is the Tui-style value/units confusion.

Bonus: status flag P (preliminary) — the result is preliminary, not final (F). Impact: if the receiver treats it as final, a clinician may act on a result still subject to change; the amended/final version must supersede it.

The trap: this message still "arrives" and shows a glucose on screen, so an arrival-only test passes it.

Test ID: INT-FHIR-018

Standard / profile: FHIR R4 Observation, NZ lab-results profile (NHI required as patient identifier; recognised unit and test code systems)

Clinical risk: Corrupted/mis-mapped result or wrong patient reference

Field(s) under test: Observation.status, Observation.subject (Patient reference / NHI), Observation.valueQuantity (value + unit + unit code), Observation.code (test coding), Observation.referenceRange

Pre-conditions: Receiver loaded with the agreed NZ profile and validator; a known Patient resource with a valid NHI exists.

Action: POST a final Observation with valueQuantity value 14.5 unit mmol/L, subject referencing the known patient's NHI, and a valid test code.

Expected result: 1) Resource validates against the named profile with no errors. 2) Stored value is exactly 14.5 with unit mmol/L (value and unit not merged). 3) subject resolves to the correct Patient by NHI. 4) status final is stored as final; referenceRange round-trips.

Negative variants: missing NHI (must be rejected per profile); status preliminary (must not be treated as final); value as a string (must be rejected); subject referencing a non-existent Patient (must be rejected, not stored against a guess).

Evidence required: the sent resource; the validator report against the profile; the stored field values; the resolved patient reference.

Traceability: Interop risk register IR-02 (mis-mapped value/unit) and IR-03 (wrong patient reference).

What makes it strong: it names the standard and the NZ profile, asserts on specific fields and their exact values, validates against the profile (not just base FHIR), includes negative variants with required rejections, and demands field-level evidence plus the validator report — not "the result showed up".

BR-01 | Verifies: OBX value and units map to FHIR valueQuantity correctly | Acceptance criteria: OBX-5 value (incl. decimals like 14.5) maps to valueQuantity.value exactly and OBX-6 maps to valueQuantity.unit; value and unit never merged | Evidence required: source HL7 message; emitted FHIR resource; field-by-field comparison

BR-02 | Verifies: the PID NHI maps to the FHIR patient reference/identifier | Acceptance criteria: the NHI in PID becomes the correct Patient reference/identifier in the Observation.subject; no name+DOB fallback | Evidence required: source PID; emitted subject/identifier; resolution to the correct Patient

BR-03 | Verifies: a missing required field is handled, not silently emitted | Acceptance criteria: an HL7 message missing a profile-required field (e.g. NHI or status) produces a rejection/error, not a partial FHIR resource | Evidence required: the deficient source message; the rejection/error; confirmation no resource was stored

BR-04 | Verifies: a Māori name with macrons round-trips intact | Acceptance criteria: a name containing ā ē ī ō ū is byte-for-byte preserved from HL7 to the emitted FHIR resource; no mojibake or stripping | Evidence required: source name; emitted name; character-level comparison

BR-05 | Verifies: a status/amendment is reflected correctly | Acceptance criteria: a preliminary result emits status preliminary (not final); a later amendment supersedes the prior Observation rather than duplicating it | Evidence required: source messages (preliminary then amended); emitted status values; the supersede/amend linkage

Strong plans: each case is specific, has a measurable criterion, names concrete evidence, and together they cover value/unit mapping, NHI/patient mapping, a missing required field, macron handling, and status/amendment. Weak plans say "check the translation works" five times — that is the difference being marked.

11 Self-Check

Click each question to reveal the answer.

12 Interview Prep

Real questions asked in NZ QA interviews for health integration roles. Read the model answers, then practise your own version.