A vendor-neutral SDK for reading, validating, and generating identity document data.
Tessera reads Machine Readable Zones (MRZ) from passports, national ID cards, residence permits, machine-readable visas, and similar travel documents conforming to ICAO Doc 9303. It returns extracted data verbatim, with structured validation results — leaving all trust decisions to the integrating application.
Status: In active
0.xdevelopment.v0.5.0is the current release on Maven Central (io.lightine.tessera), adding the default scanner UI — an optional, out-of-the-box MRZ scanner screen on both platforms (MrzScannerScreenintessera-mrz-camera-ui-android, Jetpack Compose;MrzScannerViewinTesseraUIvia tessera-swift, SwiftUI) layered over the headless APIs — on top of the0.2.xlive-camera,0.3.xsaved-image, and0.4.xmanual-entry reading — see Installation andCHANGELOG.md. The1.0.0milestone marks the public-stability and open-source release commitment per ADR-011; pre-1.0.0releases follow the same strict backward-compatibility commitments as post-1.0.0releases. Seedocs/versioning.mdfor the policy.
- Parses all ICAO Doc 9303 MRZ formats: TD1, TD2, TD3, MRV-A, MRV-B
- Validates structurally, by check digit, and semantically — without making trust decisions
- Generates valid MRZs from structured input, supporting round-trip use cases
- Exposes everything it extracts — raw fields, computed values, validation results, and warnings — so the consumer always knows what was observed and what was inferred
- Reads MRZ from a live camera or a saved image — headless: Android (CameraX + ML Kit) and iOS (AVFoundation + Apple Vision) read live frames or a pre-captured image file through the same parser, with the consumer owning all UI. You can also supply the MRZ string directly, or read a human-typed MRZ through the manual-entry reading method (
ManualMrzReader). NFC-chip reading is planned for a later release (0.6.0— see the roadmap). - Runs anywhere the core technology stack supports — initial mobile targets (Android, iOS) plus future support for backend, desktop, and web
Tessera is a reader, not an oracle. It surfaces observations; the consumer makes trust decisions. Specifically, the SDK does not:
- Decide whether a document is "valid" or "trustworthy" — that depends on the consumer's threat model
- Verify document authenticity against external registries
- Perform face matching or liveness detection (these may be added later as separate capabilities)
- Store any data — no persistence, no caching, no telemetry by default
- Phone home — no network calls, no analytics, no licensing checks
These are deliberate boundaries. See docs/principles.md for the reasoning.
This example compiles against the published API (verified symbol-by-symbol; the project's documentation rules require it). The public API follows strict backward compatibility throughout 0.x (ADR-007).
val result = MrzParser.parse("""
P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<
L898902C36UTO7408122F1204159ZE184226B<<<<<10
""".trimIndent())
when (result) {
is ParseResult.Success -> {
val doc = result.document as TD3 // io.lightine.tessera.mrz.model.TD3
println("Name: ${doc.commonFields.primaryIdentifier}, ${doc.commonFields.secondaryIdentifier}")
println("Document number: ${doc.commonFields.documentNumber}")
// ... use the parsed data
}
is ParseResult.PartialSuccess -> {
// Data extracted, but some validations failed.
// Read result.document and result.metadata.validationFailures to decide.
}
is ParseResult.Failure -> {
// The input was structurally too broken to construct a document.
println("Parse failed: ${result.error}")
}
}The result type makes the three possible outcomes explicit. The consumer cannot accidentally treat a PartialSuccess as a Success.
More examples — validation, generation, transliteration, live-camera scanning — are in the feature guides; every guide has a copy-paste Usage section.
Tessera is published to Maven Central under the io.lightine.tessera group. The current release is 0.5.0 (JVM + Android; iOS via Swift Package Manager — see Platforms).
Use the BOM to keep every Tessera module on one version:
dependencies {
implementation(platform("io.lightine.tessera:tessera-bom:0.5.0"))
implementation("io.lightine.tessera:tessera-mrz-core") // MRZ parsing, validation, generation
}Or pin the module version directly, without the BOM:
implementation("io.lightine.tessera:tessera-mrz-core:0.5.0")tessera-mrz-core pulls in tessera-types transitively — most integrators need only this one module.
<dependency>
<groupId>io.lightine.tessera</groupId>
<artifactId>tessera-mrz-core</artifactId>
<version>0.5.0</version>
</dependency>In Xcode: File → Add Package Dependencies…, enter https://github.com/lightine-io/tessera-swift, and choose 0.5.0. Or in a Package.swift:
dependencies: [
.package(url: "https://github.com/lightine-io/tessera-swift", from: "0.5.0"),
]Then import Tessera. The iOS binary ships as the Tessera XCFramework (minimum deployment target iOS 18, per ADR-018). The Swift surface is provisional through the 0.x line — see tessera-swift.
Android ships the same coordinates as AAR artifacts (e.g.
tessera-mrz-camera-androidfor live-camera reading) — use the Gradle/Maven blocks above. See Platforms for the per-target capability matrix.
The project's documentation is structured for two audiences: integrators (who want to use the SDK) and contributors (who want to understand or extend it).
docs/scope.md— what the SDK supports, what it does not, and what is planneddocs/getting-started.md— dependency → parse → validate → generate in ten minutesdocs/guides/android-integration.md— Android: from empty app to a working live-camera MRZ scandocs/guides/ios-integration.md— iOS: the same journey in Swift, including the provisional Flow-collection patterndocs/features/— usage guides for every capability, each with a copy-paste Usage example- API reference — KDoc ships as javadoc jars with every module on Maven Central (your IDE picks them up automatically); a hosted Dokka site is a tracked deferral in the project's issue tracker
docs/reading-risks.md— what each reading method establishes, what it does not, and what additional verification might be needed- Glossary — YouTrack KB — definitions of MRZ, eMRTD, BAC, PACE, and other terms used throughout the documentation
docs/versioning.md— versioning policy and release commitments
docs/principles.md— the foundational principles every design decision honorsdocs/architecture.md— module structure, dependency graph, and technology choicesdocs/conventions.md— how documentation is written, how decisions are made, how contributions happendocs/testing.md— testing discipline (tests alongside implementation, synthetic data only)docs/contributor-setup.md— one-time machine setup for contributors (clone, Git identity, SSH commit signing)docs/decisions/— Architecture Decision Records capturing the reasoning behind major choices- the project's issue tracker — decisions that have been deliberately deferred, tracked so they are not forgotten
docs/publishing-setup.md— one-time setup for publishing to Maven Central (PGP signing key, Sonatype Central Portal user token, Gradle credential storage). Maintainer-only; contributors do not need this
Tessera is built with Kotlin Multiplatform. Targets activate per-release as the corresponding reading methods land — see docs/scope.md for the full roadmap.
Active as of 0.5.0:
- JVM — the pure core logic (parsing, validation, generation, lookup tables, transliteration profiles, telemetry contract)
- Android — core logic plus headless live-camera, saved-image, and manual-entry reading (CameraX + ML Kit), and the optional default scanner UI (
tessera-mrz-camera-ui-android, Jetpack Compose). Minimum API level 23 (Android 6.0), per ADR-018 - iOS — core logic plus headless live-camera, saved-image, and manual-entry reading (AVFoundation + Apple Vision), and the optional default scanner UI (
TesseraUI, SwiftUI), distributed via Swift Package Manager. Minimum deployment target iOS 18, per ADR-018
The architecture supports further targets — Web (JS / Wasm), Desktop (JVM and native) — without changes to the core logic. They are not part of the initial releases but can be activated when there is a use case.
Tessera follows Semantic Versioning 2.0.0 with strict backward-compatibility commitments from the first release onward — including the 0.x line. This is stricter than the convention in many open source projects, where 0.x signals "API may change without notice." The choice is deliberate: see docs/versioning.md for the reasoning.
Tessera is released under the Apache License 2.0. The full license text is in the LICENSE file at the project root. See docs/decisions/0010-apache-2-license.md for the reasoning behind the license choice.
Tessera is used in trust-related contexts. Security reports are taken seriously and handled privately. See SECURITY.md for the disclosure process, the supported-versions matrix, and what is in and out of scope.
CONTRIBUTING.md is the short pointer for new contributors; docs/conventions.md holds the full contribution rules; docs/contributor-setup.md covers one-time machine setup. The short version:
- Decisions of architectural or scope significance are recorded as ADRs
- Disagreement is welcome — the project's culture is dispute-driven, grounded in the principles
- New conventions are added through normal contribution: proposal, discussion, agreement, then an edit
The project is in active 0.x development. The formal open-source release happens at 1.0.0 per ADR-011.
Tessera builds on the work of the International Civil Aviation Organization (ICAO), whose Doc 9303 series defines the standards this SDK implements. The SDK references those standards rather than reproducing them.
The project's design owes a debt to the broader open source community's work on identity document standards, MRZ parsing libraries that came before, and the Kotlin Multiplatform ecosystem that makes shared cross-platform logic practical.