uom-jackson

Jackson modules for uom
quantities and units as JSON, for Jackson 2 and Jackson 3, on the native and the JSR-385 API

Jackson modules for uom: quantities and units as JSON, with exact decimals, typed fields and units that Jackson checks while it reads.

Usage

The format is docs/JSON.md.

// Jackson 2 (uom-jackson2)
ObjectMapper mapper = new ObjectMapper().registerModule(new UomModule());
// Jackson 3 (uom-jackson3): mappers are immutable
ObjectMapper mapper = JsonMapper.builder().addModule(new UomModule()).build();

mapper.writeValueAsString(Length.of(5, SI.KILOMETRE));              // "5.0 km"
mapper.readValue("{\"value\": 5, \"unit\": \"km\"}", Length.class);  // a Length of 5 km
mapper.readValue("\"5 s\"", Length.class);   // error: cannot read "5 s" as Length: Time [T] is not Length [L]

Modules

Artifact	For
org.tinygears:uom-jackson2	Jackson 2.x (com.fasterxml.jackson)
org.tinygears:uom-jackson3	Jackson 3.x (tools.jackson)

Both use the same JSON format and the same version number, so one release covers both.

Dependencies

uom and uom-jsr are optional dependencies of the modules. Declare the one you use, or both, and the module serves what is on the class path:

You declare	The module serves
org.tinygears:uom	the native API
org.tinygears:uom-jsr (it brings uom)	both APIs
neither	nothing: creating the module throws an IllegalStateException that names what is missing

Jackson itself is an ordinary dependency, and your own Jackson version (from your BOM or your framework) wins over the one the module is built against.

On the module path the modules requires static transitive org.tinygears.uom. Compiling a module against them needs uom (or uom-jsr, which brings it) on the module path, and the types of uom, such as the UnitFormat of the builder, are readable without an own requires. Nothing requires uom at run time, so add it to the module graph (your module requires it, or --add-modules org.tinygears.uom); the module is found by its provides, and needs no opens.

Versions

The modules are built against a baseline and are meant to work with later versions of the same major:

	Baseline
Jackson 2	2.18.12
Jackson 3	3.0.4
uom, uom-jsr	0.1.0

Until uom 1.0 any 0.x release may change its API, so only the tested combinations are supported. CI builds on JDK 17 and 25 against the baselines, and builds weekly against the latest Jackson 2, Jackson 3 and uom releases.

Build

Java 17 or later and Maven 3.9:

mvn -B verify

The tests run on three class paths, to prove that the dependencies are optional: uom and uom-jsr, uom only, and neither.

Documentation

• docs/JSON.md: the JSON format and the settings.
• CHANGELOG.md: changes per release.
• AGENTS.md: the rules for AI coding agents (CLAUDE.md links to it).

License

Apache License 2.0, see LICENSE.