Specifications

What a spec is here

Each crate's spec/index.md is a numbered, section-by-section statement of every rule the crate implements: how a delimiter is resolved, what a name falls back to, which inputs are errors and which are warnings, what the command line does with each flag. It is written to be cited — “spec/index.md §4.2” is a real address you can quote in a bug report.

The specifications, by crate

Core

hl7-2 — crate page

HL7 v2 itself: parse, navigate, validate, modify, render.
§2 the ER7 layer · §3 the dictionary · §4 generic mode · §5 schema mode · §6 struct mode · §7 mutation and building · §8 validation · §12 command line

hl7-3 — crate page

HL7 v3: the RIM backbone, the data types, the message envelope.
§1 scope — read before filing a bug · §2 the XML layer · §3 data types · §4 the RIM backbone · §5 the three-level envelope · §6 vocabulary validation as future work

Transports

hl7-2-mllp — crate page

MLLP: HL7 v2 framed on a TCP stream.
§2 the protocol · §3 framing · §4 streaming · §5 acknowledgement · §6 transport · §7 features

hl7-2-soap — crate page

HL7 v2 carried in a SOAP envelope over HTTP.
§3 the envelope · §4 what the body carries · §5 faults · §6 responses · §7 WSDL

hl7-3-soap — crate page

HL7 v3 carried in a SOAP envelope over HTTP.
§3 the envelope · §4 what the body carries · §5 faults · §6 responses · §7 WSDL

Format conversions

hl7-2-from-er7-into-xml — crate page

ER7 → the official v2.xml XML representation.
§2 ER7 parsing · §3 message-structure grouping · §4 XML naming and rendering · §4a schema mode · §5 batch input · §8 command line

hl7-2-from-xml-into-er7 — crate page

v2.xml XML → ER7.
§2 XML parsing · §3 reconstructing the value tree · §4 segment- and field-level special cases · §5 fallbacks and limitations

hl7-2-from-er7-into-json — crate page

ER7 → typed JSON.
§0 relationship to the XML sibling · §2 ER7 parsing · §3 grouping · §4 JSON key naming · §5 batch input · §8 command line

hl7-2-from-json-into-er7 — crate page

Typed JSON → ER7.
§2 JSON parsing · §3 reconstructing the value tree · §4 segment- and field-level special cases · §5 fallbacks and limitations

Tooling and helpers

hl7-2-from-xsd-into-json-dictionary — crate page

HL7 v2.xml XSDs → the JSON dictionary hl7-2 reads.
§2 input · §3 what is read, and what it becomes · §4 what the schemas cannot say · §5 output · §8 command line

hl7-2-xml-lite-helper — crate page

The small, dependency-free XML reader this family shares.
§2 why it exists, and why the name · §3 reading · §4 writing · §6 what this is not

The crates with no spec, and why

• hl7 — a thin re-export (pub use hl7_2 as v2;) with nothing normative of its own to state. Read hl7-2's spec and hl7-3's instead.
• hl7-2-derive — macro behavior is documented in the crate's own README and, normatively, in hl7-2's spec §6 (struct mode).
• hl7-3-derive — macro behavior is documented in the crate's own README and in hl7-3's typed module, rather than as a spec of its own.

How to read them together

The two forward conversion specs (ER7 → XML and ER7 → JSON) are deliberately kept consistent with each other, and each one's §0 says exactly where they are meant to diverge: JSON uses real arrays and real null; XML follows v2.xml's element and attribute constructs. Reading one tells you most of the other.

Each reverse spec documents in its own §1.1 why it needs no HL7 v2.5 data-type dictionary at all: every element or key name its forward counterpart writes already carries its own position, so reversing the conversion is a purely structural, position-based rebuild. That is also why the reverse crates are so much smaller than the forward ones.

The workspace's own specs

Several specs sit outside any crate, because what they state is true of the whole workspace rather than of one member. Eighteen today. The spec is the normative version in every case; the entries below summarise them and link back.

spec/conformance/index.md

What “supports HL7 v2 releases 2.1 through 2.9” means, exactly — the segments, types, and structures by name, and what happens outside them. Summarised at Conformance.

spec/phi/index.md

What these crates do with protected health information, what they never do, and where a value can escape into a log. Summarised at Patient data.

spec/benchmark/index.md

How performance is measured, what the published figures mean, and what they are not evidence of. Summarised at Benchmarks.

spec/rust-msrv-n-minus-2/index.md

The minimum supported Rust version policy every member pins to. See Versions and compatibility for what it means in practice.

spec/schema-data-provenance/index.md

Where the bundled dictionary data in hl7-2/schemas/*.json came from, traced as far back through git history as the trail goes — no HL7® file is vendored anywhere in this workspace.

spec/rust-fuzz/index.md

Why the three crates with fuzz targets keep them outside the main Cargo workspace — each declares its own empty [workspace] — so fuzzing never pulls the MSRV floor onto a nightly-only toolchain.

The six above are about what the crates do. The twelve below are about how this repository runs itself — its own practice, not the code's behavior — but the same rule applies: the spec is the source of truth, and a root document that disagrees with one is the bug.

spec/hl7-trademarks-fair-use/index.md

HL7®'s own fair-use rules for its word marks, quoted verbatim rather than paraphrased, and what this project does to follow them — the disclaimer, ® on first use per page, and the “HL7® FHIR® standard” naming. Summarised at TRADEMARKS.md.

spec/professionalization/index.md

What “professional” means for this repository, binding the maintainer as much as any contributor — a checked box in tasks.md means verified, a self-declared gap in SECURITY.md or MAINTAINERS.md is a promise, and a countable claim is measured before it is written.

spec/docs-budget-and-links/index.md

A size budget and a link-integrity rule binding every markdown document this repository tracks, checked by bin/check-docs in CI. Its first run found nine broken links in a stray draft the same day it was adopted.

spec/serial-comma/index.md

English-language prose in this workspace uses the serial comma. That is the whole rule.

spec/special-files-for-public-repos/index.md

The canonical list of root-level files a public repository in this family carries — README.md through AI_STATEMENT.md — and, as of this workspace, a status section naming which ones exist here and which do not yet.

spec/dependabot/index.md

Turns on GitHub's Dependabot security updates and a scheduled .github/dependabot.yml for update pull requests.

spec/free-open-source-funding/index.md

What funding channels this project intends to set up — GitHub Sponsors, Open Collective, a FUNDING.yml — and the other root documents that need to agree with it.

spec/trusted-publishing/index.md

Why crates still publish with a long-lived API token today, and the OIDC-based Trusted Publishing this project intends to adopt once it is production-ready across every forge and destination it uses.

spec/agent-skills/index.md

The repository top-level Agent Skills folders — hl7-skill for end users working with HL7® concepts and messages, hl7-rust-maintainer-skill for contributors changing this repository itself. Summarised at Agent skill and Maintainer skill.

spec/llms-json-and-llms-txt/index.md

The root llms.json/llms.txt AI-guidance files — a curated map of this workspace's most important content for language models — and why the site's own copies under static/ rewrite the links rather than repeating the root files verbatim.

spec/node-current-version/index.md

The Node.js version this site's tooling targets — currently 26 — and where that figure has to be kept in sync: deploy.yml's node-version, and this directory's own package.json engines.node.

spec/monorepo-github-pages/index.md

Why this site lives inside the workspace monorepo yet publishes from a separate sibling repository — git subtree, not a copy — and the rule that follows from it: edit here, never in the published repository. See "Publishing" in this directory's own README.md for the how-to.