mrz
Zero-dependency ICAO Doc 9303 Machine Readable Zone parser, emitter and check-digit validator for Rust.
A valid composite check digit is mathematical proof that an OCR read is
faithful to the printed document — not a probability, not a model score. mrz
verifies every printed check digit under the standard 7-3-1 weighting and
reports the result per field, so you always know which digit proved the read,
and which one failed.
The crate has no runtime dependencies and compiles to
wasm32-unknown-unknown as readily as to native targets.
▶ Try it in your browser — live WASM MRZ validator.
Contents
- Install · Supported formats · Quick start
- Parsing — OCR text · long document numbers · unknown dates
- Emitting — national characters
- What a check digit cannot prove — expiry · blind character pairs · structural guards
- Conformance · Feature flags · MSRV · License
Install
[]
= "0.6"
Supported formats
| Format | Document | Layout | Parse | Emit |
|---|---|---|---|---|
| TD3 | Passports | 2 lines × 44 | ✅ | ✅ |
| TD2 | Official travel documents / IDs | 2 lines × 36 | ✅ | ✅ |
| TD1 | ID cards | 3 lines × 30 | ✅ | ✅ |
| MRV-A | Visas (passport-book) | 2 lines × 44 | ✅ | ✅ |
| MRV-B | Visas (smaller) | 2 lines × 36 | ✅ | ✅ |
Quick start
let doc = parse_td3.unwrap;
assert_eq!;
assert_eq!; // expanded to ISO 8601
// Per-field proof, not a single boolean.
assert!;
assert!;
assert!;
assert!; // every check digit verified
parse_td1, parse_td2, parse_mrv_a and parse_mrv_b cover the other
formats, each with a *_with variant taking ParseOptions.
Parsing
Scan free-form OCR text
find_and_parse locates an MRZ inside noisy OCR output — it tolerates
HTML-escaped fillers and lines merged onto one physical line — and drives a
check-digit-guided repair pass. A candidate reading is accepted only when its
composite check digit proves it.
let text = "## REPUBLIC OF UTOPIA\n\
P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<\n\
L898902C36UTO7408122F1204159ZE184226B<<<<<10";
let doc = find_and_parse.expect;
assert_eq!;
assert_eq!;
assert!;
Long document numbers
When a document number exceeds the 9-character field, Doc 9303 puts the nine
principal characters in the field, a filler in the check-digit position, and
the remainder plus its check digit at the front of the optional-data field.
mrz emits and reads that form, exposing both the printed field and the
reassembled number:
use ;
let lines = format_td3;
let = lines.split_once.unwrap;
let doc = parse_td3.unwrap;
assert!;
assert_eq!; // the printed 9-char field
assert_eq!; // the reassembled number
assert!; // read as the Doc 9303 form
This is normative for TD1 and TD2 (Part 5 and Part 6, note j). Part 4 defines no overflow rule for TD3, so applying it there is a deliberate extension by analogy, made because issuers do it in practice; Part 7 defines none for MRV-A/MRV-B, so visas never overflow. When the remainder does not fit the optional field, the number truncates to 9 characters instead.
The parser also accepts the eight-character encoding this crate emitted before
0.6.0, flagging it via document_number_legacy_encoding.
Unknown and partial dates
Doc 9303 Part 3 §4.8 lets an issuer complete an unknown date of birth with
filler characters, and §4.9 gives a filler the value zero for check-digit
purposes. An entirely unknown date of birth with check digit 0 is therefore a
valid field, not a corrupt read:
use ;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
MrzData::date_of_birth_completeness carries this for a parsed document. It is
how a caller separates "the issuer conformantly recorded an unknown date" from
"the OCR failed" — both leave date_of_birth holding the raw field rather than
an ISO date, and the raw YYMMDD is not recoverable afterwards, since a known
date has been reshaped to ten characters.
Emitting
All five formats emit — format_td3 / format_td2 / format_td1 /
format_mrv_a / format_mrv_b, each taking its own *Fields struct in
MRZ-native form (YYMMDD dates, uppercase text). Every check digit is computed
for you, so output always round-trips back through the matching parser as
valid().
use ;
let lines = format_td3;
let = lines.split_once.unwrap;
assert!;
Td1Fields and Td2Fields follow the same shape, with optional_data_1 +
optional_data_2 and optional_data respectively:
use ;
let td1 = format_td1;
assert_eq!; // three 30-char lines
National characters are transliterated, not dropped
Doc 9303 Part 3 §6 A defines a recommended transliteration for Latin national
characters that do not fit the MRZ's [A-Z0-9<] alphabet. The emitters apply
it automatically, so accented letters survive instead of being deleted:
use ;
let lines = format_td3;
let line1 = lines.split_once.unwrap.0;
assert!;
assert!;
Five of the table's 95 characters have more than one ICAO-recommended
transliteration, and the issuing State chooses among them. transliterate
exposes that choice rather than pretending to a single canonical answer:
use ;
assert_eq!;
assert_eq!;
assert_eq!; // only one ICAO answer
This crate can produce a conformant transliteration; it cannot validate one, because the standard admits several correct answers. Only Latin-based characters (§6 A) are implemented — Cyrillic (§6 B) and Arabic (§6 C) are out of scope.
What a check digit cannot prove
Check digits are the crate's strongest guarantee, so its limits are worth stating as precisely as the guarantee itself.
It does not prove the document is in date
A verified composite proves the read is faithful. Whether the document is
expired, or its dates are internally consistent, is a separate and
non-cryptographic judgement — MrzData::validity(today), which takes an
explicit reference date so the crate stays deterministic and clock-free:
use ;
// The ICAO specimen (Utopia / Anna Maria Eriksson): expires 2012-04-15.
let doc = parse_td3
.unwrap;
assert!; // the read is checksum-proven ...
let report = doc.validity;
assert!; // ... and, as of 2010, still in date
assert!;
// The same faithful read, judged against a later day: still valid(), expired.
assert!;
It cannot distinguish characters congruent mod 10
A check digit is a 7-3-1 weighted sum taken mod 10 (Part 3 §4.9), so it
sees only each character's value mod 10. Two characters are indistinguishable
to every check digit exactly when their values are congruent — and
blindspot says so outright:
use ;
// The OCR confusion everyone worries about is CAUGHT ...
assert!;
// ... and the quiet one nobody mentions is not.
assert!;
// The complete blind set for a character, not a sample of it.
assert_eq!;
That inversion is the point:
| Pair | Verdict | Why |
|---|---|---|
| O ↔ 0 | caught | 24 vs 0 — differ mod 10 |
| I ↔ 1 | caught | 18 vs 1 |
| B ↔ 8 | caught | 11 vs 8 |
| S ↔ 5 | caught | 28 vs 5 |
| Z ↔ 2 | caught | 35 vs 2 |
K ↔ < |
blind | 20 vs 0 — congruent mod 10 |
| I ↔ S | blind | 18 vs 28 |
| B ↔ L | blind | 11 vs 21 |
| A ↔ K | blind | 10 vs 20 |
mrz::CLASSES is the whole atlas: ten residue classes partitioning the
37-character alphabet. Class 0 is 0 A K U < — five members, because the
filler and the digit zero share a value. Any substitution within a row is
provably undetectable; any substitution across rows is caught.
cargo run -p mrz --example checksum_blindspots demonstrates this
empirically — it mutates the ICAO specimen character by character and asks the
real parser, rather than asserting the algebra at you.
Structural guards
Because the arithmetic has a known blind set, the crate layers structural checks on top of it: recognized country codes, date plausibility, and name charset rules.
use ;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
The table covers the full Doc 9303 Part 3 §5 registry — ISO 3166-1 codes plus
the ICAO extensions, United Nations codes, stateless/refugee codes, deprecated
codes kept for backward compatibility, and the specimen code UTO.
Conformance
mrz is verified against the ICAO Doc 9303 text rather than against memory of
it. Worked examples published in the standard — composite check digits, name
encodings, transliterations — are pinned as test vectors, and the crate
documents where the standard is silent rather than inventing conformance:
- Two-digit-year century inference has no rule anywhere in Doc 9303. The pivot is this crate's policy and is documented as such.
- Name truncation is issuer-discretionary; Doc 9303 defines several strategies and states that truncation is not reliably detectable.
- Transliteration is deliberately multi-valued for five characters.
The corroboration record — which passages are relied on, how each was verified,
and which remain unverified — is kept alongside the source corpus in
CONFORMANCE_BASIS.md.
Feature flags
Both are off by default, keeping the base crate zero-dependency and wasm-clean:
serde— derivesSerialize+DeserializeonMrzData,Checks,Format,Td3Fields,Date,DateValidityandDateCompleteness.zeroize— derivesZeroizeOnDroponMrzData, wiping the PII-bearingStringfields from memory when the value is dropped.
Minimum supported Rust version
1.82. The floor is set by std::iter::repeat_n and Option::is_none_or in
the OCR repair helpers, both stabilized in that release. It applies to the
zero-dependency default build and is enforced by CI on every push; the optional
serde/zeroize features and the dev-dependency test suite follow their own
upstream MSRVs, which are higher. The MSRV is a floor, not a pin — raising it
is a minor version bump.
License
MIT