Azure / Azure/azure-sdk-for-java

Upgrade Jackson 2 to Jackson 3 in sdk/cosmos

Open
#49,551 4 comments 0 reactions 4 assignees Claimed by @FabianMeiswinkel View on GitHub
azure-spring-cosmos Client Cosmos needs-team-attention Service Attention
Dominant language
Java
Stars
2.6k
Forks
2.2k
Avg merge
2d 8h
Merged PRs (30d)
178

Description

## Summary

Upgrade Jackson from major version 2 (`com.fasterxml.jackson`) to major version 3 (`tools.jackson`) across all modules under `sdk/cosmos`.

## Context

As part of aligning with Spring Boot 4, the `sdk/spring` modules were migrated from Jackson 2 to Jackson 3 (see #49538 and #49550). During that work, the Cosmos modules (`azure-spring-data-cosmos` and, transitively, `azure-cosmos`) were intentionally left out of scope because they cannot be migrated in isolation.

This issue tracks the follow-up work to bring `sdk/cosmos` to Jackson 3 so that `azure-spring-data-cosmos` and the Spring Cloud Azure Cosmos starter can fully move off Jackson 2.

## Why Cosmos could not be upgraded together with `sdk/spring`

`azure-cosmos` exposes Jackson 2 types as part of its **public API**, not just internally. Around 65 public (non-`implementation`) classes import `com.fasterxml.jackson`, for example:

- `CosmosItemSerializer` (public abstract extension point whose signatures use `ObjectNode` / `JsonNode`)
- `CosmosItemResponse`, `CosmosBulkItemResponse`, `CosmosBatchOperationResult`
- Most `com.azure.cosmos.models.*` properties classes (`CosmosContainerProperties`, `IndexingPolicy`, `SqlQuerySpec`, ...)

Because `JsonNode` is part of the public contract, switching to Jackson 3 is a **breaking API change** for `azure-cosmos`. That change cascades to every module that depends on it.

## Affected modules

Modules under `sdk/cosmos` that depend on `azure-cosmos` and/or use Jackson 2 directly (approximate Jackson 2 file counts):

| Module | Jackson 2 files |
| --- | --- |
| `azure-cosmos` | 221 |
| `azure-cosmos-tests` | 103 |
| `azure-cosmos-spark_3` (+ all spark variants) | 52+ |
| `azure-cosmos-kafka-connect` | 20 |
| `azure-cosmos-encryption` | 14 |
| `azure-cosmos-benchmark` | 9 |
| `azure-cosmos-test` | — |

Roughly 440+ source files reference Jackson 2 across the tree.

## Considerations

- `azure-cosmos` is a GA data-plane library; a 2 -> 3 migration that changes the public API is a breaking change and requires the appropriate API review / approval.
- Options to evaluate:
- Additive Jackson 3 support in `azure-cosmos` (keep the Jackson 2 public API, add Jackson 3) to avoid an immediate break for downstream consumers.
- A full migration across all `sdk/cosmos` modules in lockstep.
- The Jackson 2 annotations namespace (`com.fasterxml.jackson.annotation`) is unchanged in Jackson 3 and can be retained.

## Related

- #49538
- #49550

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.