Versions and compatibility

HL7 v2 releases 2.1 through 2.9

hl7-2 covers the fourteen published releases from 2.1 to 2.9 — including the point releases 2.3.1, 2.5.1, 2.7.1, 2.8.1, and 2.8.2. v2.5 is the complete base dictionary; every other release is a delta of it, covering the differences this crate models today, and inheriting everything else. Three of the fourteen (2.7.1, 2.8.1, 2.8.2) have no dictionary file of their own and resolve to their base release.

How a release is chosen

By default the release comes from MSH-12, the version id the message declares about itself. A release string the crate has no dictionary for resolves to the nearest older one — 2.5.2 reads as 2.5.1 — rather than failing.

use hl7_2::Version;

// From MSH-12, which is the default.
let message = hl7_2::parse(text)?;

// Forced, for a sender whose MSH-12 does not match what it actually sends.
let options = hl7_2::Options::new().with_version(Version::V2_3);
let message = hl7_2::parse_with_options(text, &options)?;

// Or resolve a release string the way MSH-12 is resolved: exact if known,
// otherwise the newest release no newer than what was declared.
assert_eq!(Version::nearest("2.5.2"), Some(Version::V2_5_1));

Forcing a release is not a niche need. Real senders declare 2.3 and send fields that only exist in 2.5, or declare 2.5 and send a 2.3-shaped MSH-9. When the declaration and the content disagree, believe the content.

What each release actually claims

Three of those change how a message reads, not just what a field is called, so they are the ones worth remembering: MSH-9 has no message-structure component before v2.3.1, which is why a pre-2.3.1 message's structure has to be resolved from MSH-9.1 and MSH-9.2; ERR is a single field before v2.5; and TS is withdrawn in favour of the primitive DTM from v2.7, so a TS-typed field holds a scalar timestamp rather than a value^precision pair.

HL7 v3 is versioned differently — by interaction, not by release — and hl7-3 is explicit that it implements the shared foundation rather than any particular interaction. Read that crate's spec/index.md §1 before filing anything as a bug.

Crate versions

Latest published at the time of writing. Each crate is versioned independently — they are released when they change, not on a common cadence.

Minimum supported Rust version

The policy is current stable minus three releases, pinned as rust-version in every member's Cargo.toml and stated in the workspace's own spec/rust-msrv-n-minus-3.md. At the time of writing that is 1.95.

# Check a change against the floor
cargo +1.95 check --workspace --all-targets

Raising the floor is a breaking change and belongs in a release that is allowed to break. If a crate here fails to build on a Rust version at or above its declared rust-version, that is a bug worth reporting.

Rust edition

Every member is on edition 2024. Editions are per crate in Cargo, so your own crate's edition is unaffected by these — you can depend on an edition-2024 crate from an edition-2018 crate without trouble.

Licensing

Every crate, and the workspace root, carries the same five-way choice:

MIT OR Apache-2.0 OR BSD-3-Clause OR GPL-2.0-only OR GPL-3.0-only

OR means you pick. Take MIT if you want the simplest permissive terms; Apache-2.0 if you want its explicit patent grant; BSD-3-Clause if that is what your organization has already cleared; or either GPL if you are integrating into a copyleft project that requires it. You do not have to comply with all five, and you do not have to tell anyone which you chose.

The same multi-license boilerplate appears byte for byte in every crate's LICENSE.md, matching each Cargo.toml's license field.

What “0.x” means here

Most of these crates are pre-1.0, and Cargo treats a 0.x minor bump as potentially breaking. In practice:

• hl7-2 is the most settled — the three modes, the path grammar, and the diagnostic split are stable shapes even while the dictionary keeps filling in.
• The conversion crates are governed by their specs rather than by their APIs. Their convert signature has been stable for several releases; what changes is coverage, and the specs record it.
• hl7-3 is explicitly a foundation. Expect it to grow rather than to change shape, but read its scope section before depending on a specific behavior.

Pin what you depend on the way you would pin any pre-1.0 crate — hl7-2 = "0.2" — and read the crate's spec/index.md rather than inferring guarantees from the type signatures.