tessera
0.3.0indexedParses, validates, and generates ICAO Doc 9303 MRZs (TD1/TD2/TD3/MRV-A/MRV-B), exposing raw fields, computed values, and structured validation results for integrator decisions.
2
Stars
—
Used by
dependents
—
Health
/ 100
Tessera
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.
What it does
What it deliberately does not do
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.
Quick example
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())
(result) {
ParseResult.Success -> {
doc = result.document TD3
println()
println()
}
ParseResult.PartialSuccess -> {
}
ParseResult.Failure -> {
println()
}
}
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.
Installation
Tessera is published to Maven Central under the io.lightine.tessera group. The current release is 0.4.0 (JVM + Android; iOS via Swift Package Manager — see Platforms).
Gradle (Kotlin DSL)
Use the BOM to keep every Tessera module on one version:
dependencies {
implementation(platform("io.lightine.tessera:tessera-bom:0.4.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.4.0")
tessera-mrz-core pulls in tessera-types transitively — most integrators need only this one module.
Maven
<dependency>
<groupId>io.lightine.tessera</groupId>
<artifactId>tessera-mrz-core</artifactId>
<version>0.4.0</version>
</dependency>
Swift Package Manager (iOS)
In Xcode: File → Add Package Dependencies…, enter https://github.com/lightine-io/tessera-swift, and choose 0.4.0. Or in a Package.swift:
dependencies: [
.package(url: "https://github.com/lightine-io/tessera-swift", from: "0.4.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.
Documentation
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).
For integrators
For contributors
For maintainers
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
Platforms
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.4.0:
- JVM — the pure core logic (parsing, validation, generation, lookup tables, transliteration profiles, telemetry contract)
- Android — core logic plus headless live-camera and saved-image reading (CameraX + ML Kit). Minimum API level 23 (Android 6.0), per ADR-018
- iOS — core logic plus headless live-camera and saved-image reading (AVFoundation + Apple Vision), distributed as an XCFramework 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.
Versioning
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.
License
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.
Security
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
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.
Acknowledgments
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.