Install JSON:API for Java with Jackson 3¶

Choose an artifact¶

Five consumer artifacts are published together on one release train:

Artifact (`com.kazforge`)	When to use it
`jsonapi-java-jackson3`	Native runtime for a configured `tools.jackson.databind.json.JsonMapper`
`jsonapi-java-query`	Optional parsing of `include`, `fields`, `sort`, and opaque parameters
`jsonapi-java-core`	Immutable documents and validation without a JSON backend
`jsonapi-java-api`	Neutral `JsonApi`, mapping, representation, and PATCH contracts; no runtime by itself
`jsonapi-java-annotations`	Mapping role annotations without a runtime dependency

jsonapi-java-jackson3 brings API, annotations, and core transitively. The public com.kazforge.jsonapi.mapping package ships in jsonapi-java-api. Packages containing internal are unsupported implementation details, and Java visibility alone is not a compatibility promise.

Compatibility¶

Requirement	Minimum supported
Java	21
Jackson 3 (`jsonapi-java-jackson3`)	`jackson-databind` 3.1.7

Compatible newer Jackson 3 versions can be selected by your dependency management; the adapter does not force a platform or override your application's Jackson version. The LTS baseline and policy are maintained in the Jackson 3 support section. The supported Jackson line is not a Spring Boot compatibility matrix.

Starting in 0.3.0, jsonapi-java supports Jackson 3 (tools.jackson.*) only; jsonapi-java-jackson2 and the separately published internal jsonapi-java-mapping artifact from 0.2.0 are discontinued. Historical 0.2.0 artifacts remain on Maven Central without ongoing support.

Dependency declarations¶

Use the same version for every jsonapi-java-* artifact; there is no BOM. Verify public versions in Maven Central.

Gradle Kotlin DSLMaven

repositories {
    mavenCentral()
}

val jsonapiVersion = "0.4.0"

dependencies {
    implementation("com.kazforge:jsonapi-java-jackson3:$jsonapiVersion")
    // Optional: query parsing
    // implementation("com.kazforge:jsonapi-java-query:$jsonapiVersion")
}

<properties>
    <jsonapi.version>0.4.0</jsonapi.version>
</properties>
<dependencies>
    <dependency>
        <groupId>com.kazforge</groupId>
        <artifactId>jsonapi-java-jackson3</artifactId>
        <version>${jsonapi.version}</version>
    </dependency>
    <!-- Optional: query parsing
    <dependency>
        <groupId>com.kazforge</groupId>
        <artifactId>jsonapi-java-query</artifactId>
        <version>${jsonapi.version}</version>
    </dependency>
    -->
</dependencies>

Add jsonapi-java-query separately if you need query parsing.

Before 1.0, a breaking change ships in a minor release, never a patch release. Review release notes when upgrading across minors. Raising a supported Java or Jackson minimum is a breaking change too.

Configure a runtime¶

With Java 21+ and the Jackson 3 dependency above, the snippets below can run inside your application code. Declare the DTO as its own Java type and reuse api for each operation.

Configure Jackson first, then pass the mapper to JsonApiJackson3. Keep the resulting immutable, thread-safe runtime for your application's lifetime. Factories do not mutate your mapper.

import com.kazforge.jsonapi.api.JsonApi;
import com.kazforge.jsonapi.jackson3.JsonApiJackson3;
import tools.jackson.databind.json.JsonMapper;

JsonMapper mapper = JsonMapper.builder()
    .build();

JsonApi api = JsonApiJackson3.jsonApi(mapper);

For non-default application-lifetime settings, use the configuration guide. It covers the builder's identifier conversion, linkage mappers, representation policy, decorators, and optional resource-write jsonapi.version. Selection and document envelopes belong to each operation.

Read and write an article¶

Start with a DTO for an article's identity and title:

import com.kazforge.jsonapi.annotation.JsonApiAttribute;
import com.kazforge.jsonapi.annotation.JsonApiId;
import com.kazforge.jsonapi.annotation.JsonApiResource;

@JsonApiResource(type = "articles")
public record Article(
    @JsonApiId String id,
    @JsonApiAttribute String title
) {}

@JsonApiResource supplies the resource type; the other annotations place properties in id and attributes. Jackson still owns visibility, property names, creators, mix-ins, and value conversion. Unannotated attributes do not join the mapping automatically.

Suppose an API returns this JSON:API document. Here, responseBody is a Java String containing the complete JSON below:

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "Working with JSON:API"
    }
  }
}

Read the article from the document's data member:

Article article = api.resources().readOne(responseBody, Article.class);

article.id() is "1"; article.title() is "Working with JSON:API".

To write a document, supply an article DTO. For example, give the article a revised title:

Article revised = new Article(article.id(), "A practical JSON:API guide");
String revisedJson = api.resources().writeOne(revised);

revisedJson contains this document, formatted here for readability:

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "A practical JSON:API guide"
    }
  }
}

These operations map and validate documents. Your application owns HTTP handling and saving changes.

API reference and next steps¶

Continue with resources to read an ID-less create request, add an author, and work with collections and metadata. The JsonApi API groups operations under resources(), relationships(), documents(), and patches(); use relationships and documents to choose a lower-level path.

The API Reference links rendered Javadoc for released artifacts, including JsonApi and JsonApiJackson3. These links target 0.4.0, not main. Exhaustive method/overload contracts belong in Javadoc, not in this guide.