All processing happens locally in your browser. Your HL7 messages and PHI never leave your device. HIPAA-compatible.
Drop .hl7 or .txt file here, or paste below
Converting…
Paste your HL7 v2.x message into the text area, or drag-and-drop a .hl7 / .txt file onto the drop zone.
Choose the output mode: Simplified (flat field keys like PID.5) or HAPI-style (named data-type component keys like PID.5.1).
Toggle 'Pretty-print' to add 2-space indentation, or 'Unescape HL7 sequences' to resolve \F\, \S\, and \T\ escapes in the output.
Click 'Convert to JSON'. Review the side-by-side view — HL7 source on the left, JSON on the right.
Copy the JSON to your clipboard or download it as a .json file. Use 'New Conversion' to process another message.
Simplified mode produces readable flat keys (PID.5, OBX.5) ideal for quick inspection. HAPI-style mode emits named component keys (PID.5.FN.1) that mirror the HAPI Java library's JSON serialization — useful when comparing against systems that output HAPI JSON.
Handles all standard segment types: MSH, PID, PV1, OBR, OBX, ORC, NTE, NK1, DG1, IN1, GT1, MRG, and more. Parses repeated fields (~ delimiter), components (^ delimiter), and subcomponents.
Optionally resolves HL7 escape sequences: \F\ → |, \S\ → ^, \T\ → &, \R\ → ~, \E\ → \. Keeps the raw encoded form when unescape is off.
After conversion, view the original HL7 source and resulting JSON in adjacent read-only panes so you can verify field-by-field that the conversion is correct.
All parsing runs in your browser. Your HL7 messages and any PHI they contain never leave your device. HIPAA-compatible and safe for hospital and clinic workstations.
Unlike cloud-based converters, this tool runs entirely in your browser. No message content, patient identifiers, or PHI is transmitted. You can use it on an air-gapped workstation or behind a hospital firewall without risk.
Simplified mode is best for quick field lookups and building lightweight ETL rules. HAPI-style is best when you are integrating against a Java HAPI-based system and need to match its JSON output format — saves re-implementation work.
HL7 v2.x messages in production use inconsistent carriage returns, missing trailing fields, and repeated segments. The parser handles all these edge cases so you get valid JSON even from non-ideal inputs.
Pair with the HL7 Viewer for segment-level inspection, the Segment Browser for field definitions, and the ACK Generator to simulate responses. A complete HL7 workflow without leaving the site.
HL7 v2.x is a pipe-delimited, positional text format designed in the late 1980s. Its structure is precise but opaque to modern tooling: most REST APIs, NoSQL stores, ETL pipelines, and analytics platforms expect JSON. Converting HL7 messages to JSON unlocks them for SQL queries, JavaScript processing, Python data analysis, and storage in document databases like MongoDB or Elasticsearch — without modifying downstream systems.
An HL7 v2.x message is a carriage-return-delimited sequence of segments. Each segment starts with a three-character name (MSH, PID, OBX). Fields within a segment are separated by the field separator character (usually |). Fields may contain components separated by ^, subcomponents separated by &, and repetitions separated by ~. The MSH segment's first two fields establish these encoding characters, so a compliant parser reads them dynamically rather than hard-coding |^~\&.
In simplified mode, the converter emits one JSON object per segment occurrence, with field values keyed as SEG.N (e.g., PID.5 for the patient name field). Single-value fields become strings; fields with components become arrays. This format is easy to index in any document store and straightforward to query with jq or Python's json module. It trades component-key verbosity for readability.
HAPI (HL7 Application Programming Interface) is the most widely used Java library for HL7 v2.x processing. When HAPI serializes a message to JSON, it names the components using the HL7 data-type descriptor — so rather than PID.5[0] you get {"FN":{"surname":"Smith"},"given":"John","middleInitialOrName":"A"}. Systems that emit or consume HAPI JSON (Epic Bridges, Rhapsody channels, Ensemble adapters) produce or expect this shape. If you are building a system that must match HAPI's output, selecting HAPI-style mode saves hours of re-implementation.
HL7 segments can repeat — an ORU^R01 result message may have dozens of OBX segments, each carrying a different lab measurement. The converter assigns an occurrence index to repeated segments so OBX[1], OBX[2], OBX[3] stay distinct in the JSON output. Field repetitions (multiple values within one field, separated by ~) are preserved as arrays rather than collapsed into the first value.
HL7 v2.x uses a backslash escape mechanism to represent the five reserved encoding characters within field values: \F\ for the field separator (|), \S\ for the component separator (^), \R\ for the repetition separator (~), \T\ for the subcomponent separator (&), and \E\ for the escape character itself (\). When the unescape option is enabled, the converter resolves these to their literal characters in the JSON output. Keep it disabled when you need a round-trip-safe JSON representation that can be converted back to HL7 without data loss.
In HL7 v2.x, an empty field (||) means "not provided" and a double-quote field (|""|) means "explicitly delete the previous value". The converter maps empty fields to JSON null to distinguish them from absent fields — a difference that matters when using the JSON to perform database updates where a null should overwrite an existing value but absence should leave it unchanged.
HL7 v2.x messages are typically small — a few hundred bytes to a few kilobytes. Even a complex ORU^R01 with 50 OBX segments converts in under a millisecond in any modern browser. Batch files (multiple messages concatenated in a single file) are not yet supported by this tool, which expects a single message per conversion. For batch processing, split the file on MSH lines and convert each message separately.
Common integration patterns that benefit from HL7-to-JSON conversion include: feeding HL7 demographics (PID, PV1) into a REST-based master patient index; populating Elasticsearch with lab results (OBX) for analytics; testing FHIR conversion logic by first parsing the source HL7 message to JSON then mapping JSON paths to FHIR resource fields; and logging messages in structured form to CloudWatch or Datadog where pipe-delimited text is not searchable.
For integration purposes, JSON is typically an intermediate form that does not need to reconstruct the original HL7 message. However, if round-trip fidelity is required — generating HL7 from JSON — you must preserve null fields (do not omit them), preserve repetitions as ordered arrays, and keep escape sequences encoded (disable the unescape option). Simplified mode is less suited for round-trips because it omits component names; HAPI-style mode preserves enough structure for reconstruction with a compliant library.
In production integration programs, HL7-to-JSON conversion is often the bridge between legacy feeds and modern observability or API layers. Teams use the JSON output to feed staging databases, compare pre-transform and post-transform payloads in automated tests, and create searchable structured logs for incident response. Because the output is generated locally, analysts can validate mappings with realistic messages before copying the resulting JSON into ETL jobs, transformation specs, or FHIR conversion notebooks.
The converter is also useful as a contract clarification tool when multiple teams disagree about what a field means. Instead of debating pipe counts in email threads, you can inspect the exact parsed structure, confirm how repetitions and components are being read, and document the agreed JSON path that downstream consumers should use. That reduces ambiguity in interface tickets and makes it easier to align HL7 analysts, backend engineers, and data teams around the same message model.
An analyst flattening repeating fields for a lab dashboard pastes a synthetic ORU^R01 with a dozen OBX segments in simplified mode, confirming each result gets its own indexed entry rather than overwriting the last one — the exact failure mode of a naive line-by-line parser that assumes one OBX per message.
An engineer matching a Java-based interface engine's output pastes the same synthetic message in HAPI-style mode and compares the resulting component-named keys against what the engine actually emits, catching a mismatched data-type assumption before writing a single line of mapping code.
A third workflow tests round-trip safety before building a FHIR conversion pipeline. Converting a synthetic message with the unescape option off, then confirming every null field, repetition, and escape sequence survived intact in the JSON, verifies the output can safely be transformed back to HL7 later if a downstream system needs the original wire format.
This is a structural transform, not a validator — it converts whatever segments and fields it finds into JSON, but it does not check that required fields are present or that a message conforms to a specific message-type schema. It also converts one message at a time; a file containing multiple concatenated messages needs to be split on MSH boundaries first; batch conversion is not built in. And because HAPI-style mode's data-type keys come from a fixed table of common types (XPN, XAD, CX, CWE, and similar), an uncommon or custom data type falls back to a generic key rather than a fully named one — treat that as a signal to double-check the field manually rather than assume the naming is complete.
| Aspect | Simplified mode | HAPI-style mode |
|---|---|---|
| Key format | Flat, e.g. PID.5 | Named components, e.g. PID.5.FN.1 |
| Best for | Quick lookups, lightweight ETL | Matching a Java/HAPI-based system's own JSON |
| Round-trip safety | Limited — component names are lost | Better — enough structure to reconstruct HL7 |
An HL7 message being converted for a downstream system is exactly the kind of data HIPAA classifies as protected health information — patient name, MRN, diagnoses, lab values. Because this converter parses and serializes entirely in your browser's own JavaScript, an integration engineer can convert a real production message on a hospital workstation and know the content never crossed the network as part of the conversion step, which matters when the resulting JSON is destined for a staging database or a test harness rather than a production system with its own controls.
Conversion is usually one stop on a longer path. Inspect a message's segments and fields first in the HL7 Viewer, look up an unfamiliar field's definition in the HL7 Segment Browser, then convert the message here once you're confident you understand what every field means. That order keeps the JSON output honest about what the source message actually contained.
No. All processing runs in your browser using JavaScript. No message content, PHI, or patient data is transmitted. You can verify this in your browser's developer tools network tab.
Simplified mode keys fields as SEG.N (e.g., PID.5) and represents components as arrays — easy to read and query. HAPI-style mode uses named data-type component keys (e.g., PID.5.FN.1) that mirror the HAPI Java library's JSON output, which is useful when integrating with Java-based systems.
HL7 v2.x (v2.1 through v2.9). The parser reads encoding characters from MSH-1 and MSH-2, so it handles any v2.x version without requiring a version selector.
Not yet. The tool expects a single message per conversion. For batch files, split on the MSH line and convert each message individually.
It resolves HL7 backslash escape sequences to their literal characters: \F\ → |, \S\ → ^, \T\ → &, \R\ → ~, \E\ → \. Keep it off if you need a round-trip-safe JSON that can be re-encoded back to HL7.
Repeated segments (e.g., multiple OBX in an ORU result) are emitted as separate objects in the segments array with an 'occurrence' counter. Simplified mode also groups them by segment name with indexed keys.
Empty fields (||) appear as JSON null, and empty components of non-empty fields appear as null array entries. This preserves the semantic distinction between 'not provided' and 'absent'.
HAPI-style mode preserves enough structure for reconstruction with a compliant library. Simplified mode loses component names, so round-trip reconstruction is not reliable. Disable the unescape option to keep escape sequences intact.
The tool's privacy design (local processing, no data transmission) is consistent with HIPAA's technical safeguard requirements. However, compliance also depends on your workstation security, browser configuration, and organizational policies — consult your compliance officer.
The parser checks for a valid MSH segment and correct encoding characters. If validation fails, an error message is shown explaining what went wrong. No partial JSON is emitted to avoid silently incorrect output.
Learn when HL7-v2-to-JSON should sit in front of FHIR ingestion pipelines, what the JSON must preserve, and how to avoid data loss during modernization.
Read more →
Learn how to convert HL7 v2.x messages to JSON with simplified or HAPI-style output, covering field mapping, escape sequences, and integration patterns.
Read more →
Learn how to map HL7 PID and PV1 segments to JSON without losing identifiers, visit context, repetitions, or null semantics in ADT pipelines.
Read more →