Skip to content
Healthcare data guides

How to use an HL7 viewer to read, validate and parse HL7 v2 messages

Published 3 min read

An HL7 v2 message looks like a block of vertical bars and carets. It is compact for machines and hard for people. An HL7 viewer turns it into something readable. Convertada's HL7 Message Viewer shows a message segment by segment in your browser, and three more tools validate it, parse it and convert it to JSON.

Use test data only

The tools run in your browser and do not store or send your messages. Even so, paste synthetic or properly de-identified messages unless you are authorised to handle real data and your device and network are secure. No claim of HIPAA, GDPR or other regulatory compliance is made.

How an HL7 v2 message is organised

A message is a list of segments, one per line, each starting with a three-letter name such as MSH (the message header), PID (patient identification), PV1 (the visit), OBR (an order or request) and OBX (an observation result). Fields are separated by |, components by ^ and repetitions by ~. Field numbers, such as PID-5 for the patient name, tell you what each position means.

HL7 Message Viewer

  1. Open the HL7 Message Viewer.
  2. Paste a message, drop a file or load an example.
  3. Read the message segment by segment, with field numbers and components. Key and required fields are marked, and each kind of segment has its own colour.
  4. Use Expand all and Collapse all, search segments and values, and copy a single segment.

HL7 Message Validator

The HL7 Message Validator checks structure: delimiters, the MSH segment, message type and version, segment structure and order, required fields and basic data types. It lists findings with a severity, a location and a suggested correction. For example, it tells you when the message does not start with MSH, when MSH-9 does not follow the TYPE^TRIGGER pattern or when a timestamp is not a valid HL7 date and time.

It does not validate a site or implementation profile, and it is tested with versions 2.3.1, 2.4 and 2.5.1. A valid result means the structure is sound, not that the content fits your local interface.

HL7 Message Parser

The HL7 Message Parser groups the values into sections: message, patient, visit, orders and observations. It only shows what is present in the message and infers nothing. You can download the parsed result as JSON.

HL7 to JSON Converter

The HL7 to JSON Converter offers two modes:

  • Complete (lossless): every segment, field, repetition, component and sub-component.
  • Readable summary: common fields of each segment under readable names, showing only present values.

A reading workflow

  1. Validate the message first, to find structural problems.
  2. Open it in the viewer to understand what each field holds.
  3. Use the parser for a patient-level overview.
  4. Export JSON when another tool needs the data.
  5. For a FHIR version of the same message, see converting HL7 to FHIR.

Common problems and how to fix them

"The message must start with an MSH segment." Remove anything before MSH, such as extra blank lines or header text.

Segments run together. HL7 separates segments with a carriage return. If copying lost the line breaks, put each segment on its own line.

A field looks empty. The message may not contain it. The parser shows only present values.

The validator complains about the version. Check MSH-12.

Frequently asked questions

Is the HL7 viewer free?

Yes, with no sign-up.

Are my messages uploaded?

No. They stay in your browser. Use test data anyway.

Which message types can I read?

The viewer reads HL7 v2 messages generally. Structure-specific checks cover common types, and unknown types get general checks only.

Can I check FHIR as well?

Yes, see the FHIR validator guide.

Conclusion

Validate, view and parse, and export JSON when you need it. Used with synthetic data, these tools make HL7 v2 much easier to understand.