hl7-2-from-xsd-into-json-dictionary

What it is

HL7 publishes v2.xml as schemas. hl7-2 reads a dictionary, because one dictionary format can serve every release and every local dialect from a single build. This crate is the bridge: it turns the schemas a site already has into the dictionary the crates already read.

cargo install hl7-2-from-xsd-into-json-dictionary

Why you would want one

The dictionary it writes carries cardinality as well as data types — each field's minOccurs and maxOccurs become required and repeats.

What a schema directory looks like

Three base files that every message shares, plus one file per message structure:

schemas/paris/
  2_5_1_types.xsd      composite data types and their components
  2_5_1_fields.xsd     every SEG.n element and the data type it carries
  2_5_1_segments.xsd   each segment's field list, with cardinality
  ADT_A05.xsd          one abstract message structure each
  ADT_A39.xsd

The 2_5_1 prefix is discovered from a structure file's <xsd:include>, so the directory can be named for the sending system rather than for the HL7 release.

Use

hl7-2-from-xsd-into-json-dictionary schemas/paris -o paris.json

Two things the schemas cannot say

hl7-2-from-xsd-into-json-dictionary schemas/paris \
    --name paris \
    --alias ADT_A28=ADT_A05 \
    --alias ADT_A31=ADT_A05 \
    --inherits 2.5 \
    -o paris.json

--alias CODE_TRIGGER=STRUCTURE

Which trigger events arrive carried by another message's structure. A directory holds ADT_A05.xsd but never says that an ADT^A28 is one, so that mapping has to come from you.

--inherits 2.5

Layers the generated document over a bundled release instead of leaving it to stand alone. Without it, everything the schemas do not describe reads positionally.

--name

What the dictionary calls itself, which is what appears in diagnostics.

Reading the result

let text = std::fs::read_to_string("paris.json")?;
let dictionary = hl7_2::Dictionary::from_json(&text, "paris")?;

assert_eq!(dictionary.field_type("PID", 3), Some("CX"));
assert!(dictionary.field_cardinality("PID", 3).repeats);

Or hand it straight to a converter:

hl7-2-from-er7-into-xml --dictionary paris.json --schema-shape message.hl7

As a library

use hl7_2_from_xsd_into_json_dictionary::{Options, convert_directory};

let document = convert_directory("schemas/paris".as_ref(), &Options::default())?;
std::fs::write("paris.json", document.to_json())?;

Dependencies

One: hl7-2-xml-lite-helper, the small dependency-free XML reader shared with hl7-2-soap and hl7-2-from-xml-into-er7, re-exported here as xml so a caller can name xml::Element without adding its own dependency on it.

Reading XSD needs an XML reader; writing a dictionary needs a JSON writer, which is small and specific enough to the one shape involved to live here rather than pull in a general-purpose one. hl7-2 itself is a dev-dependency only, used to check that a generated dictionary loads — it is not needed to build this crate.

Related crates