Backend-independent application contracts and values implemented by the configured Jackson 2 and Jackson 3 runtimes. This module defines contracts and values; it has no standalone Jackson runtime.
| Package | Responsibility |
|---|---|
com.kazforge.jsonapi |
Supported-package overview and cross-package invariants |
com.kazforge.jsonapi.api |
Level-1 JsonApi root and resource, relationship, document, and PATCH facets |
com.kazforge.jsonapi.document |
Document read contexts, primary-data kind, and write envelope |
com.kazforge.jsonapi.mapping |
Mapping, provenance, decoration, typed-envelope, registry, and identifier-meta contracts |
com.kazforge.jsonapi.patch |
Presence, command, change, and structured PATCH contracts |
com.kazforge.jsonapi.representation |
Include/fieldset selection and application policy |
com.kazforge.jsonapi.diagnostic |
Stable codec/mapping diagnostics and locations |
Each package's documentation owns its invariants. The packages carry backend-independent contract
and value shapes only: configured Jackson in each adapter derives the observable property
semantics, and backend-neutral mapping implementation lives in the unsupported
jsonapi-java-mapping module.
An adapter supplies the implementation; application code can depend on the neutral interface:
JsonApi api = /* Jackson 2 or Jackson 3 configured runtime */;
Article article = api.resources().readOne(json, Article.class);
String rendered = api.resources().writeOne(article);
ArticlePatch patch = api.patches().readPatch(updateJson, ArticlePatch.class);JsonApi groups ordinary resource, linkage-document, raw-document, and PATCH operations. Advanced
major-specific readers, writers, mapping/binding, parameterized Jackson types, and heterogeneous
typed envelopes remain adapter capabilities. ADR-012
owns that split.
- No production signature imports
tools.jackson.*,com.fasterxml.jackson.*, or a major-specific adapter package. - This artifact ships only supported contract packages. Cross-artifact mapping helpers live in
jsonapi-java-mapping's unsupported internal namespace, and native wire/codec helpers stay in each adapter's internal package; neither may appear in supported public signatures per ADR-015.
The java-test-fixtures variant provides passive, major-neutral application-shaped DTOs, the
canonical JSON corpus,
pinned draft schemas, the
neutral TestFixtureResources loader, and the shared characterization contract specs in
com.kazforge.jsonapi.fixtures.contract,
which every adapter runs through a concrete subclass. AGENTS.md owns the fixture
and contract-spec policy.
See the architecture overview and conformance checklist.