Path to Jackson 3.0.0

[cowtowncoder]

Goal of this Discussion

This Discussion is "uber-discussion" covering the high-level scope of what the official Jackson 3.0.0 Release should include, along with bit of status of the progress. Most of content will be links to other pages, issues, discussions in other repos (with actual Issues, for example).

Note that while most issues were planned to be addressed by 3.0.0-rc1 (the first pre-release), we also want to follow "release early, release often" to get a tight feedback loop -- i.e. not get too ambitious on specific RC release.

Jackson 3.0.0: Requirements

To reach state where we are ready to publish the final 3.0.0, we have to tackle following things.
(note: this document is work-in-progress and will continue living -- it is not a static requirements document).

RCs

Lower level details about specific release candidates are on sub-discussions:

• 3.0.0-rc1 -- released on March 7, 2025
• 3.0.0-rc2 -- released on March 28, 2025
• 3.0.0-rc3 -- released on April 13, 2025
• 3.0.0-rc4 -- released on May 10, 2025
• 3.0.0-rc5 -- released on May 22, 2025
• 3.0.0-rc6 -- released on July 18, 2025
• 3.0.0-rc7 -- released on August 8, 2025
• [3.0.0-rc8] -- released on August 13, 2025 (due to problem with rc7)
• [3.0.0-rc9]- released on September 5, 2025
• [3.0.0-rc10]- released on September 19, 2025
• any more RCs needed?

JSTEPs

See JSTEP Overview for an overview what JSTEPs are. They can be thought as an effort bigger than what a single Issue can cover, and are natural way to group such efforts.

For 3.0.0 we want to tackle most of them, specifically:

JSTEP	Description	Status
JSTEP-1	Maven artifact, Java package name change (Jackson 2.x -> 3.x)	complete
JSTEP-2	Jackson 3.0 Default Settings	ALMOST complete (as of 3.0.0-rc6)
JSTEP-3	JsonNode improvements	complete (in 3.0.0-rc2)
JSTEP-4	Unchecked JacksonException	complete
JSTEP-5	Unified/improved Data/Time handling	started
JSTEP-6	Jackson 3.0 Renaming of Entities	complete
JSTEP-8	Jackson 3.0 Renaming of Format-specific Features	complete
JSTEP-9	Jackson 3.0 Removal of Deprecated 2.x Modules	complete
JSTEP-10	Unifying testing structure/tools	complete
JSTEP-11	Use native JPMS module-info.java	complete
JSTEP-14	Generate, publish SBOMs for Jackson components	mostly complete

Note that we can create new JTEPs and reconsider ones not completed.
Some JSTEPs are also for 2.x, not 3.0 (and others for later 3.x versions beyond initial one).

Of these, ones with specific urgency are:

• JSTEP-5 Unified/improved Data/Time handling -- much more involved, need to
  • Scope wrt "classic" java.util.Date / Java 8 Date/Time / Joda
  • -- Decide on changes to default settings (done)
  • Decide on changes to behavior in general
  • Possibly new configurability options
    • partly done with new DateTimeFeature
  • ... and implementing above
• JSTEP-14
  • Done except need to finalize classifier to use: initial proposal is "sbom-cyclonedx" (but plug-in default simple "cyclonedx")

Things to decide (polls!)

Here are things to decide on proposed changes: please vote if you have opinion on whether change suggested is desired.

You may also add comments explaining your reasoning, as well as upvote comments by others.

General

• Minimum Java Version for 3.0.0 (17 vs 21) (databind#4820)
  • DECIDED: JDK 17 is the 3.0 baseline
  • IMPLEMENTED
• Deprecate+remove Hibernate modules from 3.0.0
  • DECIDED: no 3.0 version of Hibernate modules will be created
  • IMPLEMENTED (by not creating 3.0 modules)

Changes to Feature defaults

• Poll Default for JsonWriteFeature.ESCAPE_FORWARD_SLASHES -- issue core#1200
  • DECIDED: Default will NOT be changed (that is, earlier change reverted)
• Poll Default for DeserializationFeature. FAIL_ON_NULL_FOR_PRIMITIVES -- issue databind#4858
  • DECIDED: Default WILL be changed
  • IMPLEMENTED
• Poll Default for 'DeserializationFeature.FAIL_ON_TRAILING_TOKENS' -- issue: databind#3406
  • DECIDED: Default WILL be changed
  • IMPLEMENTED
• Poll Default for 'MapperFeature.DEFAULT_VIEW_INCLUSION' -- issue: databind#1484
  • DECIDED: Default WILL be changed
  • IMPLEMENTED
• Poll Default for 'SerializationFeature.WRITE_DATES_AS_TIMESTAMPS' -- issue: databind#4845
  • DECIDED: Default WILL be changed
  • IMPLEMENTED
• Poll Default for 'SerializationFeature.WRITE_DURATIONS_AS_TIMESTAMPS' -- issue: databind#4846
  • DECIDED: Default WILL be changed
  • IMPLEMENTED

Issues to work on in jackson-databind

Aside from decisions (or in some cases, related to), there are specific issues to work on.

"Most Wanted" Jackson issues

Of all open issues, a small subset has been labeled as "most-wanted" based on upvotes.
These may be considered for inclusion in 2.x as well, but some might require bigger changes.
Because of this, it would make sense to see if any could be added in 3.0.0-SNAPSHOT:

• https://github.com/FasterXML/jackson-databind/issues?q=is%3Aissue+is%3Aopen+label%3Amost-wanted+

Issues labeled with '3.0'

Some issues have been labeled specifically as targeted to 3.0.0-SNAPSHOT release:

https://github.com/FasterXML/jackson-databind/issues?q=is%3Aissue+is%3Aopen+label%3A3.0

Issues labeled with '3.x'

Other issues have been labeled with 3.x to indicate "not possible/practical for 2.x, maybe one of 3.x releases", but not necessarily 3.0.0:

https://github.com/FasterXML/jackson-databind/issues?q=is%3Aissue+is%3Aopen+label%3A3.x

Issues/Discussion for Other Modules

Beside jackson-databind repo, there are issues in other FasterXML Jackson repositories, labeled for ideally being included in 3.0.0-SNAPSHOT:

None yet

Kotlin

• Discussion of changes to default behavior in Jackson 3.0

[cowtowncoder]

/cc @k163377 @pjfanning @yawkat @yihtserns -- the new central planning page for Jackson 3.0.0. Trying to collect links to everything pertinent, keep updated. Especially interested in 3 Polls under "Things to Decide".

[JooHyukKim]

I should go tell community in Korea to vote. There is huge Java community here.

[k163377]

Is it possible to enable FAIL_ON_NULL_FOR_PRIMITIVES by default in 3.0?
At least as a kotlin-module user, I find the current default counter-intuitive, and I have seen several of the submitted issues as a maintainer.

[JooHyukKim]

+1. Sounds counter-intuitive.
Hopefully the feature doesn't take precedence over FAIL_ON_UNKNOWN_PROPERTIES or sorts 🤔

[cowtowncoder]

If not yet done, could someone file issue like #4845 / #4846 for this setting? Then I (or anyone else actially) can create discussion here (like #77 / #78). And this allows for discussing pros and cons.
I think original leniency is due to some users with scripting language background liking interoperability (in some sense; I can see pros and cons here!). But I know many others are in favor of making change as suggested.

Or if an issue already created, we can just create discussion, add links.

I think it's a good idea to try to get more people involved giving their opinion by voting.

[JooHyukKim]

Will do

[JooHyukKim]

@k163377 @cowtowncoder
Created a poll #79

[cowtowncoder]

Thanks! Created databind issue, linked to from this discussion so we are good.

[JooHyukKim]

How about another one? Proposal for this one : Unifying testing structure/tools pre-Jackson 3 that I previously proposed in Jackson main repo.

Benefits....

1. We get more visibility over behavior changes, e.g. failing test now passes.
2. Upgrade all tests JUnit 5

[cowtowncoder]

Sounds good, +1: could you create a new JSTEP for this? (JSTEP-10 I think).
Mostly useful as common-term to group various PRs/issues with.

[JooHyukKim]

Yeah will do.

[JooHyukKim]

Just so we all now. We now have https://github.com/FasterXML/jackson-future-ideas/wiki/JSTEP-10.

Planning and other detailed discussions may be done in FasterXML/jackson#249

[JooHyukKim]

[ Another suggestion for writing 2 -> 3 migration guide ]

I would like to suggest that we have 2 -> 3 migration guide here in this repo.
As to detail(how), I'm thinking we add to source code so we can write PR's add comments, track history etc...

[cowtowncoder]

That would be useful, although probably easiest to write if and when someone does actual upgrade of a codebase.

Need not be source code, could be Markdown file (like README.md etc), just stored as file and not Wiki page.

[yawkat]

If there's official rewrite instructions, I think we should have a https://docs.openrewrite.org/ recipe too

[cowtowncoder]

That'd be good too for sure. It might even help writing instructions.

[cowtowncoder]

I suspect writing of guide is easier to do after 3.0.0-rc1 which I hope to get out by end of February 2025 (that is, in 4 weeks from now). At that point API should be somewhat stable with (almost?) all renaming, refactoring, signature changes complete.

[ppkarwasz]

An OpenRewrite recipe in place there should be no limits to the renamings in JSTEP 6.

[k163377]

@cowtowncoder
Will 2.19 be released before 3.0.0-rc1?
We can reflect the future image of features that are in the process of being deprecated in 3.0 first, but it would be better to keep the difference between 3.0 and the 2.x branch small.

Also, would it be desirable to do the same for the 2.18.3 release?

[JooHyukKim]

We can reflect the future image of features that are in the process of being deprecated in 3.0

Could u elaborate further i didnt quite catch what u meant by this @k163377

[k163377]

Sorry, I've reorganized.

There are some changes in kotlin-module that I would like to make for 2.20 (mainly to clean up deprecated code).
I would prefer that 2.19 be released first, to minimize the diff between this change and 3.0.

[JooHyukKim]

Makes sense. I think when Tatu gets back from vacay, we can discuss this? @cowtowncoder

[cowtowncoder]

Quick note: due to timing, I think 3.0.0-rc1 needs to go first, to try to make it happen close to end of February 2025. I don't want 2.19.0 work to derail that (plus there's need for 2.19.0-rc1).
But we can definitely merge forward-looking changes in 2.19 branch.

But I am also fairly certain that 2.19.0 (release) will go out way before 3.0.0 (release). Just that rc1's go in different order.

I also think 2.18.3 will be released before 2.19.0, and probably before 2.19.0-rc1. Just because there are so many accumulated changes.

As to changes for 2.18.3: this is a patch release and really shouldn't change API, including no new deprecations. So there's less co-ordination wrt 3.0.0, I think.

[cowtowncoder]

Notes:

1. 2.18.3 was just released
2. End of February 2025 is gone, hope for 3.0.0-rc1 now early/mid-March -- only one bigger issue (JsonNode scalar accessor rewrite) to complete

[mayleaf]

Hi everyone, I noticed that jackson-annotations hasn’t been migrated to the tools.jackson group like the other Jackson artifacts.
I’m curious—was there a specific reason for keeping it in the original group?

[JooHyukKim]

I recall there was a note / github-issue somewhere explaining why. Don't have time to re-search for it tho.

[cowtowncoder]

Yes. The idea is/was that there would be actual 2.x/3.x cross-compatibility just for annotation types.
So that those value classes that only depend on jackson-annotations can work fine with either Jackson 2.x or 3.x, without duplicated annotations as was necessary between Jackson 1.x and 2.x.
To that end, keeping Maven coordinate as well as Java packages the same is essential.

I tried explaining rationale here:

https://github.com/FasterXML/jackson-future-ideas/wiki/JSTEP-1#handling-of-jackson-annotations

I hope it makes sense.

[JooHyukKim]

@mayleaf Could you tell us places you looked for the reason why? Your answer might be the place we want to link explanation to JSTEP-1 part above

[cowtowncoder]

3.0.0 GA released, discussion over. :)