Change of versioning scheme to `2.20` (no patch) vs `2.19.0` and earlier (jackson-databind version still 2.20.0 (28-Aug-2025))

[ca-stefan-cordes]

In the past the jackson-annotations version was released inline with all other jackson components. Now "other" are named "2.20.0" and this one "2.20" (without .0).

Has that be done by intention to de-couple jackson annotations from the rest ?

(currently I have one version for all jacksons and so build fails with Could not find artifact com.fasterxml.jackson.core:jackson-annotations:jar:2.20.0 in centralMirror)

The "Release notes" does not mention something in that direction (to be precise it is completely empty ;-) )

EDIT: see actual 2.20 Release Notes

EDIT: see discussion#90 for more on decision to go with "2.20 plan". And JSTEP-1 for the wider discussion on Jackson 3.x versioning.

[pjfanning]

Relates to #294. It is unfortunate - some people will see build issues but this change is going to be kept. We should update the release notes if this change is not highlighted.

[pjfanning]

The release notes are at https://github.com/FasterXML/jackson/wiki/Jackson-Release-2.20

And they mention the #294 change.

[cowtowncoder]

Yes: this is to sort of de-couple jackson-annotations from patch versions of other components. But also related to Jackson 3.0.0 relying on 2.x annotations.

I tried to explain rationale on JSTEP-1 (https://github.com/FasterXML/jackson-future-ideas/wiki/JSTEP-1).

This change (dropping patch) was originally meant just for Jackson 3.x (due to friction for some 2.x users). But due to re-thinking 2.x/3.x split for annotations, Jackson 3.0 will continue using 2.x jackson-annotations (to prevent problems we saw with 1.x->2.x migration with 2 annotations packages).

I realize this change may seem sudden and apologize for short time, reduced discussion.

But like @pjfanning said, this is permanent change from 2.20 onwards.

EDIT: To expand just slightly on "both 2.x and 3.x will depend on jackson-annotations 2.x hence drop the patch" will mean that:

• Both 2.20.x and 3.0.y jackson-databind will depend on jackson-annotations 2.20
• But there is no synchronization between x and y -- 2.20.1 and 3.0.1 releases go out independently
• There is no way -- aside from publishing separate 2.x and 3.x jackson-annotations -- to keep 3-level versions in-sync

this also ties into the older observation that annotations package really should never change in patch versions, prompting this change.

[pjfanning]

I mentioned this elsewhere but it's useful to mention it here. One way to simplify dependencies for Jackson is use: https://github.com/FasterXML/jackson-bom

[Philippus]

Maybe good to update the wiki: https://github.com/FasterXML/jackson/wiki/Jackson-Releases#internal-api-versioning

[marcrohlfs]

I'm not glad with this versioning difference. This isn't a problem when jackson-annotations is only used as a build dependency via the jackson-bom. But in some places, we need jackson-annotations as plugin dependency, too. And I cannot do a BOM import for plugin dependencies, hence I'd need to configure two Jackson versions (where I used one common property until now). Or am I just not up-to-date with latest Maven features?

[ca-stefan-cordes]

I mentioned this elsewhere but it's useful to mention it here. One way to simplify dependencies for Jackson is use: https://github.com/FasterXML/jackson-bom

Using <scope>import</scope> with the jackson-bom helps getting consistent jackson versions but as <dependencyManagement> with maven (3.x) is a little bit wired you may see unexpected results in the transitive (non-jackson) dependencies (especially when you have more than one project in the <dependencyManagement> section with <scope>import</scope>).

As <jackson.version.annotations> currently is the only one "out of sync" with ${jackson.version} in the jackson-bom, we stick to our "plain-dependencies" without dependencyManagement and maintaining two version properties in our pom.xml.

Thanks for linking the relevant resources.

[gaeljw]

Cross posting a comment that I made in https://github.com/FasterXML/jackson-annotations/issues/294#issuecomment-3241290253 as I believe here might be a better place for discussion.

I can understand the reasons behind the change. I would highlight the changes more strongly in the various READMEs though.

[pjfanning]

@cowtowncoder I reopened this - not that it will be 'fixed'. It is in the hope that people will stop creating new issues. If this is open, it might be more visible. We can close again when everyone sits down and reads the docs in their build tools instead of expecting the version change to be undone.

[cowtowncoder]

Quick note: I have merged updates to https://github.com/FasterXML/jackson-annotations/ (README.md) and https://github.com/FasterXML/jackson -- and will see if I can find other places to update. But would appreciate help finding things to update as well.

[sschuberth]

It is in the hope that people will stop creating new issues.

Maybe also even "pin" this issue then?

[erik-meuwese-topicus]

@sschuberth people should continue to create issues on this. This costs unnecessary money to fix automated pull requests form tools like dependabot/renovate. It's possible to make 2 tags for the 2.20.0 and the 3.x.x version on the release branch or make a branch for the 3.x.x version.

[sschuberth]

This costs unnecessary money to fix automated pull requests form tools like dependabot/renovate.

@erik-meuwese-topicus, IMO that's the wrong way to deal with the issue anyway. Just switch to the Jackson BOM as proposed above (see this for how to do it with Gradle), and you'll not have any problems with Dependabot / Renovate anymore.

[cowtowncoder]

@erik-meuwese-topicus Problem is not so much the initial 2.20.0 / 3.0.0 combo, but patch versions thereof: 2.20.1 and 3.0.1 (just as an example) won't be released in-sync. Complexity of release process does not warrant blind reliance on 3-digit scheme for version..

And as per @sschuberth use of jackson-bom is very strongly recommended.

[adi-gnm]

I mentioned this elsewhere but it's useful to mention it here. One way to simplify dependencies for Jackson is use: https://github.com/FasterXML/jackson-bom

Thanks @pjfanning . A BOM is a good way forward. Do you have plans to add jackson-module-kotlin versions to the BOM?

[pjfanning]

I mentioned this elsewhere but it's useful to mention it here. One way to simplify dependencies for Jackson is use: https://github.com/FasterXML/jackson-bom

Thanks @pjfanning . A BOM is a good way forward. Do you have plans to add jackson-module-kotlin versions to the BOM?

https://github.com/FasterXML/jackson-bom/blob/2.x/pom.xml#L410

jackson-module-kotlin is in the jackson-bom

[victorwss]

Well, this broke my pipeline quite badly and unexpectedly. Even after making jackson-annotations be 2.20, it still tried to load the non-existent jackson-annotations 2.20.0 via some transitive dependency. Instead of smashing my head trying to fix this mess, I just reverted back to 2.19.2 since my project was running smoothly.

[bmaehr]

Why on earth are you doing this kind of breaking change on the last version of the 2.x branch instead of starting it with 3.x?

Nobody would have cared if jackson-annotations 2.20.0 and 3.0 has exactly the same content.

So please release jackson-annotations 2.20 as 2.20.0 and 3.0 and start a new scheme then.

[cowtowncoder]

@bmaehr This approach (3.0 and 2.20.0 being "same", published separately) was indeed the earlier plan. But it was changed based on feedback from integrators (frameworks that integrate with Jackson) -- apparently aside from confusion (which, to be honest, all alternatives considered cause to some degree), such versioning (2.20.0 and 3.0 being equivalent and ideally interchangeable) is problematic with version alignment.

The issue and resolution were discussed here: https://github.com/FasterXML/jackson-future-ideas/discussions/90

I think all alternatives have their drawbacks, and depending on your use case/usage, different choices would be more optimal. But what I can say is that we try our best to deal with complicated systems with lots of stakeholders -- and sometimes it is easier to only see problems with chosen approach without realizing problems with alternatives. I hope that after initial difficulties we get to more stable state where new versioning schemes benefits -- it does support "peaceful co-existence" of Jackson 2.x and 3.x better than alternatives, I think -- are more evident.

Thank you everyone for sharing your viewpoints in respectful and constructive manner.

[veita]

IMO, not a good decision to drop the patch version, since it breaks semantic versioning and thus requires special treatment.

https://semver.org/

[cowtowncoder]

I don't see how it would break semantic versioning: missing patch is same as 0, and leaving it out makes it clear there is no intent to have other patch versions. Semantic versioning concerns itself with compatibility across versions and meaning of specific parts: not on whether one must always use exactly 3 components (Jackson already has occasional micro-patches with 4 and no one complains that breaks SemVer).

And as I explained earlier, the need for Jackson 2.x and 3.x both to depend on shared compatible annotations would make use of 3-digit patch version impractical.

Be that as it may, this is how versions of jackson-annotations will work.

[veita]

I don't see how it would break semantic versioning: missing patch is same as 0, and leaving it out makes it clear there is no intent to have other patch versions.

The specification is unambiguous:

A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.

https://semver.org/#spec-item-2

See also https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions

[cowtowncoder]

Ok I learned something new today.

I agree, then, Jackson does NOT conform to SemVer. We try to follow some of the concepts -- f.ex. role of each 3 components of version (when and how to increase) -- but deviate in places like here (and apparently wrt micro-patches too where 4th digit is only allowed for pre-release).

I think this (varying number of number components, with 0 defaulting) is what Maven uses and I wrongly assumed is what SemVer would do as well. But on plus side Maven (and Gradle, which probably has similar logic) handling has more practical relevance than SemVer specification.

[bmaehr]

I don't see how it would break semantic versioning: missing patch is same as 0, and leaving it out makes it clear there is no intent to have other patch versions.

The specification is unambiguous:

A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.

https://semver.org/#spec-item-2

See also https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions

IMHO this is a "bug" in semantic versioning. If I want to specify just an api then it should only have two digits because apis doesn't have "patches" .

[veita]

IMHO this is a "bug" in semantic versioning. If I want to specify just an api then it should only have two digits because apis doesn't have "patches" .

This is not true. There exist plenty of APIs with patch versions, e.g. the Java/Jakarta Servlet API (3.0.1, 4.0.1, 4.0.2, ...) or OpenAPI (3.0.1, 3.0.2, ...).