mrz
A zero-dependency ICAO 9303 Machine Readable Zone (MRZ) parser 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
exposes the result per field, so you always know which digit proved (or
failed) the read.
The core 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.
Supported formats
| Format | Document | Layout | Status |
|---|---|---|---|
| TD3 | Passports | 2 lines × 44 | ✅ parse + emit |
| TD2 | Official travel documents / IDs | 2 lines × 36 | ✅ parse + emit |
| TD1 | ID cards | 3 lines × 30 | ✅ parse + emit |
| MRV-A | Visas (passport-book) | 2 lines × 44 | ✅ parse + emit |
| MRV-B | Visas (smaller) | 2 lines × 36 | ✅ parse + emit |
Document-number overflow (ICAO 9303 part 4 §4.2.2.2) is supported for TD1/TD2/
TD3: when a document number is longer than the 9-character field, format_td3
/ format_td2 / format_td1 reassemble it automatically as long as the
remainder fits the format's optional-data field (TD3 personal number, 14
chars; TD2/TD1 optional data, 7/15 chars), and the parser reads it back into
MrzData::document_number_full:
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
When the remainder doesn't fit the optional field, the number still truncates to 9 characters as before (unchanged, pre-existing behavior). MRV-A/MRV-B visas have no overflow encoding in ICAO 9303 part 7, so this only applies to TD1/TD2/TD3.
Usage
Add it to Cargo.toml:
[]
= "0.4"
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!; // every check digit verified
Parse known lines directly
let doc = parse_td3.unwrap;
// Per-field proof, not a single boolean.
assert!;
assert!;
assert!;
parse_td1 and parse_td2 cover the other two formats.
Emit a valid MRZ
All three formats emit — format_td3 / format_td2 / format_td1, each taking
its own Td3Fields / Td2Fields / Td1Fields in MRZ-native form (YYMMDD
dates, uppercase [A-Z0-9]). Every check digit is computed for you, so the
output always round-trips back through the matching parser as valid().
use ;
let lines = format_td3;
// Round-trips: parse_td3(&lines) is valid() == true.
Td2Fields and Td1Fields follow the same shape (with optional_data /
optional_data_1 + optional_data_2 respectively):
use ;
let td1 = format_td1;
// Three 30-char lines; parse_td1 rebuilds them as valid().
A valid read is not an in-date document
A verified composite check digit proves the read is faithful — it says
nothing about whether the document is expired or its dates are internally
consistent. That separate, non-cryptographic judgement is
MrzData::validity(today):
use ;
// The ICAO 9303 part 4 specimen: 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!;
Feature flags
Both are off by default, keeping the base crate zero-dependency (and wasm-clean):
serde— derivesSerialize+DeserializeonMrzData,Checks,Format,Td3Fields,Date, andDateValidity.zeroize— derivesZeroizeOnDroponMrzData, wiping the PII-bearingStringfields from memory when the value is dropped.
License
MIT