Azure / Azure/azure-sdk-for-java
Upgrade Jackson 2 to Jackson 3 in sdk/cosmos
- 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
Assessment
This issue has not been assessed yet.