The first time you open an HL7v2 message and try to read it with a FHIR developer's eyes, the thing looks like a badly-formatted CSV. Pipes everywhere, cryptic three-letter segment names, encoding characters at the top of the file. It is a real interchange format used in production every day, and it does not disappear when a shop adopts FHIR. Learning to read v2 is the shortest path from FHIR-first to production-integration.
Naming the shape is the discipline. For related walkthroughs, our FHIR / HL7 reference desk collects the surrounding material.
The Shape of a v2 Message
A v2 message is a text file organized into segments separated by carriage returns. Each segment starts with a three-letter identifier (MSH, PID, OBX) and continues with fields separated by pipes. Fields can contain components separated by carets, and components can contain subcomponents separated by ampersands.
The whole hierarchy is: segment → field → component → subcomponent. FHIR developers usually recognize this immediately once the structure is named; the messy appearance is just delimiters. A pass through the site's HL7 v2 segment → FHIR mapping tool looks up specific segments and shows the FHIR equivalent.
The Segments You Meet First
Three segments dominate almost every v2 integration:
- MSH: the header. Every message starts with MSH. It carries the sender, the receiver, the encoding, and the message type.
- PID: patient identifier. Almost every message about a patient carries a PID.
- OBX: observation. Any message carrying a clinical measurement carries OBX segments.
Reading those three well covers most of what production integration teams handle. For the header specifically, MSH segment: the header that decides how the rest is parsed walks through the fields.
Event Types as Verbs
The v2 world uses event types (A01, A02, A03) as verbs. A01 is admit; A02 is transfer; A03 is discharge. The verbs form the message vocabulary and correspond to state transitions in FHIR Encounter or FHIR Patient resources.
For the specific ADT event framing, the ADT event types you meet first in an integration covers the vocabulary. Every integration eventually needs to know these verbs.
The Encoding Characters
The top of every message declares its own encoding characters in MSH-1 and MSH-2. Field separator, component separator, repetition separator, escape character, subcomponent separator. Most implementations use the defaults (|^~\&); some legacy systems use others.
Parsing v2 correctly means honoring the declared encoding characters, not assuming defaults. This is where naive parsers fail on real production traffic.
Escape Sequences Are a Trap
v2 uses escape sequences like \F\ for a literal field separator inside a value. Parsers that split on the delimiter without unescaping produce corrupted results.
Reliable v2 parsing goes through a two-pass approach: first split on segment delimiters, then split each segment on field delimiters, then unescape each field. Skipping the unescape step is where a lot of first-integration bugs live.
FHIR Mapping Is Not Universal
Some v2 fields have clean FHIR equivalents. Some do not. The v2 world carries a lot of implicit context that FHIR expresses more explicitly, and translation always involves some judgment. For the pattern-level framing, HL7v2 to FHIR translation patterns worth memorizing covers the recurring ones.
The Cheatsheet Habit
Every integration team maintains a v2-to-FHIR cheatsheet of some kind. Segment lookups, field mappings, escape rules. Published cheatsheets survive team rotations; institutional cheatsheets do not.
Reading v2 is not glamorous. It is what turns a FHIR-first developer into someone who can actually operate integrations that touch real hospital traffic.
Sources
- HL7 canonical product overview for HL7v2 messaging standard - HL7 canonical product overview for HL7v2 messaging standard, evergreen reference