Expand description
Redaction for HL7 v2 messages in ER7 (pipe-hat) encoding, in either direction: reject by default and name what survives, or accept by default and name what does not.
An HL7 v2 message is almost entirely patient detail. A process that logs one — to find a failure, to trace a flow, to answer “what happened to the message the ward is asking about?” — is putting clinical data into a store that is queried far more widely, and retained far longer, than the message store it came from. This crate is what goes between.
§Two dispositions, and which one to pick
Every field is either accepted — it survives into the output — or
rejected — it is replaced by a mask. A Policy decides which,
starting from a default disposition and applying whatever exceptions you
name.
| Starts from | You name | Use when | |
|---|---|---|---|
Policy::reject_all | reject everything | what to accept | the payload is clinical and you are publishing a little of it |
Policy::accept_all | accept everything | what to reject | the payload is already known-safe and you are removing a few known fields |
Reject by default is the safer of the two, and it is the default.
The difference is what happens when a sender adds a field nobody
anticipated: rejecting by default masks it, accepting by default
publishes it. Reach for Policy::accept_all when you genuinely know
the whole shape of what you are handling — a synthetic corpus, a message
that has already been through a redactor, a feed with no patient
content — and not merely because it is fewer lines to write.
Policy::routing_metadata is the built-in reject-by-default answer:
ten MSH fields — the routing and metadata a support engineer needs to
find one message among millions — and nothing else, from any segment.
§Shape survives, content does not
Field positions are preserved: an empty field stays empty and a populated one becomes the mask. Segment identifiers are structural and are always emitted.
use hl7_2_redact::redact;
// PID-2 is empty and PID-3 is not; both stay where they are.
assert_eq!(redact("MSH|^~\\&|A\rPID|1||X"), "MSH|^~\\&|A\rPID|***||***");That keeps visible which segments arrived, how many fields each carried, and where the gaps are — which is most of what a structural problem looks like, without any of the content.
§What this is not
Not a de-identification tool. It is a positional editor. It cannot
find an identifier written into a free-text NTE segment that a policy
accepts, and it has no opinion about whether what survives is anonymous
enough for a given purpose — that is a judgement about a whole data set,
made by a person.
Not a parser. It never allocates proportional to a declared length, and never panics on arbitrary bytes. Anything it cannot recognise as ER7 is handled whole rather than inspected, because the content of an unrecognised payload is by definition unknown. Those properties matter because the caller is usually an ingress process logging whatever arrived on a socket.
§An invalid payload: mask it, pass it, or refuse it
Unrecognised decides what happens to a payload that is not readable
as ER7 at all:
| What comes out | Use when | |
|---|---|---|
Unrecognised::Reject | the mask, in place of the whole payload | the default: safe, and always produces a log line |
Unrecognised::Accept | the payload, unchanged | you already know it is not clinical |
Unrecognised::Refuse | nothing — Policy::try_redact returns Refused | a placeholder is not good enough and the caller must decide |
Refusal is the one that needs the fallible API. *** in a log line
cannot distinguish “this was masked” from “this could not be read”, and
for a caller that must fail the operation, raise an alert, or route the
payload somewhere it can be inspected safely, that distinction is the
whole point.
use hl7_2_redact::{Policy, Refusal, Unrecognised};
let policy = Policy::routing_metadata().on_unrecognised(Unrecognised::Refuse);
// A real message is redacted as usual.
let redacted = policy.try_redact("MSH|^~\\&|A\rPID|1||SECRET")?;
assert_eq!(redacted, "MSH|^~\\&|A\rPID|***||***");
// A payload that is invalid is refused.
let error = policy.try_redact(r#"{"nhsNumber": "4444444444"}"#).unwrap_err();
assert_eq!(error.reason(), Refusal::NotAMessageHeader);
// The error names no content — only why, and how many bytes.
assert!(!error.to_string().contains("4444444444"));An empty payload is returned unchanged under every setting, refusal included: there is nothing to hide, and refusing it would turn “the payload was empty” — itself the diagnosis — into an error a caller has to unpick.
§Examples
The default policy, which is what most callers want:
use hl7_2_redact::redact;
let message = "MSH|^~\\&|252|252|100|100|20260729095037|SEC|ADT^A28^ADT_A05|MSG1|P|2.5\r\
PID|1||B0000010612^^^328^PI||SURNAME^FORENAME||20010909|M";
let redacted = redact(message);
// Routing metadata is accepted, so the message is still findable.
assert!(redacted.contains("|252|252|100|100|20260729095037|"));
assert!(redacted.contains("ADT^A28^ADT_A05"));
// The patient is not.
assert!(!redacted.contains("SURNAME"));
assert!(!redacted.contains("B0000010612"));
// MSH-8, the security field, is not accepted.
assert!(!redacted.contains("SEC"));Reject by default, additionally accepting the event type in EVN-1:
use hl7_2_redact::Policy;
let policy = Policy::routing_metadata().accept("EVN", [1]);
let redacted = policy.redact("MSH|^~\\&|A\rEVN|A28|20260729095037");
assert!(redacted.contains("EVN|A28|***"));Accept by default, rejecting two segments outright and one field elsewhere:
use hl7_2_redact::Policy;
let policy = Policy::accept_all()
.reject_segment("PID")
.reject_segment("NK1")
.reject("PV1", [7]);
let redacted = policy.redact("MSH|^~\\&|A\rPID|1||SECRET\rPV1|1|I|||||DOCTOR");
assert!(redacted.contains("MSH|^~\\&|A"), "{redacted}");
assert!(!redacted.contains("SECRET"), "{redacted}");
assert!(!redacted.contains("DOCTOR"), "{redacted}");
assert!(redacted.contains("PV1|1|I"), "{redacted}");Structs§
- Policy
- Which fields of which segments this policy names, and what happens to everything it does not.
- Refused
- A payload that
Unrecognised::Refusedeclined to redact.
Enums§
- Disposition
- What happens to a field that no exception names.
- Refusal
- Why a payload was refused.
- Unrecognised
- What to do with a payload that is not recognisable as ER7.
Constants§
- DEFAULT_
MASK - What a rejected value is replaced with, unless a policy says otherwise.
- ROUTING_
METADATA_ MSH_ FIELDS - The
MSHfield numbersPolicy::routing_metadataaccepts, in HL7’s own 1-based numbering. - SEPARATOR_
IS_ FIELD_ ONE - The segments whose field 1 is the field separator.
Functions§
- redact
- Redact a payload under
Policy::routing_metadata. - separator_
of - The field separator a message declares, if it declares one readably.