# Changelog
All notable changes to this project will be documented in this file.
## v3.10.1 — 2026-04-09
### Fixed
- `mix docs` now builds cleanly. `HL7v2.Profile.ComponentAccess`
was marked `@moduledoc false` in v3.10.0 but referenced from
public docstrings in `HL7v2.Profile.require_component/5`,
`HL7v2.Profile.bind_table/4`, `guides/conformance-profiles.md`,
and the v3.10.0 CHANGELOG entry — producing "documentation
references module ... but it is hidden" warnings on every
docs build. Promoted `ComponentAccess` to a public module with
a full `@moduledoc` that lists the registered composite types
(CX, HD, CE, CWE) and explains how to extend the registry.
Zero behavior change.
## v3.10.0 — 2026-04-09
### Profile DSL polish release
Closes the deferred HIGH and MEDIUM findings from the v3.9.0 iter-1
audit that were worked around with custom-rule closures in the IHE
Profile Pack. The DSL is now substantially more declarative —
profiles built with v3.10 are introspectable, diffable, and (in
principle) serializable. The IHE profile modules shipped with
v3.9.0 have been migrated end-to-end and dropped ~135 net lines of
bespoke helper code.
### Added — declarative value pins
- **`HL7v2.Profile.require_value/5`** — pin a field to an expected
equality value. Supports an optional `:accessor` 1-arity function
for struct-component matching (e.g. pinning the `identifier`
component of a CE without a closure).
```elixir
profile
|> HL7v2.Profile.require_value("PV1", 2, "N")
|> HL7v2.Profile.require_value("QPD", 1, "IHE PIX Query",
accessor: & &1.identifier)
```
- **`HL7v2.Profile.require_value_in/5`** — pin a field to an
allowed-value list.
```elixir
profile
|> HL7v2.Profile.require_value_in("MSA", 1, ["AA", "AE", "AR"])
```
Fires a new `:require_value` rule on mismatch or blank. Error
messages include both expected and actual values. The rule is data
— the profile's `required_values` field is a plain map, not a
closure store.
### Added — declarative component/subcomponent targeting
- **`HL7v2.Profile.require_component/5`** — target a specific
component (and optionally subcomponent) within a composite field.
Supports `:each_repetition`, `:subcomponent`, and `:repetition`
options.
```elixir
# "Every PID-3 repetition must carry CX-1 (ID Number)"
profile
|> HL7v2.Profile.require_component("PID", 3, 1,
each_repetition: true)
# "Every PID-3 repetition must carry CX-4.1 (HD namespace_id)"
profile
|> HL7v2.Profile.require_component("PID", 3, 4,
each_repetition: true, subcomponent: 1)
```
Fires a new `:require_component` rule. Error messages follow the
`segment-field[repetition].component.subcomponent` format, e.g.
`"profile requires PID-3[2].4.1 to be populated"`.
Backed by a new `HL7v2.Profile.ComponentAccess` helper that maps
composite type modules to their canonical component field order.
Registered for **CX, HD, CE, CWE** — the composites referenced by
the shipped IHE profiles. Adding a new composite type is a
one-line entry. A compile-time guard raises if a declared field
is missing from the type's defstruct, preventing silent drift.
### Added — `bind_table/4` enforcement
`Profile.bind_table/4` was stored-but-ignored before v3.10.
Profiles declared table bindings that had no effect at validation
time — documented-as-feature-but-silently-ignored. Now fully
enforced against `HL7v2.Standard.Tables`:
```elixir
profile
|> HL7v2.Profile.bind_table("PV1", 2, "0004")
# At validation time, PV1-2 must be in HL7 table 0004
# (Patient Class): I, O, E, P, R, B, C, N, U.
# Anything else → :bind_table error.
```
- Table ID forms accepted: integer (`4`), plain string (`"4"`),
zero-padded string (`"0004"`), atom (`:"0004"`).
- Coded-struct unwrapping: CE, CWE, CX, HD, and any other composite
registered in `HL7v2.Profile.ComponentAccess` have their first
component extracted before the table lookup.
- Unknown numeric table IDs silently pass (matches the existing
`HL7v2.Standard.Tables.validate/2` semantics).
- Non-numeric table IDs (site-local codes) are silently skipped —
only HL7 standard numeric tables are currently enforced.
### Changed (breaking) — `bind_table/4` now fires errors
Profiles that relied on the pre-v3.10 silent-success behavior will
now produce `:bind_table` errors at validation time. If this is
unwanted, delete the `bind_table` call from the profile definition.
### Changed (breaking) — custom rule exceptions surface as errors
Already landed in v3.9.0 but worth repeating for anyone skipping
versions: a `Profile.add_rule/3` closure that raises no longer
silently returns `[]`. It surfaces as a
`%{rule: :custom_rule_exception}` error with the rule name and the
exception message. Preserves the zero-silent-failures stance.
### Internal — IHE Profile Pack migrated to the new DSL
Every shipped `HL7v2.Profiles.IHE.*` module was migrated to use the
new declarative builders. Net **-135 lines** across 5 modules,
zero behavior change:
- **`HL7v2.Profiles.IHE.Common.pid_core/1`** — the ~60-line
`pid3_identity_rule/1` custom rule was split: CX-1 (ID Number)
validation moved to `require_component`, a much smaller ~25-line
`:pid3_assigning_authority` custom rule remains for the
`HD.namespace_id` OR `HD.universal_id` disjunction. Rule atom
renamed to reflect the narrower scope.
- **`HL7v2.Profiles.IHE.PIX`, `.PDQ`** — ITI-9/21/22 query/response
closures (`qpd_1_matches_*`, `rcp_1_is_immediate`,
`msa_1_is_valid_ack`, `qak_2_is_valid_status`) all replaced with
`require_value` / `require_value_in` calls. ~56 lines deleted
across both modules.
- **`HL7v2.Profiles.IHE.LTW`** — LAB-1 ORC-1 and LAB-3 OBR-25 /
OBX-11 value constraint closures replaced with
`require_value_in`. ~25 lines deleted.
- **`HL7v2.Profiles.IHE.RadSwf`** — RAD-4 ORC-1 = "NW" and
ORC-5 = "SC" closures replaced with `require_value`. ~12 lines
deleted.
- **`HL7v2.Profiles.IHE.Common.pin_patient_class/2`** — now a
one-line wrapper around `Profile.require_value("PV1", 2, expected)`.
### Documentation
- **`guides/conformance-profiles.md`** — full DSL reference table
with examples for value pins, component targeting, and bind_table
enforcement. Escape-hatch section explains when to use
`add_value_constraint/4` vs `add_rule/3`.
- **`HL7v2.Validation.ProfileRules` moduledoc** — added a
`## "Blank" semantics` section documenting the recursive
`blank?/1` contract that several rules share.
### Deferred to v3.11
- `require_component` with `each_repetition: false` default
silently validates only repetition 1 on a repeating field.
Changing the default is breaking; documented the foot-gun.
- `custom_rules` LIFO execution order is undocumented.
- `blank?/1` fallback treats unknown terms as populated.
- `ProfileRules` is O(n²) — rebuilds the segment index per check.
Not a bottleneck for typical profile sizes.
- Per-CX "namespace_id OR universal_id" disjunction — the one
remaining custom rule in the IHE Common module. Could be
expressed with a `require_any_of_components/3` primitive but
not worth the DSL surface for one rule.
### Stats
5,140 tests (511 doctests + 32 properties + 4,597 tests),
0 failures.
## v3.9.0 — 2026-04-09
### Added — IHE Profile Pack
22 pre-built IHE conformance profiles covering the most common
HL7 v2.x transactions from IHE ITI, IHE PaLM (Lab), and IHE RAD
Technical Frameworks. `HL7v2.Profiles.IHE.*` lets integrators
validate IHE conformance in three lines:
```elixir
profile = HL7v2.Profiles.IHE.PAM.iti_31_adt_a01()
{:ok, msg} = HL7v2.parse(wire, mode: :typed)
HL7v2.validate(msg, profile: profile)
```
**PAM** (`HL7v2.Profiles.IHE.PAM`) — Patient Administration
Management. Source: IHE ITI TF-2b §3.30/§3.31.
- `iti_31_adt_a01` Admit Inpatient
- `iti_31_adt_a03` Discharge
- `iti_31_adt_a04` Register Outpatient
- `iti_31_adt_a08` Update Patient Information
- `iti_30_adt_a28` Create Patient (no visit)
- `iti_30_adt_a31` Update Patient (no visit)
- `iti_30_adt_a40` Merge Patient ID List
**PIX** (`HL7v2.Profiles.IHE.PIX`) — Patient Identifier
Cross-Reference. Source: IHE ITI TF-2 §3.8/§3.9/§3.10.
- `iti_8_feed_a01/a04/a08/a40` Patient Identity Feed (v2.3.1)
- `iti_9_query` PIX Query `QBP^Q23`
- `iti_9_response` PIX Response `RSP^K23`
- `iti_10_update` PIX Update Notification `ADT^A31`
**PDQ** (`HL7v2.Profiles.IHE.PDQ`) — Patient Demographics Query.
Source: IHE ITI TF-2 §3.21/§3.22.
- `iti_21_query` Demographics Query `QBP^Q22`
- `iti_21_response` Demographics Response `RSP^K22`
- `iti_22_query` Demographics + Visit Query `QBP^ZV1`
- `iti_22_response` Visit Response `RSP^ZV2`
**LTW** (`HL7v2.Profiles.IHE.LTW`) — Laboratory Testing Workflow.
Source: IHE PaLM TF-2a §3.1/§3.3 (Rev 11.0, 2024-04-08).
- `lab_1_placer_oml_o21` Placer Order Management `OML^O21`
- `lab_3_results_oru_r01` Order Results Management `ORU^R01`
**RAD-SWF** (`HL7v2.Profiles.IHE.RadSwf`) — Radiology Scheduled
Workflow. Source: IHE RAD TF-2 Rev 13.0 §4.1/§4.4.
- `rad_1_registration_a01` Patient Registration `ADT^A01` (v2.3.1)
- `rad_4_procedure_scheduled_omi` Procedure Scheduled `OMI^O23` (v2.5.1)
**Shared building blocks** in `HL7v2.Profiles.IHE.Common`:
- `msh_pam_core/1` — MSH-9/10/11/12 required, MSH-8 forbidden
- `evn_core/1` — EVN-2 required
- `pid_core/1` — PID-5 required + `:pid3_identity` custom rule
that validates every PID-3 repetition has CX-1 (ID Number)
and CX-4 (Assigning Authority) populated
- `pin_patient_class/2` — sugar for ITI-30/ITI-10 PV1-2 = "N"
**Mixed HL7 versions are supported**: ITI-8 PIX Feed and RAD-1 use
v2.3.1 (the earliest IHE profiles, never rebased), while ITI-9/10,
PDQ, LTW, and RAD-4 use v2.5 or v2.5.1. Profile version enforcement
gates each profile so cross-version mismatches are silently skipped
rather than flagged as false positives.
**Top-level catalog**: `HL7v2.Profiles.IHE.all/0` returns all 22
profiles keyed by IHE transaction code. Sub-catalogs exposed as
`pam/0`, `pix/0`, `pdq/0`, `ltw/0`, `rad_swf/0`.
### Added — DSL extension: `Profile.forbid_field/3`
IHE profiles frequently mark base-HL7 fields as "X" (not
supported). `HL7v2.Profile` gains a new builder:
```elixir
HL7v2.Profile.new("p")
|> HL7v2.Profile.forbid_field("MSH", 8) # MSH-8 Security forbidden
|> HL7v2.Profile.forbid_field("EVN", 1)
```
The matching `:forbid_field` rule in `HL7v2.Validation.ProfileRules`
fires when the named field is present with a non-blank value.
Missing segments are silently ignored (use `require_segment/2` if
absence should also be an error).
### Changed (breaking) — Profile version enforcement is now active
`HL7v2.Profile.version` was previously stored but never enforced —
an ITI-8 v2.3.1 profile would silently validate a v2.5 feed,
producing false-positive errors because field sequence numbers can
drift between versions. `ProfileRules.check/2` now compares
`profile.version` against the message's MSH-12 version; mismatched
versions cause the profile to return `[]` (not applicable) instead
of running its rules.
**Migration**: if your code depended on the old silent-ignore
behavior, either pass a profile with `version: nil` (wildcard) or
match the profile version to your sender.
### Changed (breaking) — Custom rule exceptions surface as errors
A custom rule added via `Profile.add_rule/3` that raises no longer
silently returns `[]`. It now surfaces as a
`%{rule: :custom_rule_exception}` error containing the rule name
and the exception message, preventing buggy rules from silently
passing every message.
**Migration**: if you had a test asserting `ProfileRules.check/2`
returned `[]` for a raising rule (indicating the rule was swallowed),
update it to assert the synthetic error is present.
### Guides
New [`guides/ihe-profiles.md`](guides/ihe-profiles.md) walks
through the pack with usage examples, a transaction coverage
table, deployment caveats for the catalog dispatch patterns, and
a list of IHE TF sources.
### Stats
5,102 tests (505 doctests + 32 properties + 4,565 tests),
0 failures.
## v3.8.0 — 2026-04-09
### Added — v2.6 Materials Management Segments
Eight new typed segment modules covering HL7 v2.6 Chapter 17
(Materials Management). Supply-chain and sterilization flows that
arrive with these segments now parse as typed structs instead of
landing in `extra_fields`.
- **`HL7v2.Segment.ITM`** — Material Item Master. 18 fields.
Canonical material item identity, manufacturer, category,
regulatory flags, and cost data.
- **`HL7v2.Segment.IVT`** — Material Location. 26 fields.
Per-location stocking policy: bin, par levels, reorder points,
reusable/consignment flags, substitutes.
- **`HL7v2.Segment.ILT`** — Material Lot. 10 fields. Lot-level
tracking — expiration, received date/quantity, on-hand quantity,
lot cost — complementing ITM.
- **`HL7v2.Segment.PKG`** — Item Packaging. 7 fields. Packaging unit
definitions and pricing per packaging level (each, box, case).
- **`HL7v2.Segment.VND`** — Purchasing Vendor. 10 fields. Vendor
master: identifier, name, contact, contract, regulatory approvals.
- **`HL7v2.Segment.STZ`** — Sterilization Parameter. 3 fields.
Sterilization type, cycle, and maintenance cycle for reusable
medical devices. Complements SCD and SCP.
- **`HL7v2.Segment.SCP`** — Sterilizer Configuration. 8 fields.
Device configuration for a sterilizer: number of devices, labor
calculation, date format, identification, type, lot control.
- **`HL7v2.Segment.SLT`** — Sterilization Lot. 5 fields. Ties a
sterilization batch to the device that processed it.
Catalog grows from **156 → 164** typed segments (152 v2.5.1 baseline
+ 12 common v2.6/v2.7 additions).
### Added — Migration Guide
New [`guides/migration.md`](guides/migration.md) for developers
moving from another HL7 v2 library. Covers:
- **`elixir_hl7`** (main Elixir alternative) — installation, parse,
field access, builder, validation, ACK, MLLP, and a pitfalls
section (empty-string vs nil, repeating fields, separator handling,
version-aware rules). Includes a step-by-step adoption checklist.
- **HAPI v2 (Java)** — method-by-method mental-model mapping.
- **HL7apy (Python)** — attribute-traversal mental-model mapping.
- **Feature comparison table** — `hl7v2` vs the other three.
### Stats
4,997 tests (504 doctests + 32 properties + 4,461 tests), 0 failures.
## v3.7.0 — 2026-04-09
### Added — v2.6/v2.7 Typed Segments
Four new typed segment modules for post-v2.5.1 segments. Messages at
v2.7+ that use these segments now parse as typed structs instead of
landing in `extra_fields`.
- **`HL7v2.Segment.PRT`** (v2.7+) — Participation Information. 10
fields. Introduced in HL7 v2.7 to replace ROL in many messages;
captures the participation of a person, organization, location,
device, or other entity in an event.
- **`HL7v2.Segment.ARV`** (v2.6+) — Access Restriction. 7 fields.
"Break the glass" emergency access, patient-requested
confidentiality, VIP flags.
- **`HL7v2.Segment.UAC`** (v2.7+) — User Authentication Credential.
2 fields. Inter-system user authentication (Kerberos, SAML, etc.).
- **`HL7v2.Segment.IAR`** (v2.7+) — Allergy Reaction. 5 fields.
Attaches to IAM to provide additional reaction details.
Catalog grows from **152 → 156** typed segments (100% v2.5.1 + 4
common v2.6/v2.7 additions).
### Stats
4,907 tests (504 doctests + 32 properties + 4,371 tests), 0 failures.
## v3.6.0 — 2026-04-09
### Added — Conformance Profiles
Second feature release closing the gap vs HAPI and HL7apy. HL7v2 now has
**conformance profile validation**: user-defined constraints that extend the
base HL7 schema with organization-specific rules.
- **`HL7v2.Profile`** — pure functional builder for conformance profiles:
```elixir
profile =
HL7v2.Profile.new("Hospital_ADT_A01", message_type: {"ADT", "A01"})
|> HL7v2.Profile.require_segment("NK1")
|> HL7v2.Profile.require_field("PID", 18)
|> HL7v2.Profile.require_cardinality("OBX", min: 1, max: 10)
|> HL7v2.Profile.bind_table("PV1", 14, "0069")
|> HL7v2.Profile.add_value_constraint("PV1", 2, &(&1 in ["I", "O", "E"]))
|> HL7v2.Profile.add_rule(:custom_check, &my_rule_fn/1)
```
Eight builder functions: `new`, `require_segment`, `forbid_segment`,
`require_field`, `bind_table`, `require_cardinality`, `add_value_constraint`,
`add_rule`. Plus `applies_to?/2` for message-type gating.
- **`HL7v2.Validation.ProfileRules`** — evaluates a profile against a typed
message and returns standard error maps with two extra keys (`:rule` and
`:profile`) for traceability.
- **`HL7v2.validate/2` `:profile` option** — validates against one profile
or a list of profiles alongside the base schema:
```elixir
HL7v2.validate(msg, profile: profile)
HL7v2.validate(msg, profile: [p1, p2, p3])
```
Profiles with a specific `:message_type` are silently skipped for
non-matching messages.
- **`HL7v2.Profiles.Examples`** — ships two example profiles as starting
points for integrators:
- `hospital_adt_a01/0` — strict hospital profile (NK1 + DG1 + PID-18 +
PV1-3 required, patient_class constrained to I/O/E)
- `ihe_lab_oru_r01/0` — IHE-style lab results (OBR + OBX required,
observation_result_status constrained to HL7 table 0085 codes)
- **`guides/conformance-profiles.md`** — user guide covering concepts,
DSL builders, validation integration, error shape, and custom rules.
Included in HexDocs.
### Changed
- **README comparative table** — hl7v2 Validation cell updated to include
**conformance profiles**. On the BEAM, hl7v2 is now the only package
with typed structs + builder + structural + conditional + version-aware
+ profile validation + MLLP/TLS.
### Stats
4,864 tests (504 doctests + 32 properties + 4,328 tests), 0 failures.
## v3.5.0 — 2026-04-09
### Added — Version-Aware Validation (v2.3 → v2.8)
HL7v2 now applies **version-specific rules** driven by MSH-12 (`version_id`).
Previously the library enforced v2.5.1 rules on every message regardless of
the declared version.
- **`HL7v2.validate/2` is version-aware** — reads MSH-12 automatically, or
accepts an explicit `:version` override:
```elixir
HL7v2.validate(msg) # reads MSH-12
HL7v2.validate(msg, version: "2.7") # explicit override
```
Invalid/unrecognized overrides silently fall back to MSH-12 (prevents
typos from weakening validation).
- **v2.7+ segment fields** — MSH-22/23 (sending/receiving responsible
organization), MSH-24/25 (network addresses), PID-40 (telecommunication
information, replaces PID-13/14), OBR-50 (parent universal service
identifier), OBX 20-25 (observation site, instance ID, mood code,
performing organization) are now declared typed fields and round-trip
cleanly.
- **B-field deprecation tracking** — v2.7+ messages exempt fields that
became backward-compatibility-only in v2.7: PID-13/14, OBR-10/16,
ORC-10/12. Required-field enforcement skips these when the message is
v2.7 or later, matching the HL7 conformance model.
- **`HL7v2.Standard.Version`** — new public module with `normalize/1`,
`compare/2`, `at_least?/2`, and `supported?/1` for HL7 version strings.
Accepts `"2.7"`, `"v2.7"`, `"2.7.1"`, etc.
- **`HL7v2.Standard.VersionDeltas`** — tracks field optionality changes
between versions. `exempt?/3` returns true when a field should not be
enforced as required at a given version.
- **v2.7 extended fixture** — new `adt_a01_v27_extended.hl7` exercises
MSH-22/23 and PID-40 end-to-end. All 5 adjacent-version fixtures
(v2.3/v2.4/v2.6/v2.7/v2.8) now pass strict validation, not just
round-trip.
### Changed
- **README Scope section** — updated to describe the version-aware support
explicitly. v2.3-v2.8 messages parse, round-trip, and validate under
their declared version's rules.
### Stats
4,761 tests (499 doctests + 32 properties + 4,230 tests), 0 failures.
## v3.4.0 — 2026-04-09
## v3.4.0 — 2026-04-09
### Fixes
- **Conditional rule test proves each clause exists** — each of the 24
segment-specific rules is now triggered with data that MUST produce
non-empty output. A blank struct hitting the default catch-all would
fail. Previously only tested `is_list(errors)`.
- **Raw gap identities pinned** — `Coverage.raw_holes()` asserted as
exact tuples `[{"QPD", ...}, {"RDT", ...}]` and `runtime_dispatched()`
as `[{"OBX", ...}]`. A swap to different fields fails CI.
- **Tarball test is safe and exact** — builds into temp dir (`--output`),
uses `System.cmd` argument lists (safe for paths with spaces), derives
tarball name from `Mix.Project.config()[:version]`, asserts `.hl7`
count == frozen fixture count (exact equality). Never mutates the
project root.
- **Zero test noise** — `@moduletag capture_log: true` on ConnectionTest,
`@tag capture_log: true` on timeout tests in ListenerTest and ClientTest,
named `&handle_telemetry_event/4` replaces anonymous handler lambdas.
Test output is pure dots.
- **ListenerTest teardown flake fixed** — `on_exit` wraps `Listener.stop/1`
in `try/catch :exit` to handle concurrent-client tests where the listener
exits before cleanup.
- **All overclaims narrowed** — PackagingTest moduledoc, Fixtures moduledoc,
README, and CHANGELOG wording aligned to what CI actually proves (tarball
file count equality, not compile-and-compare coverage map parity).
### Stats
4,688 tests (472 doctests + 32 properties + 4,184 tests), 0 failures.
Zero noise in test output.
## v3.3.6 — 2026-04-09
### Fixes
- **Tarball-level packaging smoke test** — `mix hex.build` is run in CI and
the built tarball is unpacked to assert the `.hl7` fixture count exactly
equals the compile-time frozen list. Previously only project config was
checked, not the actual artifact.
- **OBX value type count pinned** — `length(OBXValue.known_types()) == 41`
asserted (matches README claim).
- **Conditional rule count corrected and pinned** — actual count is 24
segments (was incorrectly claimed as 25 in README/docs, then 23 in an
overcorrection). Now pinned by an explicit test listing all 24 segments
with conditional rules.
- **CHANGELOG `/0` → `/1`** — stale v3.3.1 entries still said
`check_freshness/0`; normalized to `/1` throughout.
### Stats
4,688 tests (472 doctests + 32 properties + 4,184 tests), 0 failures
## v3.3.5 — 2026-04-09
### Fixes
- **Schema coverage claims pinned by exact tests** — segment count (152),
type count (90), structure count (222), and `coverage_summary` fields are
now asserted as exact values, not ranges. Shrinkage or expansion without
updating tests fails CI.
- **Corpus breadth pinned with exact equality** — three new tests assert
`@exact_fixture_files`, `@exact_canonical`, `@exact_pct` alongside the
existing minimums. Any fixture add/remove now requires updating both the
test pins AND the README/CHANGELOG in the same commit. This closes the
final claim-proof drift gap: expansion no longer silently passes CI while
published numbers go stale.
- **Packaging smoke test** — new `HL7v2.Conformance.PackagingTest` asserts
`mix.exs` `package()[:files]` includes `test/fixtures/conformance`, the
directory exists with `.hl7` files, and the on-disk count matches the
frozen list. A `package()[:files]` regression now fails CI before reaching
Hex.
### Stats
4,682 tests (472 doctests + 32 properties + 4,178 tests), 0 failures
## v3.3.4 — 2026-04-08
### Fixes
- **`check_freshness/1` is now strict-by-default on missing fixture dir** —
returns `{:error, :fixture_dir_unavailable}` instead of silently passing
as `:ok`. Since v3.3.3 ships the corpus in the Hex package, a missing
directory is itself a packaging/pathing regression and should fail loudly.
Pass `allow_missing: true` to opt back into the lenient behavior.
- **Strict-clean suite freshness guard** now flunks on
`{:error, :fixture_dir_unavailable}` with a packaging-hint error message.
- **Release-surface test pins** — four new tests in
`HL7v2.Conformance.FixturesTest` lock the documented minimums
(`@min_fixture_files`, `@min_canonical_structures`, `@min_pct`) and
cross-check that `list_fixtures/0` and `unique_canonical_structures/0`
sizes match `coverage/0`. Silent corpus shrinkage now fails CI with a
clear message.
- **Removed duplicate `groups_for_extras`** in `mix.exs` — the second
(inert) block was shadowed by the first and would have silently absorbed
future edits. Only the `Guides` + `Reference` block remains.
### Stats
4,676 tests (472 doctests + 32 properties + 4,172 tests), 0 failures
## v3.3.3 — 2026-04-08
### Fixes
- **Fixture corpus now ships in the Hex package** — `test/fixtures/conformance`
is included in `files:`, so installed artifacts compile against the same
110 .hl7 fixtures as the source tree and report identical counts.
Verified via `mix hex.build` (110 conformance fixtures present in the
tarball). Previously, an installed user's
`HL7v2.Conformance.Fixtures.coverage()` returned `%{files: 0, canonical: 0}`
while README claimed parity.
- **`guides/getting-started.md`** — install snippet bumped from `~> 2.9` to
`~> 3.0`.
- **`check_freshness/1`** is now **testable** via `:dir` and `:frozen`
keyword options. Automated stale-case tests cover: matching dir+frozen,
on-disk additions, frozen removals, simultaneous drift, non-.hl7 filtering,
and missing-dir (installed Hex artifact case).
- **Strict-clean suite freshness guard** now delegates to
`Fixtures.check_freshness/1` instead of reimplementing the comparison —
regressions in the helper fail the guard.
### Stats
4,671 tests (472 doctests + 32 properties + 4,167 tests), 0 failures
## v3.3.2 — 2026-04-08
### Fixes
- **Strict-clean fixture suite is now runtime-discovered** — previously, the
`describe "strict-clean fixture corpus"` block expanded `Path.wildcard` at
compile time, so newly added fixture files were silently ignored until the
test module recompiled. The suite now enumerates fixtures at runtime via
`File.ls` inside a single test, so additions and removals are picked up
on every test run without recompilation.
- **Freshness guard test** — a new test in the strict-clean suite fails if
the compile-time-frozen `HL7v2.Conformance.Fixtures.list_fixtures/0` drifts
from the on-disk corpus. This catches stale `@external_resource` snapshots
that would otherwise pass silently.
- **README wording narrowed** — explicit caveat that `@external_resource`
only tracks files present at compile time, with instructions to call
`HL7v2.Conformance.Fixtures.check_freshness/1` in dev/test.
### Added
- **`HL7v2.Conformance.Fixtures.check_freshness/1`** — returns `:ok` or
`{:stale, on_disk_only: [...], frozen_only: [...]}` comparing the
compile-time snapshot against the current on-disk fixture directory.
Returns `:ok` when the directory is not accessible (installed Hex artifact
case).
- Test for `check_freshness/1` in `HL7v2.Conformance.FixturesTest`.
### Verified
Ran the new drift guard against a temporary `zzz_probe_drift.hl7` fixture —
the guard correctly reported:
`fixtures on disk but missing from compile-time frozen list: ["zzz_probe_drift.hl7"]`.
Probe file removed after verification.
### Stats
4,665 tests (472 doctests + 32 properties + 4,161 tests), 0 failures
## v3.3.1 — 2026-04-08
### Fixes
- **`HL7v2.Conformance.Fixtures` ACK fallback** — `unique_canonical_structures/0`
now uses the same alias fallback as `HL7v2.Validation`: when the
trigger-specific structure (e.g. `ACK_A01`) is unregistered, it falls back to
the bare message_code (`ACK`). Previously the helper returned the unregistered
alias as a "canonical" entry.
- **Corpus stats are now compile-time frozen** — fixture filenames, canonical
structures, and families are computed at compile time by walking the fixture
directory and extracting MSH-9 via lightweight string parsing.
`coverage/0`/`list_fixtures/0`/`unique_canonical_structures/0` return
identical results whether running from source or from an installed Hex
artifact. `@external_resource` ensures recompilation when any fixture
changes.
- **`mix hl7v2.coverage` no longer emits telemetry noise** — the task starts
the `:telemetry` application before running and, more importantly, no longer
parses fixtures at runtime (they're compile-time frozen).
- **README family list is now live-derived** — the hand-curated (and stale)
family enumeration was replaced with a pointer to
`HL7v2.Conformance.Fixtures.families/0`, which cannot drift from the actual
corpus.
### Added
- **`HL7v2.Conformance.Fixtures.families/0`** — returns the sorted list of
message family prefixes (`ADT`, `ORU`, `MFN`, ...) covered by the corpus,
derived at compile time from canonical structure names.
- **5 new tests** in `HL7v2.Conformance.FixturesTest`: ACK fallback guard,
registry validity check (every entry must be in `MessageStructure`),
families accessors, and an explicit "ORI is NOT in corpus" regression to
prevent future hand-curated drift.
### Stats
4,772 tests (472 doctests + 32 properties + 4,268 tests), 0 failures
## v3.3.0 — 2026-04-08
### Fixes
- **MFN canonicalization bug** — `MFN^M03` through `MFN^M13` (except M05) were
incorrectly collapsed to `MFN_M01` in `HL7v2.MessageDefinition.canonical_structure/2`,
even though all 14 MFN structures are registered. Each trigger now resolves
to its own structure for strict validation. This was exposed by the v3.3.0
corpus expansion — fixtures for MFN_M03/M04/M06..M13 failed strict validation
until the canonical map was corrected.
### Added
**58 new conformance fixtures covering 58 new canonical structures** — corpus
expansion from 43 to 101 unique canonical structures (**54.3% of 186 official
v2.5.1 structures**):
- **ADT variants** (11): A12, A15, A20, A21, A24, A30, A37, A39, A43, A54, A61
- **Financial** (3): DFT_P11, BAR_P10, BAR_P12
- **Queries & responses** (15): QBP_Q11/Q13/Q15/Z73, RSP_K11/K13/K15/K23/K25/K31/Q11/Z82/Z86/Z88/Z90
- **Master files** (12): MFN_M03 through MFN_M15 (11 MFN structures + MFK coverage)
- **Lab orders** (3): OML_O33, OML_O35, OML_O39
- **Order variants** (5): OMB_O27, OMD_O03, OMG_O19, OMN_O07, OMP_O09
- **Order responses** (5): ORB_O28, ORD_O04, ORF_R04, ORG_O20, ORL_O22
- **Personnel management** (4): PMU_B03, PMU_B04, PMU_B07, PMU_B08
All new fixtures pass **strict-clean validation** (`mode: :strict`) with zero
warnings. Fixture round-trip suite has 105 explicit test cases; strict-clean
suite auto-discovers all 110 fixture files via `Path.wildcard`.
### Corpus Growth
| | v3.2.0 | v3.3.0 |
|---|---|---|
| Wire fixtures | 52 | **110** (+58) |
| Unique canonical structures | 43 | **101** (+58) |
| % of 186 official | 23.1% | **54.3%** (+31.2pp) |
### Method
This release was produced by a **Forge loop**: fresh-context audit selected
60 highest-value targets, then iterative tranches (A: ADT+DFT, B: RSP+QBP,
C: MFN, D+E: orders & personnel) each fed back through strict validation.
The MFN canonicalization bug was uncovered by Tranche C and fixed in the
same iteration.
### Stats
4,763 tests (472 doctests + 32 properties + 4,259 tests), 0 failures
## v3.2.0 — 2026-04-08
### Added
- **15 new conformance fixtures covering 15 new canonical structures**:
ADT_A03 (discharge), ADT_A06 (change outpatient to inpatient), ADT_A09
(patient departing tracking), ADT_A16 (pending discharge), ADT_A18 (merge
patient info), ADT_A38 (cancel pre-admit), ADT_A45 (move visit info),
ADT_A50 (change visit number), ADT_A60 (update allergy info), BAR_P02
(purge patient accounts), DOC_T12 (document response), MDM_T01 (original
document notification), MFK_M01 (master file application ack), QRY_A19
(patient demographics query), SSU_U03 (specimen status update).
- All new fixtures pass strict-clean validation with zero warnings.
- Fixture round-trip suite now has 47 explicit test cases; strict-clean
suite auto-discovers all 52 fixture files via `Path.wildcard`.
### Corpus Growth
**52 wire fixtures, 43 unique canonical structures, 23.1% of 186 official
v2.5.1** (up from 37 / 28 / 15.1% in v3.1.1).
### Stats
4,651 tests (472 doctests + 32 properties + 4,147 tests), 0 failures
## v3.1.1 — 2026-04-08
### Fixes
- **Fixture coverage counts computed live from disk** — `HL7v2.Conformance.Fixtures`
module is now the single source of truth. `mix hl7v2.coverage` reads the
fixture directory and reports current file count, unique canonical structures,
and percentage of 186 official. Prevents doc drift.
- **Strict-clean suite wording** — describe block renamed from "real conformance
proof" to "strict-clean fixture corpus" with a comment noting its breadth is
bounded by the on-disk corpus, not the full standard.
- **Generated non-repeating test wording** — moduledoc no longer claims the
assertion checks specifically for a "cardinality error"; the test asserts only
that the validator emits *some* diagnostic (cardinality, out-of-order, or
unexpected) for the duplicated segment.
### Added
- `HL7v2.Conformance.Fixtures.coverage/0` — returns `%{files, canonical,
total_official, pct}` computed from the fixture directory.
- `HL7v2.Conformance.Fixtures.list_fixtures/0` — sorted list of .hl7 files.
- `HL7v2.Conformance.Fixtures.unique_canonical_structures/1` — deduplicated
canonical structures covered by the corpus.
### Current Fixture Corpus
37 wire fixtures, 28 unique canonical structures, 15.1% of 186 official v2.5.1.
### Stats
4,621 tests (472 doctests + 32 properties + 4,117 tests), 0 failures
## v3.1.0 — 2026-04-08
### Fixes
- **ACK_A01-style aliases now resolve** — `ACK^A01^ACK_A01`, `ACK^A02^ACK_A02`,
etc. now fall back to the bare `ACK` structure when the specific alias isn't
registered. Previously these returned "structure not checked" warnings.
### Added
- **Richer generated structural negatives** — every one of the 222 message
structures now has 5 generated tests instead of 2: positive in order,
MSH-only fails, MSH-not-first flagged in strict mode, non-repeating required
duplicated is flagged, and unknown segment injection does not crash. Total:
1,110 generated structure tests.
- **Version-matrix fixtures** — ADT_A01 fixtures at v2.3, v2.4, v2.6, v2.7, and
v2.8. Adjacent-version tolerance is now exercised by real wire messages at
each version declaration.
### Changed
- **Scope claim narrowed** — README now describes adjacent-version tolerance as
"parser/encoder round-trip" rather than broad interoperability. The version
matrix slice is small by design.
### Stats
4,615 tests (472 doctests + 32 properties + 4,111 tests), 0 failures
## v3.0.2 — 2026-04-08
### Fixes
- **PV2 transfer rule respects strict mode** — `prior_pending_location` check
now escalates to `:error` in strict mode for transfer triggers. Previously
hardcoded to `:warning` regardless of mode.
- **All 32 fixtures pass strict-clean validation** — fixtures fixed: NTE ordering
in ADT_A01, PV2-1 populated in ADT_A02, BPX donation/commercial path in
BPS_O29. Zero warnings under `mode: :strict`.
- **Fixture coverage percentage corrected** — 32 files map to 28 unique canonical
structures (15.1% of 186 official), not 30% as previously claimed.
### Added
- **Strict-clean conformance suite** — new test describe block runs every fixture
under `mode: :strict` and fails on any warning. Lenient round-trip suite is
preserved separately.
### Stats
3,938 tests (472 doctests + 32 properties + 3,434 tests), 0 failures
## v3.0.1 — 2026-04-08
### Fixes
- **Structural validation skipped for non-canonical MSH-9.3 aliases** — messages
with alias structures in MSH-9.3 (e.g., `SIU_S14`, `ADT_A28`, `REF_I13`) now
canonicalize to the correct registered structure (SIU_S12, ADT_A05, REF_I12)
before structural validation. Previously these returned "structure not checked"
warnings despite having known canonical mappings.
- **MLLP client docs** — `send_message/3` docs now correctly state that protocol
desync is terminal (closes connection, stops client process). Previously still
described the old drain-and-continue behavior.
- **README install snippet** — updated from `~> 2.9` to `~> 3.0` with upgrade
note about the breaking desync change.
- **Conformance roadmap** — current state updated to reflect 32 fixtures, 25
trigger-aware conditional rules, and accurate raw gap counts.
### Stats
3,906 tests (472 doctests + 32 properties + 3,402 tests), 0 failures
## v3.0.0 — 2026-04-08
### Breaking
- **MLLP protocol desync is now a fatal error** — `send_message/3` returns
`{:error, :protocol_desync}` and closes the connection if any stale bytes
(complete or partial frames) are found in the buffer at a send boundary.
Previously, complete stale frames were silently discarded and partial bytes
were carried forward, potentially corrupting the next response.
### Added
- **Trigger-aware conditional validation** — scheduling segments (AIS, AIG,
AIL, AIP, RGS) now check the message trigger event from MSH-9.2. Modification
triggers (S03-S11) produce definitive checks; non-modification triggers skip
the heuristic. PV2 `prior_pending_location` is validated against transfer
triggers (A02, A06, A07, etc.). Without trigger context, the original
heuristic fallback is preserved for backwards compatibility.
- **14 new conformance fixtures** — ADT_A02/A04/A08/A17, ORU_R01 multi-OBR,
ORU_R30, OML_O21, OMI_O23, OMS_O05, RDS_O13, RAS_O17, BPS_O29, MFN_M01,
SIU_S14. 32 fixture files covering 28 unique canonical structures (15% of
186 official). All pass strict-clean validation.
- **OBX-5 runtime-dispatched** in coverage reporting — `mix hl7v2.coverage`
now distinguishes between true raw gaps (QPD-3, RDT-1) and intentionally
runtime-typed fields (OBX-5 VARIES via OBXValue dispatch).
### Stats
3,904 tests (472 doctests + 32 properties + 3,400 tests), 0 failures
## v2.12.0 — 2026-04-08
### Fixes
- **MLLP protocol desync** — any non-empty buffer at a send boundary now returns
`{:error, :protocol_desync}` and closes the connection. Previously, stale
complete frames were silently discarded (hiding protocol violations) and
partial stale bytes could corrupt the next response by concatenating with it.
MLLP is strictly 1:1 request/response; leftover bytes of any kind are now
treated as a fatal protocol violation.
- **Stale secondary docs** — `docs/expansion-plan.md` marked as historical
(was showing v1.3.0 state); `docs/conformance-roadmap.md` corrected to
reflect the 3 remaining raw holes and current conditional rule count.
### Stats
3,876 tests (472 doctests + 32 properties + 3,372 tests), 0 failures
## v2.11.0 — 2026-04-08
### Fixes
- **MLLP request/response desync** — stale frames from misbehaving peers are
now drained before each send, maintaining strict 1:1 request/response pairing.
Previously, buffered extra frames would be returned as the response to a
subsequent request, mispairing ACKs with outbound messages.
- **~h sigil** — now validates repetition legality (non-repeating field +
repetition selector = compile error) and component bounds against typed
field metadata at compile time.
- **Typed round-trip contract** — tests and docs now correctly describe typed
encode/parse as "canonicalization is idempotent" rather than
"identity-preserving" (trailing empty components are trimmed per HL7 encoding
rules).
### Added
- **Reference docs in HexDocs** — segments, data types, message structures, and
encoding rules are now included in the published documentation.
- **Known Limitations** section in README — documents the 3 raw field holes
(OBX-5 VARIES, QPD-3, RDT-1), segment-local conditional validation, and typed
canonicalization behavior.
### Stats
3,875 tests (472 doctests + 32 properties + 3,371 tests), 0 failures
## v2.10.0 — 2026-04-07
### Fixes
- **MLLP client multi-frame safety** — extra complete frames in a single TCP
read are now re-framed back into the buffer instead of silently dropped;
previous fix only preserved partial-frame remainders
- **fetch/2 component out-of-range on composites** — `MSH-9.99` and
`PID-3.99[*]` now return `{:error, :invalid_component}` instead of
`{:ok, nil}` or `{:ok, [nil, nil]}`
- **Flaky MLLP client test** — server-close test uses 1ms timeout + 300ms
margin (was 50ms/100ms race)
- **parse/2 docs** — `validate: true` now documented as typed-mode only
### Added
- **8 new OBX-5 value types** — AD, MA, NA, NDL, PL, PPN, SPS, VR added to
the dispatch map (41 types total, up from 33)
- **PV2 conditional rule** — warns when `expected_discharge_date_time` is set
without `expected_discharge_disposition`
- **QAK conditional rule** — warns when `query_tag` is present without
`query_response_status`
### Stats
3,875 tests (472 doctests + 32 properties + 3,371 tests), 0 failures
## v2.9.1 — 2026-04-07
### Fixes
- **MLLP client frame buffering** — leftover frames from multi-frame responses
are now buffered in GenServer state and consumed on the next `send_message`
call (was silently discarding extra frames)
- **fetch/2 out-of-range repetitions** — `PID-3[3]` with only 2 reps now returns
`{:error, :repetition_out_of_range}` instead of `{:ok, nil}`
## v2.9.0 — 2026-04-07
### Generated Reference Docs + Structure Proof
- **`mix hl7v2.gen_docs`** — generates all reference docs from code metadata
- **message-structures.md**: 6,726 lines — all 222 structures with group notation
- **segments.md**: 3,516 lines — all 152 segments with field tables
- **data-types.md**: 1,162 lines — all 90 types with components
- **444 generated structure validation tests** — positive + negative for every
structure. No more "selectively tested."
- Conformance assertions tightened to exact counts
- Stale moduledocs and roadmap fixed
### Stats
3,863 tests (472 doctests + 32 properties + 3,359 tests), 0 failures
## v2.8.2 — 2026-04-06
### Fixes
- **Flaky MLLP test** — increased sleep and assert_receive timeouts for telemetry
exception events (was timing-sensitive under CI load)
- **TQ moduledoc** — removed stale "RI/OSD preserved as raw strings" (now typed)
- **SCD/SDD moduledoc** — removed contradictory "per HL7 v2.5.1 specification"
## v2.8.1 — 2026-04-06
### Fixes
- **RPT data loss** — all 10 v2.5.1 components now parsed and encoded (was 6,
silently dropping components 7-10)
- **TQ depth** — `interval` parsed as RI struct, `order_sequencing` as OSD struct
(were raw strings despite typed modules existing)
- **Stale moduledocs** — IN2, SCD, SDD corrected
## v2.8.0 — 2026-04-06
### Full Conformance Expansion
- **189 HL7 tables** (was 108) — coded-value tables across all v2.5.1 domains
- **255 field bindings** (was 80) — 100% of ID-typed fields bound to tables
- **23/23 conditional rules** — all segments with `:c` fields have enforcement
- **18 conformance fixtures** — end-to-end round-trip + validation per family
- **222 message structures** (186/186 official v2.5.1 + aliases)
## v2.7.1 — 2026-03-27
### Fixes
- **parse/2 table validation** — `validate_tables: true` option now forwarded to
validator (was silently ignored)
- **add_segment/2 guards** — rejects MSH (ArgumentError) and non-segment structs
- **ACK 5-char delimiter support** — ACK encoder handles truncation-character MSH-2
- **parse/2 typespec** — includes `{:ok, msg, warnings}` return shape
## v2.7.0 — 2026-03-27
### Full v2.5.1 Structure Coverage
- **9 final missing structures**: EAN_U09, PPV_PCA, PRR_PC5, PTR_PCF, QBP_Z73,
QRY, RCL_I06, RGR_RGR, RTB_Z74
- **186/186 official v2.5.1 structures** covered (222 total with aliases)
- All official segments, types, and structures at 100%
## v2.6.0 — 2026-03-26
### Full v2.5.1 Structure Coverage
- **23 new structures** closing all identified gaps vs the official v2.5.1 index:
ADT_A18, ADT_A52, MFR_M04-M07, MFN_M15, ORF_R04, QRY variants, OSQ/OSR_Q06,
RSP_Q11/K23/K25/Z82/Z86/Z88/Z90, SQM/SQR_S25
- **213 message structure definitions** total (186 official + aliases/responses)
- README: tightened type count (89 + legacy TN), version scope, raw mode claims
## v2.5.0 — 2026-03-26
### Deep Semantic Validation
- **108 HL7 tables** (was 20) — demographics, clinical, scheduling, administrative,
financial coded-value tables
- **80 coded field bindings** (was 11) — across MSH, PID, PV1, PV2, NK1, AL1, IAM,
DG1, DRG, NTE, ORC, OBR, OBX, IN1, FT1, TXA, SCH, AIS, AIG, RXR, EVN, ERR, MSA
- **Conditional field rules** for 17 segments — OBX, MSH, NK1, ORC, OBR, SCH, AIS,
AIG, AIL, AIP, RGS, ARQ, DG1, PID, PV2, QAK, MFE/MFA. Rules produce warnings
in lenient mode, errors in strict mode.
## v2.4.0 — 2026-03-26
### CCP Type + 190 Message Structures
- **CCP type** (Channel Calibration Parameters) — last missing v2.5.1 type. 90/90.
- **86 new message structures** (104 → 190) covering all major v2.5.1 families
- README and docs updated to current coverage
## v2.3.0 — 2026-03-25
### 104 Message Structures
- 81 new message structures across all HL7 v2.5.1 families: ADT, BAR, DFT,
pharmacy, lab, query, master files, scheduling, referrals, pathways, equipment,
blood bank, clinical study, personnel, network management
- 226 canonical trigger-event mappings
## v2.2.0 — 2026-03-25
### Zero Raw Holes
- 218 raw field holes filled across 36 segments
- Only 3 intentional raw holes remaining (OBX-5 dispatch, RDT-1 variable, QPD-3 query)
## v2.1.3 — 2026-03-26
### Fixes
- **SI/TM/DT invalid value preservation** — completes the lossless round-trip
work started in v2.1.2. Invalid SI values preserved as raw strings, invalid
TM/DT values preserved in `original` field. No primitive type silently drops
malformed values anymore.
## v2.1.2 — 2026-03-26
### Fixes
- **DT/DTM invalid value preservation** — invalid dates (e.g., `20240230`, `20250229`)
and malformed DTM values are now preserved in an `original` field instead of silently
dropping to nil. Prevents clinical data loss on dirty feeds during typed round-trip.
## v2.1.1 — 2026-03-26
### Fixes
- **Strict repetition validation** — non-repeatable fields with illegal repetitions
(e.g., `M~F` on PID-8) are now caught in strict mode as errors and in lenient
mode as warnings. Previously silently accepted.
## v2.1.0 — 2026-03-26
### Full v2.5.1 Segment Catalog
- **16 new segments**: ABS, AFF, BTX, EQL, ERQ, NCK, NDS, NSC, NST, ODS, ODT,
PRC, QRI, RMI, SPR, VTQ — completing the official v2.5.1 segment index
- **152/152 v2.5.1 segments** in catalog, all typed (115 fully, 37 partial)
- **89/89 v2.5.1 data types** implemented
- SCD/SDD marked as v2.6 extensions
- Fixed unused alias warning in DLT type
## v2.0.0 — 2026-03-25
### Full Standard Coverage
- **84 new segments** — all remaining v2.5.1 standard segments
- **35 new data types** — all remaining v2.5.1 data types
- **66 raw holes filled** across 13 segments
- Segment coverage: 136/136 → 152/152 (after v2.1.0 corrections)
- Type coverage: 89/89 (100%)
## v1.4.6 — 2026-03-25
### Fixes
- **Nested composite validation** — `semantic_blank?` now recurses into nested
structs. `[%XPN{family_name: %FN{}}]` is correctly detected as blank for
required-field checks.
- **Strict mode unsupported structures** — `validate(msg, mode: :strict)` now
returns errors (not warnings) for unsupported message structures.
## v1.4.5 — 2026-03-24
### Fixes
- **Escape.decode/2 crash** — malformed hex escapes (`\XGG\`, `\X4Z\`) no longer
raise `FunctionClauseError`; invalid hex bytes gracefully terminate decoding
- **parse(validate: true) warnings** — now returns `{:ok, msg, warnings}` when
validation produces only warnings (was silently discarding them as `{:ok, msg}`)
- **Empty string required fields** — `""` on required fields now caught by validation
(was passing as non-blank)
- **MLLP connection stop reason** — telemetry now carries actual reason (`:closed`,
`:timeout`, `:message_too_large`, `{:error, reason}`) instead of always `:normal`
- **Getting-started guide** — install `~> 1.4`, fixed `CX` field name (`id` not `id_number`)
- **README TLS example** — uses `HL7v2.MLLP.TLS.mutual_tls_options/1`
- **OBX moduledoc** — removed stale claim that ED/SN/RP are raw (they're typed)
- **PRD** — marked as historical
## v1.4.4 — 2026-03-24
### Fixes
- **ADT structure definitions** — 8 structures corrected against v2.5.1 spec:
A09, A12, A15, A16, A21, A24, A37, A38 had incorrect NTE (removed) and
missing OBX/DG1 (added). Structural validation now matches the standard.
- **Coverage metrics** — `mix hl7v2.coverage` now shows fully typed vs partially
typed segment split. `--detail` flag shows per-segment field completeness.
- **Builder moduledoc** — clarified as low-level constructor (does not validate)
## v1.4.3 — 2026-03-24
### Fixes
- **Structural validator strictness** — unknown non-Z segments are no longer silently
consumed during matching. They now stop the matcher and are flagged as leftover
warnings (e.g., ACC in an ACK message is now caught).
- **ADT_A02** — added OBX and PDA per v2.5.1 spec (were missing)
- **ADT_A03** — added NK1, VISIT group, AL1, GT1, INSURANCE group, ACC, PDA
per v2.5.1 spec (was incomplete)
- **Canonical aliases** — added A29, A32, A33 → ADT_A21 (were falling through)
- **Conformance roadmap** — updated to current state
## v1.4.2 — 2026-03-23
### MLLP Hardening
- **`max_message_size` option** — configurable buffer limit for both MLLP
server connections and client recv loops (default: 10 MB). Connections
exceeding the limit are closed with telemetry and logging. Protects against
memory exhaustion from misbehaving or malicious senders.
- **`handler_timeout` option** — configurable timeout for handler execution
(default: 60 s). Handlers that exceed the deadline are killed via
`spawn_monitor`/`Process.exit(:kill)`; the connection continues accepting
new messages. Telemetry event emitted on timeout.
### Property Testing
- Added delimiter-aware generators (`gen_hl7_field/0` family) that produce
fields with repetitions (`~`), components (`^`), and sub-components (`&`).
Two new property tests verify round-trip idempotency for structured messages
and individual structured fields.
### Documentation
- **Escape sequence behavior** documented in `TypedMessage` moduledoc and
README Scope section: typed field values preserve HL7 escape sequences
literally; users must call `HL7v2.Escape.decode/2` explicitly.
### Stats
2,383 tests (303 doctests + 32 properties + 2,048 tests), 0 failures
## v1.4.1 — 2026-03-23
### Fixes
- **Raw parser/encoder round-trip data corruption** — fields with mixed-structure
repetitions (e.g., `a~b^c`) were silently corrupted: the encoder misidentified
repetitions as components, encoding `a~b^c` as `a^b&c`. The parser now normalizes
each repetition to a list, making the representation unambiguous. This also fixes
the same ambiguity in the typed parser (mixed repetitions were collapsed into a
single garbled composite value).
- **`HL7v2.type/1`** — now returns `{:ok, typed}` instead of raising `MatchError`
on conversion failure. Aligns with the library's error-tuple convention.
- **README/CHANGELOG accuracy** — stale segment counts, stale ROL example (was shown
as raw tuple but is typed since v1.2.0), missing changelog entries, UB1/UB2
disclosure (mostly raw shells).
### Stats
2,376 tests (303 doctests + 30 properties + 2,043 tests), 0 failures
## v1.4.0 — 2026-03-23
### Pharmacy, Documents & Adverse Reactions
- **9 new segments**: RXO (Order, 25 fields), RXE (Encoded Order, 44 fields),
RXD (Dispense, 33 fields), RXA (Administration, 26 fields), RXR (Route, 6 fields),
RXG (Give, 27 fields), RXC (Component, 9 fields), TXA (Transcription Document Header,
23 fields), IAM (Patient Adverse Reaction, 20 fields)
- **3 new message structures**: RDE_O11 (Pharmacy Encoded Order), RDS_O13 (Pharmacy
Dispense), MDM_T02 (Document Notification and Content)
- **Segment coverage**: 52/136 (38.2%, up from 31.6%)
### Fixes
- **Atom leak in structural validator** — segment IDs from untrusted input were
converted to atoms via `String.to_atom/1`. Now uses string-based MapSet comparison.
- **Strict mode field cardinality** — field cardinality overflow escalated to `:error`
in strict mode (was always `:warning` regardless of mode).
### Stats
2,370 tests (303 doctests + 30 properties + 2,037 tests), 0 failures
## v1.3.0 — 2026-03-23
### Standards Expansion
- **6 new segments**: UB1 (UB82), UB2 (UB92 Data), CTD (Contact Data),
CTI (Clinical Trial Identification), BLG (Billing), DSC (Continuation Pointer)
- **Segment coverage**: 43/136 (31.6%, up from 27.2%)
### Stats
2,126 tests (303 doctests + 30 properties + 1,793 tests), 0 failures
## v1.2.0 — 2026-03-23
### Standards Expansion
- **8 new segments**: ROL (Role), IN2 (Insurance Additional Info, 72 fields),
IN3 (Insurance Certification, 28 fields), DRG (Diagnosis Related Group),
SPM (Specimen, 30 fields), TQ1 (Timing/Quantity), TQ2 (Timing Relationship),
PDA (Patient Death and Autopsy)
- **6 new types**: RI (Repeat Interval), SN (Structured Numeric),
ED (Encapsulated Data), RP (Reference Pointer), RPT (Repeat Pattern),
PLN (Practitioner License)
- **OBX dispatch**: Added SN, ED, RP to value_type_map
- **Segment coverage**: 37/136 (27.2%, up from 21.3%)
- **Type coverage**: 54/89 (60.7%, up from 53.9%)
- **833 declared fields** across typed segments
- All 14 previously-raw segments in supported structures now typed
(ROL, IN2, IN3, DRG, SPM, TQ1, TQ2, PDA + previously done)
- Improved structural validator diagnostics: out-of-order segments no longer
double-reported
### Stats
2,126 tests (303 doctests + 30 properties + 1,793 tests), 0 failures
## v1.1.0 — 2026-03-23
### Positional Structural Validation
- **Rewritten structural validator** — state-machine-style positional matcher that walks
the segment stream against the structure AST. Replaces flat deduplicated checks.
- Handles segments in multiple groups (ROL in PATIENT, VISIT, PROCEDURE, INSURANCE)
- Validates repeating groups per-occurrence (A39 PATIENT requires PID+MRG each time)
- Ordering enforced naturally by sequential walk
- **ADT_A01**: Added OBSERVATION group (OBX+NTE) per HL7 v2.5.1
- **ORU_R01**: Added SPECIMEN group (SPM+OBX+NTE) per HL7 v2.5.1
- **Type catalog**: Added 5 missing v2.5.1 types (CD, DLT, DTN, ICD, MOP) — 89 total
- **Type coverage**: 48/89 (53.9%, corrected from inflated 57.1%)
- 10 new structural validation tests
### Stats
1,933 tests (266 doctests + 30 properties + 1,637 tests), 0 failures
## v1.0.0 — 2026-03-23
### M6: Conformance Platform
- **HL7 table validation** — 20 coded-value tables from HL7 v2.5.1 (administrative sex,
patient class, message type, processing ID, acknowledgment codes, observation status,
value types, identifier types, and more). Opt-in via `validate(msg, validate_tables: true)`.
- **Table-aware field validation** — 11 coded fields checked against their HL7 tables:
MSH-9.1, MSH-11.1, MSH-12.1, MSH-15, MSH-16, PID-8, PV1-2, PV1-4, MSA-1, OBX-2, OBX-11
- **Tables API** — `HL7v2.Standard.Tables.valid?(table_id, code)`, `validate/2`, `get/1`
- 26 new table validation tests
### Stats
1,921 tests (266 doctests + 30 properties + 1,625 tests), 0 failures
## v0.9.0 — 2026-03-23
### M5: Broad Clinical Coverage
- **8 new segments**: SFT (Software), PD1 (Patient Additional Demographic),
PR1 (Procedures), AIG/AIL/AIP (Scheduling Resources), DB1 (Disability),
ACC (Accident)
- **Segment coverage**: 29/136 standard segments (21.3%, up from 15.4%)
- **647 declared fields** across typed segments
- All segments referenced in ADT/ORU/SIU message structure definitions are now
typed (except ROL, DRG, IN2, IN3 which are lower priority)
- 98 new tests across 8 test files
### Stats
1,893 tests (266 doctests + 30 properties + 1,597 tests), 0 failures
## v0.8.0 — 2026-03-23
### M4: Datatype Expansion
- **TQ type** — Timing/Quantity (12 components) — closes raw holes in OBR-27, ORC-7, SCH-11
- **ELD type** — Error Location and Description (4 components) — closes raw hole in ERR-1
- **SPS type** — Specimen Source (7 components) — closes raw hole in OBR-15
- **TM type** — Time primitive (HH[MM[SS[.SSSS]]][+/-ZZZZ]) — added to OBX-5 dispatch
- **Raw holes**: 6 → 1 (only OBX-5 remains, by design — uses dispatch)
- **Type coverage**: 48/84 standard types (57.1%, up from 52.4%)
- 56 new tests + 25 new doctests
### Stats
1,795 tests (266 doctests + 30 properties + 1,499 tests), 0 failures
## v0.7.0 — 2026-03-22
### M3: Structural Validation
- **Structural validator** — `HL7v2.Validation.Structural` checks segment ordering,
group anchors, and cardinality against group-aware message structure definitions.
Replaces presence-only validation for all 20 supported message structures.
- **Strict/lenient modes** — `HL7v2.validate(msg, mode: :strict)` treats ordering and
cardinality violations as errors. Default `:lenient` mode reports them as warnings.
- **Order checking** — Detects when segments appear in wrong order relative to the
abstract message definition (e.g., OBX before OBR in ORU_R01)
- **Cardinality checking** — Flags non-repeating segments that appear multiple times
- **28 structural tests** — Positive and negative cases for ADT_A01, ORU_R01, ORM_O01,
SIU_S12, ACK, ADT_A39 including missing anchors, wrong order, duplicates, Z-segments
### Stats
1,700 tests (241 doctests + 30 properties + 1,429 tests), 0 failures
## v0.6.0 — 2026-03-22
### M2: Standard Model
- **HL7v2.Standard** — Single source of truth for HL7 v2.5.1 metadata: segment catalog
(~136 entries), type catalog (~84 entries), capability tiers (`:typed` / `:unsupported`)
- **MessageStructure** — Group-aware abstract message definitions for 20 structures
(ADT A01-A39, ORM_O01, ORU_R01, SIU_S12, ACK). Includes groups, anchors, cardinality
and optionality per the HL7 v2.5.1 abstract message definitions.
- **Coverage ledger** — `HL7v2.Standard.Coverage` computes typed segments, raw holes,
unsupported types, and coverage percentages
- **`mix hl7v2.coverage`** — Prints human-readable coverage report to stdout
- **Conformance tests** — `test/hl7v2/conformance/` with structure metadata validation
(27 tests) and fixture round-trips for ADT_A01, ORU_R01, ORM_O01, SIU_S12, ACK
- **MessageDefinition** now delegates to MessageStructure for presence validation,
extracting required segments from group-aware definitions
### Stats
1,672 tests (241 doctests + 30 properties + 1,401 tests), 0 failures
## v0.5.6 — 2026-03-22
### Fixes
- **DTM encode precision** — DateTime/NaiveDateTime encode now caps fractional seconds
at 4 digits per HL7 v2.5.1 spec (was emitting up to 6, which the parser couldn't
re-parse)
- **fetch/2 raw tuple bounds** — `fetch(msg, "PR1-99")` on raw tuple segments now
returns `{:error, :field_not_found}` instead of `{:ok, nil}` for out-of-range fields
- **Type count** — README: "43 v2.5.1 types + legacy TN" (TN is deprecated, not in the
v2.5.1 data-structure catalog)
- **Implementation plan** — Marked as historical reference, no longer claims "COMPLETE"
## v0.5.5 — 2026-03-22
### Fixes
- **fetch/2 component bounds** — `fetch(msg, "PID-5.99")` now returns
`{:error, :component_not_found}` instead of `{:ok, nil}` for out-of-range
component indices on typed fields
- **MRG/RGS tests** — Added parse/encode/round-trip tests for both segments
(were at 0% coverage). Added SIU^S12 integration test with RGS.
- **Parser docs** — Changed "preserves the original wire format exactly" to
"canonical round-trip fidelity" (line endings are normalized to CR)
## v0.5.4 — 2026-03-22
### Fixes
- **Validation return shape** — `validate/1` now returns `{:ok, warnings}` when only
warnings are present, instead of treating warnings as errors. Warnings-only results
no longer block `parse(..., validate: true)`.
- **Install snippet** — README updated from `~> 0.1` to `~> 0.5`
- **Segment count** — README now says "21 standard segments + generic ZXX" (was counting
ZXX as a standard segment)
- **Raw tuple access** — README now documents that component/repetition selectors are not
applied to raw tuples (only typed segments get full descent)
- **Segment reference** — docs/reference/segments.md now says "13 of 21" segments
documented (was claiming all 22)
## v0.5.3 — 2026-03-22
### Additions
- **MRG segment** — Merge Patient Information (7 fields), registered in typed parser.
ADT^A39-A42 merge workflows now fully typed end-to-end.
- **OBX dispatch** — Extended value_type_map with CQ, MO, DR, XON, CP, FC, TN. All
implemented types now available for OBX-5 dispatch.
### Fixes
- **Builder separator** — `Message.to_raw/1` now derives separators from MSH instead
of hardcoding defaults. Custom-delimiter builder messages encode correctly.
- **NM whitespace** — `original` field now preserves raw wire value including any
whitespace for lossless round-trip. `value` field still uses trimmed+normalized form.
- **README accuracy** — 22 segments (was 21), ~95% coverage (was 95%+), explicit note
about raw holes (TQ, SPS, ELD fields)
## v0.5.2 — 2026-03-22
### Fixes
- **Subcomponent separator** — Non-default sub-component separators (e.g., `$` in
MSH-2 `^~\$`) now preserved through typed round-trip. Previously hardcoded as `&`
in 15 composite type modules. Uses process-dictionary-scoped separator context
threaded from the Separator struct through segment parse/encode.
- **RGS typed parsing** — RGS segment now registered in typed parser (was defined
but not dispatched, so SIU messages returned raw tuples instead of structs)
- **ADT_A12** — ADT^A12 (Cancel Transfer) now correctly mapped to ADT_A12, not ADT_A09
- **Presence validation** — Renamed "structure validation" to "presence validation"
throughout docs to clarify scope (no ordering/group/cardinality)
- **Docs accuracy** — Fixed DICOM PS3.x citation in message-structures.md (was wrong
standard), updated README coverage numbers
## v0.5.1 — 2026-03-22
### Fixes
- **ORM_O01 / ORU_R01** — PID is now optional (patient group is optional per spec)
- **SIU_S12** — RGS required as resource group anchor; PID now optional; AIS optional
within the resource group
- **Primitive extra components** — Non-conformant input like `M^EXTRA` on primitive
fields now preserved through typed round-trip instead of being silently truncated
- **Canonical structure mappings** — Added ADT^A12 and SIU S18-S24 to match the
documented reference
## v0.5.0 — 2026-03-22
### Conformance Hardening
- **Extra fields preservation** — Typed segments now capture fields beyond the declared
count in `extra_fields`, preventing silent data loss on messages with trailing standard
fields (e.g. OBX-20 through OBX-25)
- **MSH-2 validation** — Reject malformed encoding characters: overlong (6+), field
separator collision, duplicate delimiters
- **CNN type** — Composite Number and Name without Authority (11 components, flat HD)
- **NDL type** — Name with Date and Location (11 components with CNN sub-components)
- **OBR fields 32-35** corrected from XCN to NDL per HL7 v2.5.1
- **NM lexical preservation** — `original` field preserves raw wire format (`+01.20`
round-trips as `+01.20`, not `1.2`)
- **DTM offset preservation** — Malformed timezone offsets preserved instead of silently
dropped
- **Message definition completeness** — Canonical structure mapping moved to single source
of truth in `MessageDefinition`
### Stats
44 type modules (36 composite + 8 primitive), 20 segments + ZXX, 1,620 tests, 0 failures
## v0.4.0 — 2026-03-22
### Ergonomics & Polish
- **`~h` sigil** — Compile-time validated HL7v2 path access (`~h"PID-5.1"`)
- **`fetch/2`** — Error-returning path access (`{:ok, value}` or `{:error, reason}`)
- **String.Chars protocol** — `to_string/1` on RawMessage, TypedMessage, and Message
- **Truncation character** — v2.7+ 5th encoding character support
- **Wildcard paths** — `OBX[*]-5` returns all OBX observation values, `PID-3[*]` returns
all repetitions
- **Copy mode** — `parse(text, copy: true)` prevents GC pressure on long-lived messages
- **Unknown segment handling** — ZXX pass-through for vendor Z-segments and unrecognized
standard segments
- **Benchmarks** — Parse/encode throughput benchmarks
### Fixes
- 4 rounds of analyst review fixes: scope claims, data correctness bugs, doc
accuracy, fetch/2 error semantics
### Stats
42 type modules, 20 segments + ZXX, 1,470 tests, 0 failures
## v0.3.0 — 2026-03-22
### Type Coverage Push
- **16 new composite types** — XCN, CP, MO, FC, JCC, CQ, EIP, DLD, DLN, ERL, MOC, PRL,
AUI plus others; 97% of segment fields now typed (up from ~60%)
- **Path-based access API** — `HL7v2.Access.get(msg, "PID-5.1")` for field/component/
repetition extraction
- **Message structure definitions** — 9 message types (ADT_A01-A04/A08, ORM_O01, ORU_R01,
SIU_S12, ACK) with required/optional segment rules
- **Property-based tests** — 25 StreamData properties for parser/encoder round-trip
- **Coverage** — 81% to 96%+ with 244 additional tests
- **ExDoc** — Module groups, getting-started guide, hex.pm package metadata
### Stats
42 type modules (34 composite + 8 primitive), 20 segments + ZXX, 1,132 tests, 0 failures
## v0.2.0 — 2026-03-22
### Feature-Complete MVP
- **20 typed segment structs** — MSH, EVN, PID, PV1, PV2, NK1, OBR, OBX, ORC, MSA, ERR,
NTE, AL1, DG1, IN1, SCH, AIS, GT1, FT1 via DRY behaviour macro; plus ZXX generic
Z-segment
- **Typed parser** — Raw message to typed segment struct conversion with OBX-5 VARIES
dispatch
- **Message builder** — `HL7v2.Message.new/3` with auto-populated MSH (timestamp, control
ID, version, processing ID)
- **ACK/NAK builder** — `HL7v2.ack/2` with sender/receiver swap
- **Validation engine** — Opt-in required-field and segment-presence checks
- **MLLP transport** — Ranch 2.x TCP listener, GenServer client, TLS/mTLS support
- **Telemetry** — Instrumented parse, encode, and MLLP operations
- **26 base type modules** — 12 primitives (ST, NM, SI, ID, IS, TX, FT, TN, DT, DTM, TS,
NR) + 14 composites (CX, XPN, XAD, XTN, CE, CWE, HD, PL, EI, MSG, PT, VID, CNE, XON,
FN, SAD, DR)
### Stats
26 type modules, 20 segments + ZXX, 319 tests, 0 failures
## v0.1.0 — 2026-03-22
### Initial Release — Core Parser
- **Separator parsing** — Field, component, repetition, escape, sub-component delimiters
from MSH
- **Escape/unescape** — Full HL7v2 escape sequence handling (`\F\`, `\S\`, `\R\`, `\E\`,
`\T\`, hex `\Xhh\`, `\Cxxyy\`, `\Mxxyyzz\`)
- **Raw parser** — Lossless message parsing with CR/LF/CRLF line-ending normalization
- **Encoder** — Wire-format serialization with iodata performance and trailing-empty
trimming
### Stats
Core foundation, 45 tests, 0 failures
