HL7 v2 reference and tool guide

Getting started

The HL7 Inspector reads one HL7 v2 message at a time.

1. Paste a message, or choose a sample (ADT, ORM or ORU, all fictional). Use synthetic or de-identified data only.
2. Choose Inspect Message. The text is sent to this site's server, parsed in memory and returned. Nothing is stored or logged.
3. Pick a segment to see its fields, then a field to see its repetitions, components and subcomponents. Each value has a copyable path.
4. Use the search box to find segment IDs, paths (such as OBX-3) or values.

Limits: messages up to 20 KB; one message at a time; structure only.

How the Inspector parses

The Inspector is a structural parser. It is not a conformance validator: it does not check data types, required fields, code tables, cardinality or any implementation guide. What a given field means depends on the HL7 version and your local profile, so the Inspector shows positions and values and does not label fields.

• Delimiters come from the message. MSH-1 is the character after MSH; MSH-2 holds the component, repetition, escape and subcomponent characters (an optional fifth character is read as the truncation character). They must be single-byte printable ASCII, not letters or digits, and all different.
• MSH numbering. The field separator is MSH-1 and the encoding characters are MSH-2, so the first value after them is MSH-3. MSH-1 and MSH-2 are shown but never split.
• Empty values are kept. PID||||X has X in PID-4, and trailing empty fields are counted. Nothing is trimmed or reordered, so positions never shift.
• Line endings. CR, LF and CRLF all end a segment. Mixed endings are accepted with a warning. Blank lines are skipped with a warning.
• Escape sequences such as \F\ are shown exactly as received, not decoded. An odd number of escape characters in a field produces a warning.
• Framing. A UTF-8 byte-order mark and MLLP start/end bytes around the message are ignored (with a warning). Nothing inside the message is changed.

Errors and warnings are separate. An error means the message could not be parsed (for example, it does not start with MSH or the delimiters are invalid), so no parsed output is shown. A warning means the message was parsed but something looks unusual, such as an unexpected segment ID or an empty MSH-9. A message with no warnings is not thereby valid.

Path notation

A plain path such as OBX-3 refers to the first OBX. Use the indexed form to point at a later one.

HL7 v2 basics

An HL7 v2 message is plain text made of segments. Each segment is one line and starts with a three-character ID, such as PID. Segments end with a carriage return character. Inside a segment, fields are separated by a field separator (normally |). Fields can contain components, and components can contain subcomponents. A field can also repeat.

A short synthetic example:

MSH|^~\&|SENDAPP|SENDFAC|RECVAPP|RECVFAC|20261010093000||ADT^A01^ADT_A01|MSG00001|P|2.5.1
EVN|A01|20261010093000
PID|1||000123^^^SENDFAC^MR||DOE^JANE^Q||19800101|F|||123 SAMPLE ST^^EXAMPLEVILLE^ZZ^00000^USA||^PRN^PH^^^555^0100
PV1|1|I|WARD1^101^A^SENDFAC||||1234^SAMPLE^DOCTOR^A

The first segment, MSH, declares the delimiters used in the rest of the message, so a reader should take them from MSH rather than assume them.

Delimiters

These are the usual defaults. The message itself is the authority: MSH-1 holds the field separator and MSH-2 holds the other four characters.

Field addresses

A value is addressed as SEGMENT-field.component.subcomponent. Fields are numbered from 1 in the order they appear after the segment ID. The MSH segment is a special case: the field separator itself counts as MSH-1, so the first field after the separator is MSH-2, and the first field after the encoding characters is MSH-3.

Field meanings depend on the HL7 version. The table above reflects the v2.5.1 sample; check the specification for the version you use.

Common segments

Common message types

MSH-9 holds the message type and trigger event, for example ADT^A01.

Escape sequences

When a delimiter character must appear inside a value, HL7 v2 uses an escape sequence that starts and ends with the escape character (normally \). The Inspector preview shows these sequences as they appear in the message and does not decode them.

Message Diff Available

Message Diff compares the text of two messages. It reports segment order, the number of segments per ID, and field, repetition, component and subcomponent values. It cannot tell you whether two messages mean the same thing: 1 and 01 differ here, and identical text is not proof of equivalence.

• Repeated segments are compared by occurrence. The 2nd OBX of message A is paired with the 2nd OBX of message B. Every result shows both occurrence numbers and indexed paths such as OBX[2]-5.
• Aligned pairing Experimental pairs repeated segments by similarity instead (at least half of their non-empty fields must match), which copes with an inserted or removed OBX. It is a heuristic and falls back to occurrence pairing for very large groups.
• Moved segments: segments whose relative order differs are flagged. Moved segments are never reported as identical.
• Empty versus absent: an empty value and a missing one are different in the details ((empty) vs (absent)). Trailing empty fields that differ are flagged on the segment.
• Nothing is normalised: no trimming, case folding or number parsing.
• Ignore rules (Pro plan): MSH-7 ignores a field, PID-5.2 a component, NTE a whole segment. Ignored differences are hidden but counted, and a result that is clean only because of ignore rules says so.

HL7-to-JSON format Available

Schema identifier hl7-json/1. The formal JSON Schema is hl7-json-1.schema.json. Every document is checked against it by the automated tests.

What is preserved: segment order, repeated segments, empty values and their positions, trailing empty fields (through fieldCount), repetitions, components and subcomponents, and the exact text of every value. Rebuilding the segments from the JSON reproduces the original text.

Limitations:

• No field names or descriptions, because they depend on the HL7 version and your profile. Positions are the stable identifiers.
• Every value is a string. Numbers, dates and codes are not converted, so "007" stays "007".
• Escape sequences such as \F\ are not decoded.
• One message per document. Delimiters are single-byte ASCII.
• It is a structural representation, not an HL7 FHIR or HL7 XML mapping, and it is not a validation result.
• With includeEmpty: false, empty fields are omitted from fields but positions stay explicit and fieldCount still records the full length.
• Output can be many times larger than the message (the compact style is smaller). Very large or very dense messages may be refused if they exceed the server's memory limit.

Mirth Connect helper Experimental

The Mirth helper turns a chosen segment, field, repetition, component and subcomponent into an illustrative reference and a starter JavaScript snippet. As a general pattern, PID-5.1 is written like this:

var familyName = msg['PID'][0]['PID.5']['PID.5.1'].toString();

• Review and test everything. Output is illustrative. Element names and behaviour depend on your Mirth Connect version and channel settings (for example the HL7 v2 strict parser and repetition handling). Test in your own non-production environment with synthetic data.
• Assumptions are listed with every result: non-strict parser, repetitions handled, zero-based E4X indexes (HL7 occurrences and repetitions are one-based).
• No execution, no connection. The tool only generates text. It never runs your input and never contacts a Mirth server. Values you type appear only inside escaped string literals.
• The full template set (find a segment by code, lookup tables, a safe-read helper) is part of the Pro plan; basic templates are available to every account.
• What a field means depends on your HL7 version and profile. The helper does not know, and does not check that a field exists.

This project is independent and is not affiliated with or endorsed by NextGen Healthcare.

Roadmap

The roadmap is a plan, not a commitment. There are no release dates.

• Phase 1: website foundation, documentation, proposed pricing, contact form.
• Phase 2: the HL7 Inspector with a structural parser, copyable paths and search.
• Phase 3: free accounts, login, password reset, a dashboard with plan and usage, and server-side usage limits.
• Phase 4 (this build): Message Diff, HL7-to-JSON and a Mirth Connect helper, with plan-based limits enforced on the server.
• Later: saved snippets, multi-message files, email verification, paid plans and checkout. Each is subject to change after feedback.