Migrate the Jackson dependency object to v3.2.1 - #745
Merged
Conversation
The brief captures the target state (`tools.jackson:jackson-bom:3.2.x`), the rules of engagement, and the phased plan for moving off Jackson 2.22.x across SpineEventEngine repositories. It is the reference the per-repository change sets are written against. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Jackson 3.x moved to the `tools.jackson` group ID and the matching `tools.jackson.*` packages (JSTEP-1), so `Jackson.group` changes wholesale. The sub-group derivation via `groupPrefix` survives untouched, because the rename preserves the `.core` / `.module` / `.dataformat` / `.datatype` / `.jr` suffixes. `Junior` no longer needs its hard-coded group. The one member that must break the pattern is `annotations`. Jackson 3.x deliberately keeps consuming the 2.x annotations artifact rather than publishing a 3.x one, so both its coordinates and its `com.fasterxml.jackson.annotation` package stay as they were. The BOM pins it via `jackson.version.annotations`, which is `2.22` in `jackson-bom:3.2.1` — the value already declared here, so the forced version does not move. `jackson-module-parameter-names`, `jackson-datatype-jdk8`, and `jackson-datatype-jsr310` were merged into `jackson-databind` in 3.0 and are no longer published. They are dropped from `modules` and marked `DeprecationLevel.ERROR` rather than deleted: a hard error tells a consumer what to use instead, whereas a warning would leave it compiling against a coordinate that cannot resolve. `DataType.protobuf` was dead on arrival — `com.fasterxml.jackson.datatype:jackson-datatype-protobuf` has never been published in any version. Protobuf support is a data *format*, and the real artifact is `jackson-dataformat-protobuf`. It was never noticed because `DataType` is not among the objects passed to `forceArtifacts()`, so nothing ever attempted to resolve it. Corrected as `DataFormat.protobuf`, with the old name deprecated. `buildSrc` keeps its own Jackson on the 2.x line: `MavenMetadata.kt` and `Assemble.kt` still compile against the `com.fasterxml.jackson.*` API, and porting them is separate work. The "keep in sync" note on `jacksonVersion` therefore no longer holds and is replaced by the reason the two versions now diverge. Note that `forceArtifacts()` keys on `group:name`, so the forcing block in `jvm-module`/`kmp-module` now pins `tools.jackson.*` and no longer constrains Jackson 2.x arriving transitively. Deliberate: 2.x and 3.x coexist on a classpath by design, and a 2.x conflict is to be addressed if and when it surfaces. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 47aba62ced
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…laims The brief declares itself authoritative for the per-repository migrations that follow, but `.agents/tasks/` is lifecycle-managed storage: `.agents/tasks/README.md` requires frontmatter, a checklist, and a log so agents can discover and resume the task, and `AGENTS.md` has the file deleted on merge to master. A durable reference document satisfies none of that and would not survive the merge, so it moves to `docs/`. Two of its module-availability claims were wrong, checked against the published `jackson-bom:3.2.1` POM. `jackson-module-jsonSchema` was dropped in 3.0 but restored in 3.1 — the POM says so in a comment — and the BOM manages both it and the `-jakarta` variant. Directing agents to stop and report a nonexistent blocker would have halted a migration for no reason, so §4 now names the coordinates, and the §11 entry that listed it among removals with no drop-in replacement is gone. The `jackson-datatype-hibernate` hedge is resolved the same way: all five variants are managed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
alexander-yevsyukov
changed the title
Jackson dependency object to Jackson 3.2.1Jackson dependency object to v3.2.1
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request updates the shared Jackson dependency definitions in buildSrc to target Jackson 3.2.1 under the new tools.jackson group, while documenting the org’s intended migration approach via a dedicated migration brief.
Changes:
- Migrates
io.spine.dependency.lib.Jacksonfromcom.fasterxml.jackson:jackson-bom:2.22.1totools.jackson:jackson-bom:3.2.1, including group-derivation updates and module list adjustments. - Introduces migration-time deprecations for modules merged into
jackson-databindand corrects protobuf support toDataFormat.protobuf. - Adds
docs/jackson-3-migration-brief.mdto capture the migration checklist, rules, and known pitfalls.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/jackson-3-migration-brief.md | Adds a Jackson 2.22.x → 3.2.x migration brief and checklist for repo migrations. |
| buildSrc/src/main/kotlin/io/spine/dependency/lib/Jackson.kt | Updates the central Jackson dependency object to Jackson 3.2.1 (tools.jackson.*) and adjusts module coordinates/deprecations accordingly. |
| buildSrc/build.gradle.kts | Updates buildSrc Jackson-version documentation to reflect that buildSrc remains on Jackson 2.x for now. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The `ReplaceWith` expressions are resolved in the scope of the deprecated declaration, but the quick-fix is applied in the scope of the call site. A call site that imported the nested object directly — `import …lib.Jackson.DataType`, then `DataType.jdk8` — has no `Jackson` in scope, so the quick-fix inserted an unresolved reference. All four now name the type and pass the import. `moduleParameterNames` was the one case that did resolve, because receiver substitution rewrites `Jackson.moduleParameterNames` into `Jackson.databind`. It is qualified anyway: a call site that imported the member itself and used the bare name has no receiver to substitute, and having all four read alike removes the need to work out which case each one is. Three section cross-references in the brief were off by one, pointing into `Phase 4 — mapper construction` and `Phase 5 — changed defaults` instead of the `changed defaults` and `exception handling` sections they describe. The two references in §12 and §14 were already right. The KDoc on `jacksonVersion` told the reader to keep the value on the latest 2.x release while pinning 2.18.3, which reads as a bug. `buildSrc` needs no specific 2.x, so the comment now says what is actually true rather than the version being bumped to satisfy it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
armiol
approved these changes
Aug 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Moves the shared
Jacksondependency object fromcom.fasterxml.jackson:jackson-bom:2.22.1totools.jackson:jackson-bom:3.2.1,and adds the migration brief the change is written against.
What changed
Jackson 3.x moved to the
tools.jacksongroup ID and the matchingtools.jackson.*packages (JSTEP-1), soJackson.groupchanges wholesale. Thesub-group derivation via
groupPrefixsurvives untouched, because the renamepreserves the
.core/.module/.dataformat/.datatype/.jrsuffixes.
Juniorno longer needs its hard-coded group.core,databind,moduleKotlintools.jackson.*, still BOM-managedannotationscom.fasterxml.jackson.core:jackson-annotations:2.22moduleParameterNames,DataType.jdk8,DataType.dateTimejackson-databind; deprecated, dropped frommodulesDataType.protobufDataFormat.protobufDataFormat.xml/yaml,DataType.guava/javaXMoney/moneta,Junior.objectstools.jackson.*annotationsis the one member that must break the pattern: Jackson 3.x keepsconsuming the 2.x annotations artifact rather than publishing a 3.x one, so both
its coordinates and its
com.fasterxml.jackson.annotationpackage stay as theywere. Verified against the published BOM:
jackson-bom:3.2.1setsjackson.version.annotationsto2.22, which is the value already declaredhere, so the forced version does not move.
The three merged-away modules are marked
DeprecationLevel.ERRORrather thandeleted, so a consumer gets a migration message instead of a bare
unresolved-reference error.
Two fixes that are not mechanical
DataType.protobufwas dead on arrival:com.fasterxml.jackson.datatype:jackson-datatype-protobufhas never beenpublished in any version. Protobuf support is a data format, and the real
artifact is
jackson-dataformat-protobuf. It went unnoticed becauseDataTypeis not among the objects passed to
forceArtifacts(), so nothing ever tried toresolve it. Same class of latent defect as #741.
buildSrckeeps its own Jackson on the 2.x line —MavenMetadata.ktandAssemble.ktstill compile against thecom.fasterxml.jackson.*API, andporting them is separate work. The "keep in sync" note on
jacksonVersionnolonger holds and is replaced by the reason the two versions now diverge.
For the reviewer
Two behavioural consequences, both deliberate:
forceArtifacts()keys ongroup:name, so the forcing block injvm-module/kmp-modulenow pinstools.jackson.*and no longer constrainsJackson 2.x arriving transitively. 2.x and 3.x coexist on a classpath by
design; a 2.x conflict will be addressed if and when it surfaces.
Jackson.*constants directly willresolve 3.x coordinates after floating this submodule. Confirmed out of band
that no consumer is in that position with unmigrated 2.x sources.
Nothing else in the repo hard-codes Jackson coordinates, and
configtracks nogenerated dependency or licence reports, so there is nothing to regenerate.
Deviations from the brief
The brief is wrong in two places, checked against the published
jackson-bom:3.2.1POM. Left as committed, but worth knowing before the nextrepo follows it:
jackson-module-jsonSchemahas no 3.x port. It was restored in3.1 — the POM says so in a comment — and both it and
-jakartaare managed at3.2.1.
jackson-datatype-hibernate. All ofhibernate4/5/5-jakarta/6/7are managed.
Verification
./gradlew -p buildSrc buildpasses.dokkaGenerateis not registered inbuildSrc, so there is no Dokka step here.spine-code-review,kotlin-engineer,review-docs, anddependency-audit. Their outstanding non-blocking suggestions are not yetapplied:
ReplaceWithon the threeDataTypemembers wants animportsargument, the deprecation message could be extracted to a
const val,@Suppressis missing"ConstPropertyName"(pre-existing), thejacksonVersionKDoc overstates "latest 2.x", and the brief needssentence-case headings plus footnote-style links.
🤖 Generated with Claude Code