feat!: migrate json serialization to jackson 3 by Adrastopoulos · Pull Request #392 · openfga/java-sdk

Adrastopoulos · 2026-09-19T01:17:21Z

Description

Moves the SDK to Jackson 3 after the serialization bridge. Request, response, error and streaming JSON handling stay behind the SDK-owned API.

What problem is being solved?

The bridge still uses Jackson 2. The next major needs to switch the implementation without putting Jackson types back into the public API.

How is it being solved?

Jackson3JsonSerializer uses the existing mapper configuration on Jackson 3. The deprecated mapper and TypeReference APIs are removed; callers use JsonSerializer and SdkTypeToken instead.

This is for the next major. The Jackson 2 bridge must ship before this lands. Release versions are unchanged.

What changes are made to solve it?

Use Jackson 3 for default serialization and preserve byte-for-byte wire output.
Remove the deprecated mapper and type-reference APIs, including the streaming compatibility fields.
Keep core and databind as runtime dependencies and annotations as an API dependency.
Remove the unused nullable dependency and use built-in Java time support.
Update tests, examples, and migration notes.
Document the serializer error contract and test malformed byte/text input, concrete byte responses, and getter failures.

Release notes

BEGIN_COMMIT_OVERRIDE
feat!: migrate json serialization to jackson 3

BREAKING CHANGE: migrate to Jackson 3 and remove the Jackson 2
`ObjectMapper` and `TypeReference` APIs deprecated in the bridge release.
Applications that use the default serializer without these APIs need no
source changes.

For custom serialization, use `JsonSerializer` with
`ApiClient(HttpClient.Builder, JsonSerializer)` or `setJsonSerializer(...)`.
Use `JsonSerializer.createDefault()` to restore the SDK serializer.
This removes the `ObjectMapper` constructor, accessors, and protected
`createDefaultObjectMapper()` method.

Replace `TypeReference` with `SdkTypeToken`, including in `BaseStreamingApi`
subclasses. Use `jsonSerializer` and `streamResultType` instead of
`objectMapper` and `streamResultTypeRef`. Serialization failures still use
`SdkSerializationException`.

Jackson core and databind are runtime dependencies. Applications that
use them directly must declare their own dependencies. Jackson 3 uses
`tools.jackson.core` coordinates. Jackson annotations remain available
through the SDK under `com.fasterxml.jackson.annotation`. This also
removes the unused `jackson-databind-nullable` dependency.
END_COMMIT_OVERRIDE

References

Test plan

./gradlew build: 566 unit tests passed. Jackson3JsonSerializer has 26/26 lines and 7/7 methods covered.
./gradlew test-integration: 60 passed, one existing skip. Used the local Colima socket.
Clean Java SDK regeneration matched all generated files after formatting.
Live OpenFGA smoke run covered store/model creation, write, read, check, list, streaming, deletion, and server error decoding. Jackson 2 databind was absent.
A consumer compiled without Jackson core or databind on its compile classpath. The generated POM keeps both at runtime scope.
The three changed example projects compiled against the local SDK. This included Java and Kotlin. The basic example used a Java 17 target to match its Kotlin target.
Vale found no new errors or warnings on changed prose. Existing findings remain elsewhere in the files.

Review Checklist

Allow edits by maintainers is enabled.
Migration notes cover the changed API.
The correct base branch is used.
Tests cover serialization compatibility and wire parity.
Generated-file changes have matching source-template changes.

Summary by CodeRabbit

Changed
- Upgraded the SDK’s default JSON serialization to Jackson 3 while preserving Jackson-compatible serialization behavior.
- Applications can now provide custom JSON serialization through the SDK’s serializer interface.
- Streaming response type configuration uses SdkTypeToken instead of Jackson TypeReference.
- Examples and integration guidance now demonstrate Jackson 3 configuration.
Migration
- Existing applications using removed Jackson 2 mapper APIs or TypeReference integrations must migrate to the serializer and type-token APIs described in the updated documentation.

coderabbitai · 2026-09-19T01:17:35Z

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 67e5257a-6a5e-485d-8296-b3982fa0112b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 78f19e89-41e3-45a4-a2db-4b94dded1cd0

📥 Commits

Reviewing files that changed from the base of the PR and between 209bd3d and 0a58c2e.

📒 Files selected for processing (34)

CHANGELOG.md
build.gradle
docs/ApiExecutor.md
examples/api-executor/build.gradle
examples/api-executor/src/main/java/dev/openfga/sdk/example/ApiExecutorExample.java
examples/api-executor/src/main/java/dev/openfga/sdk/example/StreamingApiExecutorExample.java
examples/basic-examples/build.gradle
examples/basic-examples/src/main/java/dev/openfga/sdk/example/Example1.java
examples/basic-examples/src/main/kotlin/dev/openfga/sdk/example/KotlinExample1.kt
examples/streamed-list-objects/build.gradle
examples/streamed-list-objects/src/main/java/dev/openfga/sdk/example/StreamedListObjectsExample.java
src/main/java/dev/openfga/sdk/api/BaseStreamingApi.java
src/main/java/dev/openfga/sdk/api/client/ApiClient.java
src/main/java/dev/openfga/sdk/api/client/Jackson2JsonSerializer.java
src/main/java/dev/openfga/sdk/api/client/Jackson3JsonSerializer.java
src/main/java/dev/openfga/sdk/api/client/JsonSerializer.java
src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
src/main/java/dev/openfga/sdk/api/client/StreamingApiExecutor.java
src/test-integration/java/dev/openfga/sdk/api/OpenFgaApiIntegrationTest.java
src/test-integration/java/dev/openfga/sdk/api/client/ApiExecutorIntegrationTest.java
src/test-integration/java/dev/openfga/sdk/api/client/OpenFgaClientIntegrationTest.java
src/test-integration/java/dev/openfga/sdk/errors/FgaErrorIntegrationTest.java
src/test-integration/java/dev/openfga/sdk/example/Example1.java
src/test/java/dev/openfga/sdk/LegacyStreamingApiTest.java
src/test/java/dev/openfga/sdk/TestJsonSerializer.java
src/test/java/dev/openfga/sdk/api/OpenFgaApiTest.java
src/test/java/dev/openfga/sdk/api/StreamingApiTest.java
src/test/java/dev/openfga/sdk/api/auth/OAuth2ClientTest.java
src/test/java/dev/openfga/sdk/api/client/ApiClientTest.java
src/test/java/dev/openfga/sdk/api/client/Jackson3JsonSerializerTest.java
src/test/java/dev/openfga/sdk/api/client/OpenFgaClientHeadersTest.java
src/test/java/dev/openfga/sdk/api/client/OpenFgaClientTest.java
src/test/java/dev/openfga/sdk/api/client/StreamedListObjectsTest.java
src/test/java/dev/openfga/sdk/api/client/StreamingApiExecutorTest.java

💤 Files with no reviewable changes (5)

src/main/java/dev/openfga/sdk/api/client/StreamingApiExecutor.java
src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
src/main/java/dev/openfga/sdk/api/client/Jackson2JsonSerializer.java
src/test/java/dev/openfga/sdk/LegacyStreamingApiTest.java
src/main/java/dev/openfga/sdk/api/BaseStreamingApi.java

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

The SDK migrates JSON serialization from Jackson 2 to Jackson 3. It removes deprecated ObjectMapper and TypeReference APIs, adds Jackson3JsonSerializer, updates dependencies, and migrates documentation, examples, integration tests, and unit tests.

Changes

Jackson 3 migration

Layer / File(s)	Summary
Serializer implementation and API removal `src/main/java/dev/openfga/sdk/api/...`	`JsonSerializer.createDefault()` now uses `Jackson3JsonSerializer`. Deprecated Jackson 2 serializer, `ObjectMapper` APIs, and `TypeReference` streaming APIs were removed.
Dependency and migration contract updates `build.gradle`, `CHANGELOG.md`, `docs/ApiExecutor.md`	Build dependencies use Jackson 3 coordinates. Documentation describes `SdkTypeToken`, `JsonSerializer`, and application dependency changes.
Example application migration `examples/...`	Examples use Jackson 3 `JsonMapper` instances and `SdkTypeToken` for generic streaming responses.
Integration test migration `src/test-integration/...`	Integration tests use Jackson 3 imports, mapper construction, and exception types.
Unit test serializer and client updates `src/test/...`	Unit tests use `JsonSerializer` implementations and validate serialization compatibility, generic deserialization, customization, and error handling.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Refactor

Sequence Diagram(s)

sequenceDiagram
  participant Application
  participant OpenFgaClient
  participant ApiClient
  participant JsonSerializer
  Application->>OpenFgaClient: request streamingApiExecutor(SdkTypeToken)
  OpenFgaClient->>ApiClient: execute request
  ApiClient->>JsonSerializer: deserialize response
  JsonSerializer-->>OpenFgaClient: typed StreamResult
  OpenFgaClient-->>Application: streaming response

Suggested reviewers: soulpancake

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 60 functions across 23 files. (6 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely identifies the main change: migrating JSON serialization to Jackson 3. The breaking-change marker is appropriate because deprecated Jackson 2 and TypeReference APIs are…

Full details: Docstring Coverage

Explanation

Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 60 functions across 23 files. (6 skipped: 6 unsupported.)

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

Commit to this branch
Create a new PR

🧪 Generate unit tests (beta)

Create a new PR

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

codecov-commenter · 2026-09-19T01:20:43Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 39.33%. Comparing base (468f6fc) to head (26038c7).

❌ Your project status has failed because the head coverage (39.33%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff            @@
##               main     #392   +/-   ##
=========================================
  Coverage     39.32%   39.33%           
+ Complexity     1335     1330    -5     
=========================================
  Files           202      202           
  Lines          7791     7757   -34     
  Branches        912      912           
=========================================
- Hits           3064     3051   -13     
+ Misses         4579     4549   -30     
- Partials        148      157    +9

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Copilot review overview

🟡 Changes recommended

Remaining README examples reference removed Jackson 2 APIs and no longer compile with the new dependency scopes.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

Replace removed Jackson TypeReference overload in example README · New

What changed in this PR

Migrates the SDK’s internal JSON serialization from Jackson 2 to Jackson 3 while keeping public serialization library-neutral.

Changes:

Adds the Jackson 3 serializer and preserves wire compatibility.
Removes deprecated Jackson 2 mapper and TypeReference APIs.
Updates dependencies, tests, examples, and migration documentation.

File	Description
`src/test/java/dev/openfga/sdk/TestJsonSerializer.java`	Adds a Jackson 3 test serializer.
`src/test/java/dev/openfga/sdk/LegacyStreamingApiTest.java`	Removes legacy Jackson 2 streaming tests.
`src/test/java/dev/openfga/sdk/api/StreamingApiTest.java`	Tests streaming through SDK serialization APIs.
`src/test/java/dev/openfga/sdk/api/OpenFgaApiTest.java`	Uses the test serializer.
`src/test/java/dev/openfga/sdk/api/client/StreamingApiExecutorTest.java`	Removes `TypeReference` compatibility coverage.
`src/test/java/dev/openfga/sdk/api/client/StreamedListObjectsTest.java`	Uses the default serializer.
`src/test/java/dev/openfga/sdk/api/client/OpenFgaClientTest.java`	Replaces mapper-based client construction.
`src/test/java/dev/openfga/sdk/api/client/OpenFgaClientHeadersTest.java`	Uses the test serializer.
`src/test/java/dev/openfga/sdk/api/client/Jackson3JsonSerializerTest.java`	Covers Jackson 3 compatibility and failures.
`src/test/java/dev/openfga/sdk/api/client/Jackson2JsonSerializerTest.java`	Removes Jackson 2 serializer tests.
`src/test/java/dev/openfga/sdk/api/client/ApiClientTest.java`	Tests custom serializer configuration.
`src/test/java/dev/openfga/sdk/api/auth/OAuth2ClientTest.java`	Uses the default serializer.
`src/test-integration/java/dev/openfga/sdk/example/Example1.java`	Migrates integration parsing to Jackson 3.
`src/test-integration/java/dev/openfga/sdk/errors/FgaErrorIntegrationTest.java`	Migrates error tests to Jackson 3.
`src/test-integration/java/dev/openfga/sdk/api/OpenFgaApiIntegrationTest.java`	Migrates mapper and exception APIs.
`src/test-integration/java/dev/openfga/sdk/api/client/OpenFgaClientIntegrationTest.java`	Migrates client integration parsing.
`src/test-integration/java/dev/openfga/sdk/api/client/ApiExecutorIntegrationTest.java`	Migrates executor integration parsing.
`src/main/java/dev/openfga/sdk/api/client/StreamingApiExecutor.java`	Removes the Jackson `TypeReference` constructor.
`src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java`	Removes the `TypeReference` overload.
`src/main/java/dev/openfga/sdk/api/client/JsonSerializer.java`	Selects Jackson 3 and documents its contract.
`src/main/java/dev/openfga/sdk/api/client/Jackson3JsonSerializer.java`	Implements default Jackson 3 serialization.
`src/main/java/dev/openfga/sdk/api/client/Jackson2JsonSerializer.java`	Removes the Jackson 2 implementation.
`src/main/java/dev/openfga/sdk/api/client/ApiClient.java`	Removes deprecated mapper APIs.
`src/main/java/dev/openfga/sdk/api/BaseStreamingApi.java`	Removes Jackson compatibility fields and constructors.
`examples/streamed-list-objects/src/main/java/dev/openfga/sdk/example/StreamedListObjectsExample.java`	Migrates example parsing to Jackson 3.
`examples/streamed-list-objects/build.gradle`	Updates example dependencies.
`examples/basic-examples/src/main/kotlin/dev/openfga/sdk/example/KotlinExample1.kt`	Migrates Kotlin parsing to Jackson 3.
`examples/basic-examples/src/main/java/dev/openfga/sdk/example/Example1.java`	Migrates Java parsing to Jackson 3.
`examples/basic-examples/build.gradle`	Updates basic example dependencies.
`examples/api-executor/src/main/java/dev/openfga/sdk/example/StreamingApiExecutorExample.java`	Replaces `TypeReference` with `SdkTypeToken`.
`examples/api-executor/src/main/java/dev/openfga/sdk/example/ApiExecutorExample.java`	Applies formatting cleanup.
`examples/api-executor/build.gradle`	Updates executor example dependencies.
`docs/ApiExecutor.md`	Documents `SdkTypeToken` streaming.
`CHANGELOG.md`	Adds migration guidance.
`build.gradle`	Moves production dependencies to Jackson 3.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Adrastopoulos · 2026-09-19T21:28:20Z

@SoulPancake any insight into the failing snyk security test? Otherwise this is ready!

SoulPancake · 2026-09-24T05:32:45Z

@Adrastopoulos Having a look right now!

SoulPancake

Two things, then good to go.

Bump Jackson to 3.2.3 (and the test baselines to 2.22.3). It fixes CVE-2026-91776/91777 and CVE-2026-89425, which is what Snyk is failing on.

The README init snippets still import com.fasterxml.jackson.databind.ObjectMapper, which won't be on consumers' classpath after this. That's README_initializing.mustache, so it goes in #731.

Rest LGTM

Adrastopoulos · 2026-09-24T19:41:28Z

@SoulPancake Thanks, addressed.

feat!: migrate json serialization to jackson 3

0a58c2e

Adrastopoulos requested a review from a team as a code owner September 19, 2026 01:17

Adrastopoulos mentioned this pull request Sep 19, 2026

feat(java-sdk)!: generate jackson 3 clients openfga/sdk-generator#731

Open

4 tasks

Adrastopoulos added 2 commits September 18, 2026 23:35

test: cover serializer failure boundaries

40ee15a

fix(examples): retain patched language dependencies

c645900

SoulPancake requested a balanced review from Copilot September 19, 2026 11:11

Copilot started reviewing on behalf of SoulPancake September 19, 2026 11:11 View session

Copilot AI reviewed Sep 19, 2026

View reviewed changes

Comment thread docs/ApiExecutor.md

docs(examples): use sdk type token for streaming

19ef795

Adrastopoulos requested review from a team as code owners September 19, 2026 21:29

SoulPancake reviewed Sep 21, 2026

View reviewed changes

Comment thread CHANGELOG.md

Adrastopoulos and others added 2 commits September 21, 2026 15:26

docs: defer changelog to release-please

1bbea36

Merge branch 'main' into gabriel/jackson3

faee821

Adrastopoulos requested a review from SoulPancake September 24, 2026 05:16

SoulPancake reviewed Sep 24, 2026

View reviewed changes

Adrastopoulos added 2 commits September 24, 2026 12:41

fix(deps): bump jackson to 3.2.3 and 2.22.3

b2f4c28

docs: drop unused jackson imports from readme

26038c7

Adrastopoulos requested a review from SoulPancake September 24, 2026 19:52

SoulPancake approved these changes Sep 25, 2026

View reviewed changes

SoulPancake added this pull request to the merge queue Sep 25, 2026

Merged via the queue into openfga:main with commit b56e332 Sep 25, 2026
13 of 14 checks passed

Adrastopoulos deleted the gabriel/jackson3 branch September 25, 2026 05:59

Navigation Menu

feat!: migrate json serialization to jackson 3 - #392

feat!: migrate json serialization to jackson 3#392
SoulPancake merged 8 commits into
openfga:mainfrom
Adrastopoulos:gabriel/jackson3

Adrastopoulos commented Sep 19, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 19, 2026 •

edited

Loading

Review skipped

❌ Failed checks (1 warning)

Uh oh!

codecov-commenter commented Sep 19, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Adrastopoulos commented Sep 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

SoulPancake commented Sep 24, 2026

Uh oh!

SoulPancake left a comment

Uh oh!

Adrastopoulos commented Sep 24, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Adrastopoulos commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What problem is being solved?

How is it being solved?

What changes are made to solve it?

Release notes

References

Test plan

Review Checklist

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

codecov-commenter commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Adrastopoulos commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

SoulPancake commented Sep 24, 2026

Uh oh!

SoulPancake left a comment

Choose a reason for hiding this comment

Uh oh!

Adrastopoulos commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Adrastopoulos commented Sep 19, 2026 •

edited

Loading

coderabbitai Bot commented Sep 19, 2026 •

edited

Loading

codecov-commenter commented Sep 19, 2026 •

edited

Loading

Adrastopoulos commented Sep 19, 2026 •

edited

Loading

Adrastopoulos commented Sep 24, 2026 •

edited

Loading