hl7-2-from-er7-into-json

What it is

Convert HL7 v2.5 messages from ER7 to a typed JSON representation, as a Rust library and command-line tool.

Its XML counterpart is hl7-2-from-er7-into-xml: same ER7 parser, same HL7 v2.5 data-type tables, same message-structure grammars — rendered as JSON instead of the official v2.xml XML.

What it produces

PID|1||241900||TEST^FOUAZ

converts to:

{
  "PID": {
    "PID.1": "1",
    "PID.3": {
      "CX.1": "241900"
    },
    "PID.5": {
      "XPN.1": {
        "FN.1": "TEST"
      },
      "XPN.2": "FOUAZ"
    }
  }
}

Command line

# From a file to stdout
hl7-2-from-er7-into-json samples/orm_o01.hl7

# From stdin, to a file
cat samples/oru_r01.hl7 | hl7-2-from-er7-into-json -o out.json

# Disable message-structure grouping
hl7-2-from-er7-into-json --flat samples/orm_o01.hl7

# Compact (single-line) JSON instead of pretty-printed
hl7-2-from-er7-into-json --compact samples/orm_o01.hl7

Input may hold one message, several messages, or an HL7 batch file (FHS/BHS envelopes are dropped); each message becomes one independent JSON document.

Library

let er7 = "MSH|^~\\&|hphis||EPIC||20131011093851||ORM^O01|14AAACVDD|P|2.5\r\
           PID|1||241900||MEDIANO^FOUAZ\r\
           ORC|NW|ORD1";

let json = hl7_2_from_er7_into_json::convert(er7)?;

use hl7_2_from_er7_into_json::{Options, convert_with_options};

let json = convert_with_options(er7, &Options { flat: true, compact: true })?;

convert and convert_with_options return Result<String, Hl7Error>; an Err only ever means the message has no usable MSH header. Everything below that always converts.

What it does

• ER7 parsing at every level, and dynamic delimiters read from MSH-1 and MSH-2 rather than hardcoded.
• Escape sequences: \F\ \S\ \T\ \R\ \E\ decode to the delimiter characters and \Xhh..\ decodes hex bytes. Unlike XML, decoded text needs no further escaping for &, <, > in JSON.
• Typed key names from the same tables the XML sibling uses — producing "PID.5": {"XPN.1": {"FN.1": "TEST"}} style nesting.
• Repetition and repeating groups become JSON arrays: a repeating field, repeating segment, or repeating group collapses same-named siblings into one array under one key — real JSON structure, not XML's repeated-sibling-tag trick.
• OBX-5 variable typing: the value type declared in OBX-2 names the OBX-5 keys.
• HL7 null: the explicit null "" becomes JSON null; a field with no value at all is simply omitted.
• All scalars are JSON strings, never numbers or booleans — HL7 numeric text (leading zeros, explicit signs, trailing precision) is never silently coerced.
• Message-structure groups for ACK, ADT_A01 (also used by ADT^A04/A08/A13), ORM_O01, and ORU_R01. The root key comes from MSH-9.3 when present, otherwise from MSH-9.1 and MSH-9.2.

Fallback behavior

• A message whose segment sequence does not fit its declared structure renders with all segments flat under the root key.
• Fields of unknown segments, and fields beyond the built-in tables, use positional generic keys: "ZDS.1", "ZDS.1.1", and so on.

Limitations

• Only the four message structures listed above are grouped; everything else renders flat.
• A segment name that repeats non-adjacently is grouped at its first occurrence, so segments that sat between the two occurrences lose their place in the sequence — a JSON object cannot carry the same key twice. Adjacent repeats, and repeats inside a group the grammar knows, are unaffected. This is the one place the JSON mapping loses information the XML mapping keeps.
• ORM_O01 order detail supports the common OBR choice; RQD/RQ1/RXO/ODS/ODT detail segments cause a flat rendering.
• Formatting escape sequences are preserved as literal text.
• A key that can repeat is a bare value when it occurs once, and an array only when it occurs more than once — consumers that need a uniform shape must normalize that themselves.

Related crates