Native Jackson 2 implementation of the major-neutral Level-1 JSON:API contract, plus advanced document codec, mapping, flat binding, typed-envelope, and PATCH capabilities.

The minimum supported and published dependency baseline is Jackson 2.21.7 for jackson-databind and jackson-datatype-jdk8, on the sustainable 2.21 LTS line. Consumer or framework dependency management may select newer compatible Jackson 2 versions.

The separate current-test Jackson 2 version reference lives in the version catalog. Renovate maintains that reference without raising the published minimum. See the build commands for minimum and current test runs and the dependency policy for publication and framework boundaries.

import com.fasterxml.jackson.databind.json.JsonMapper;

JsonMapper mapper = JsonMapper.builder().build();
Jackson2JsonApi api = JsonApiJackson2.jsonApi(mapper);

String json = api.resources().writeOne(article);
Article readBack = api.resources().readOne(json, Article.class);
ArticlePatch patch = api.patches().readPatch(updateJson, ArticlePatch.class);

The runtime implements the neutral JsonApi facets: resources, linkage relationships, raw documents, and PATCH. Resource reads are strict and homogeneous; create/update authoring selects the corresponding core validation usage. Use JsonApiJackson2.builder(mapper) for application-lifetime identifier conversion, linkage mappers, representation policy, decorators, or an optional default jsonapi.version. Selection, document envelopes, and expected update identity remain per-operation values.

JsonApiJackson2 creates each capability from a caller-configured JsonMapper:

Use them when Level 1 is not enough, for example a parameterized root JavaType, heterogeneous typed envelopes over an explicit ResourceTypeRegistry, or direct codec and mapping composition. Each type's Javadoc owns its contract.

Neutral contracts come from jsonapi-java-api and backend-neutral mapping semantics from jsonapi-java-mapping. This adapter implements their capability interfaces over configured Jackson 2: property and type discovery, naming, conversion, construction, and native diagnostics. The architecture overview owns that split.

• Production integration uses com.fasterxml.jackson.* and must not import tools.jackson.* or com.kazforge.jsonapi.core.internal.
• Advanced reader and writer APIs retain checked IOException. Level-1 operations adapt unavoidable stream failures to UncheckedIOException; payload failures remain in the document-read family.
• Caller-owned streams, writers, parsers, and generators remain open. Convenience-created parser or generator resources are closed by the adapter.
• Factories never mutate the caller mapper. Derived mapping/binding mappers install JDK 8 Optional support only when a behavioral probe shows the caller configuration does not already provide it.
• The public composition package may depend on mapping and the two internal responsibilities; mapping and internal.codec do not depend back on composition or on sibling internals.
• Supported signatures do not expose the unsupported com.kazforge.jsonapi.mapping.internal helpers or this adapter's internal implementation packages, and this module does not redeclare neutral contract types.
• Jackson 2 property-writer, serializer/deserializer, and checked-I/O mechanics stay adapter-local.

This module does not provide HTTP or media-type policy, query parsing, field authorization, persistence lookup or projection execution, graph hydration, PATCH authorization, or mutation of application state. It does not detect another Jackson major at runtime.

See the architecture overview, conformance checklist, ADR-004, and ADR-012.