Skip to content

Jackson Release 3.0

Jump to bottom
Tatu Saloranta edited this page Nov 1, 2025 · 184 revisions

Jackson Version 3.0 is a Major New version, released on October 3, 2025. It had been in development since late 2017. Multiple Release Candidates were published before official 3.0.0.

3.0 is a major version update and thereby not API compatible with 2.x; however, since 2.10 new methods have been added in 2.x line to reduce incompatibilities.

Overall plans are outlined in JSTEP-1

Status

Branch is open for patch releases.

It is not designated a Long-Term-Support (LTS) version.

Patches

Pre-releases

Following pre-release versions were released:

  • 3.0.0-rc1 (07-Mar-2025)
  • 3.0.0-rc2 (28-Mar-2025)
  • 3.0.0-rc3 (13-Apr-2025)
  • 3.0.0-rc4 (10-May-2025)
    • SBOM publishing
  • 3.0.0-rc5 (22-May-2025)
    • Publishing via new Sonatype Central
    • SBOM publishing broke for some reason, wrt ^^^
  • 3.0.0-rc6 (18-Jul-2025)
    • note: switch to jackson-annotations v2.x (specifically, 2.19.2 for this RC) -- no more 3.0 variant released
  • 3.0.0-rc7 (08-Aug-2025)
    • jackson-annotations 2.20-rc1
  • 3.0.0-rc8 (13-Aug-2025)
  • 3.0.0-rc9 (05-Sep-2025)
    • jackson-annotations 2.20
  • 3.0.0-rc10 (19-Sep-2025)

Documentation

How-Tos

Articles, Blog posts

By Jackson project:

External:

Changes, compatibility

JDK

Java 17 is now required for all 3.x components.

NOTE: jackson-annotations not affected as Jackson 3.x uses 2.x variant (2.20) of jackson-annotations.

Android

From 2.20 baseline of:

  • SDK / API Level 26

to 3.0 baseline of:

  • SDK / API Level 34 (for Records)

(see https://apilevels.com/ for details on levels)

Behavioral changes

jackson-databind

  • databind#2882: Tighten accessor naming rules to not allow leading lower-case or non-letter character for getters/setters

Major changes/features in 3.0

  1. Renaming of artifacts (as per JSTEP-1)
    • Maven group-ids: from "com.fasterxml.jackson" to "tools.jackson"
      • except for jackson-annotations (since 2.x version used by 3.x components)
    • Java packages: from "com.fasterxml.jackson" to "tools.jackson"
      • except for jackson-annotations (since 2.x version used by 3.x components)
        • but note that annotations in other packages (jackson-databind, jackson-dataformat-xml) do get renamed as part of package
  2. Removal of all deprecated methods, functionality, as of 2.x
    • Removed format-auto-detection (interesting idea but not widely used and few formats beyond JSON, XML, Smile, Avro support detection)
  3. Major renaming of core entities (see JSTEP-6)
  4. Changes to many Configuration defaults, esp. "XxxFeature"s (see JSTEP-2)
  5. Native use of module-info.java, instead of baking in via Moditect module (as per JSTEP-11)
  6. All 3 "Java 8 modules", that were separate in Jackson 2.x, are now built-in to jackson-databind (no need to register separately)
    • jackson-module-parameter-names: auto-detection of Constructor parameter names
    • jackson-datatype-jdk8: support for java.util.Optional and other optional types (OptionalDouble, ...)
    • jackson-datatype-jsr310: support java.time types (added in 3.0.0-rc3)
  7. Full immutability of core entities, via Builder-style construction
    • TokenStreamFactory (old JsonFactory)
    • ObjectMapper (addition of format-specific sub-classes, from JsonMapper to XmlMapper)
    • Note Jackson 2.10 and later also support most of Builder-style construction but without strict guarantees of immutability of underlying entities (due to backwards-compatibility reasons)
    • See Jackson 3 immutability with builders
  8. Tighter integration between Streaming and Databinding to allow improved support of non-JSON formats
    • ObjectMapper remains shared API, but every format will have its own mapper subtype, including JsonMapper for JSON
      • Partly implemented in 2.x since 2.10, to support Builder-style construction (albeit without immutability)
    • Format-specific mapper will (have to) use format-specific TokenStreamFactory
  9. Unchecked exceptions (see JSTEP-4)
    • Base 2.x exceptions will be replaced with new counterparts as follows (counterparts will be added in 2.x but mostly used in 3.0)
    • JsonProcessingException (root exception) becomes JacksonException
    • JsonParseException/JsonGenerationException (streaming) will become StreamReadException/StreamWriteException
    • JsonMappingException (root for databind exceptions) becomes DatabindException
    • While new exceptions will be added by Jackson 2.13, their use is limited: they CAN be caught but NOT thrown (sort of "read-only" upgrade) while retaining compatibility across minor versions
  10. Deprecation of unmaintained modules: as per JSTEP-9, 2 modules without maintainer are deprecated and not migrated (at least yet):
    • JSON Schema module (jackson-module-jsonSchema) -- Obsolete, no plans to migrate
    • Hibernate Datatype module(s) (jackson-datatype-hibernateX) -- unmaintained, but if new maintainer(s) found, could be migrated to 3.x
  11. YAML module uses snakeyaml-engine over "classic" snakeyaml

Accumulated changes

Changes, core

Annotations

Separate 3.x no longer maintained or released (since 3.0.0-rc6).

Jackson 3.0 depends on jackson-annotations 2.20.

Streaming

Functionality removal

  • #402: Remove dataformat-auto-detection functionality
  • #413: Remove ObjectCodec: replace with ObjectWriteContext / ObjectReadContext
  • #551: Remove JsonGenerator.setPrettyPrinter() from 3.0
  • #676: Remove JsonGenerator.canWriteBinaryNatively(), canWriteFormattedNumbers() (replaced by StreamWriteCapability equivalents)
  • #689: Remove existing "request payload" functionality
  • #1090: Remove BufferRecyclers.SYSTEM_PROPERTY_TRACK_REUSABLE_BUFFERS
  • #1125: Remove TokenStreamFactory.Feature.USE_THREAD_LOCAL_FOR_BUFFER_RECYCLING
  • #1463: Remove URL taking factory methods of JsonFactory (3.0)

Naming/signature changes

  • #411: Rename JsonStreamContext as TokenStreamContext
  • #663: Rename JsonEOFException as UnexpectedEndOfInputException
  • #670: Replace references to "field" in JsonGenerator, JsonParser method names with "property"
  • #671: Rename getCurrentLocation()/getTokenLocation() as currentLocation()/currentTokenLocation()
  • #793: Rename "com.fasterxml.jackson" -> "tools.jackson"
  • #1364: Rename JsonLocation as TokenStreamLocation [JSTEP-6]
  • #1373: Change TreeNode.propertyNames() return type from Iterator<JsonNode> to Collection<JsonNode> (3.0)
  • #1378: Rename JsonParser.getText() as .getString() [JSTEP-6]
  • #1401: Rename TreeNode.isContainerNode() as isContainer()
  • Rename JsonGenerator.Feature.AUTO_CLOSE_JSON_CONTENT as AUTO_CLOSE_CONTENT

Config default changes

  • #378: Change default for TokenStreamFactory.Feature.INTERN_FIELD_NAMES to false
  • #1231: Enable Fast Floating-Point reading/writing by default in 3.0
  • #1233: Lower default maxNestingDepth of StreamReadConstraints / StreamWriteConstraints to 500 in 3.0

New/Improved functionality

  • #432: Add new TreeNode subtypes: ArrayTreeNode, ObjectTreeNode
  • #433: Add Builder pattern for creating configured Stream factories
  • #456: Add JsonParser.readAsValue(ResolvedType)
  • #492: Ensure primitive type names in error message enclosed in backticks
  • #661: Replace checked JsonProcessingException with unchecked JacksonException
  • #668: Add JacksonException.Reference (demote from JsonMappingException/DatabindException)
  • #680: Allow use of java.nio.file.Path as parser source, generator target
  • #785: Make JsonGenerator.writeXxx() methods chainable
  • #1269: Change JsonFactory.builder() configuration of RecyclerPool to avoid allocating default implementation (in 3.0)
  • #1380: Change 3.0 to use module-info.java directly (and not via Moditect)
  • #1411: Add JsonFactoryBuilder.configureForJackson2(), JsonFactoryBuilder builderWithJackson2Defaults()
  • #1434: Change JsonParser.getNumberType() to return null instead of throwing exception in 3.0
  • #1480: Add JsonGenerator.getPrettyPrinter()
  • Add TreeCodec.nullNode(), TreeNode.isNull() methods
  • Change the way JsonLocation.NA is included in exception messages

Databind

Functionality removal

  • #1772: Remove MapperFeature. USE_STD_BEAN_NAMING
  • #1773: Remove MapperFeature.AUTO_DETECT_xxx features
  • #1917: Remove canSerialize() and canDeserialize() methods from ObjectMapper
  • #1973: Remove support for "default [Map] key serializer" configuration from SerializerProvider
  • #2040: Remove JsonSerializer.isEmpty()
  • #4160: Deprecate DefaultTyping.EVERYTHING in 2.x and remove in 3.0
  • #4659: Remove use of global static TypeFactory singleton from 3.0
  • #4875: Remove JsonNode.fields() from 3.0
  • #5263: Remove deprecated URL-taking readValue() methods in ObjectMapper, ObjectReader from 3.0
  • #5270: Remove ObjectMapper.setSerializationInclusion() from 3.0 (deprecate in 2.20)
  • Remove MappingJsonFactory
  • #4589: Remove MapperFeature.SORT_CREATOR_PROPERTIES_BY_DECLARATION_ORDER from 3.0; make logic default
  • #4835: Remove dynamic work-arounds wrt accessing Record definition

Naming changes

  • #2713: Change wording of UnrecognizedPropertyException to refer to "property" not "field"
  • #3037: Rename Module as JacksonModule in 3.0 (to avoid overlap with java.lang.Module)
  • #3043: Rename SerializerProvider as SerializationContext
  • #3044: Rename JsonDeserializer/JsonSerializer as ValueDeserializer/ValueSerializer
  • #3046: Rename JsonSerializable as JacksonSerializable
  • #3047: Rename Bean[De]SerializerModifier as Value[De]SerializerModifier
  • #4818: Rename AnnotationIntrospector.findDefaultCreator() as findPreferredCreator()
  • #4879: Rename TextNode as StringNode; JsonNode.xxxTextYyy() (mostly) as JsonNode.xxxStringYyy() [JSTEP-3]
  • #4956: Rename JsonNode.isContainerNode() as isContainerNode()
  • #4992: Rename JsonNodeFactory.textNode() as JsonNodeFactory.stringNode() [JSTEP-3]
  • #5066: Move date/time SerializationFeatures into DateTimeFeature (3.0)
  • #5067: Move date/time DeserializationFeatures into DateTimeFeature (3.0)
  • #5079: Move Enum-related DeserializationFeatures into EnumFeature (3.0)
  • #5080: Move Enum-related SerializationFeatures into EnumFeature (3.0)
  • #5272: Replace ObjectMapper.getRegisteredModuleIds() (2.x) with ObjectMapper.registeredModules() (3.0)

Config default changes

  • #493: Change DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES default to false
  • #1484: Change default of MapperFeature.DEFAULT_VIEW_INCLUSION to false in 3.0
  • #1916: Change MapperFeature.USE_GETTERS_AS_SETTERS) default to false
  • #3070: Disable SerializationFeature.FAIL_ON_EMPTY_BEANS by default
  • #3406: Change default of DeserializationFeature.FAIL_ON_TRAILING_TOKENS to true for 3.0
  • #4552: Change MapperFeature.ALLOW_FINAL_FIELDS_AS_MUTATORS default to false
  • #4566: Enable DeserializationFeature.READ_ENUMS_USING_TO_STRING by default
  • #4567: Enable SerializationFeature.WRITE_ENUMS_USING_TO_STRING by default
  • #4572: Change MapperFeature.SORT_PROPERTIES_ALPHABETICALLY default to true (3.x)
  • #4845: Change default of SerializationFeature.WRITE_DATES_AS_TIMESTAMPS to false in 3.0
  • #4846: Change default of SerializationFeature.WRITE_DURATIONS_AS_TIMESTAMPS to false in 3.0
  • #4858: Change default of DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES to true for 3.0
  • #5065: Change default for DateTimeFeature.ONE_BASED_MONTHS to true in 3.0

Functionality changes

  • #1600: Serializing locale with underscore, not standard hyphen
  • #1762: StdDateFormat: serialize time offset using colon
  • #1774: Merge Java8 datatype (Optional, Stream) support in core databind
  • #1775: Merge Java8 parameter name support (jackson-module-parameter-names) in core databind
  • #1781: Return ObjectNode from ObjectNode set-methods in order to allow better chaining
  • #1829: JsonNode.deepCopy() ClassCastException`s
  • #1888: Merge ResolvableSerializer into JsonSerializer, ResolvableDeserializer into JsonDeserializer
  • #1889: Merge ContextualSerializer into JsonSerializer, ContextualDeserializer into JsonDeserializer
  • #1994: Limit size of SerializerCache, auto-flush on exceeding
  • #1995: Limit size of DeserializerCache, auto-flush on exceeding
  • #2083: Replace Reflection usage with MethodHandle (3.0)
  • #2177: Change parent type of JsonProcessingException to be RuntimeException
  • #2405: Make java.sql.Date serializer default to same output as java.util.Date
  • #2593: StackTraceElement w/ >= Java 9 doesn't deserialize properly
  • #2882: Tighten accessor naming rules to not allow leading lower-case or non-letter character for getters/setters
  • #3028: Change UUIDSerializer to use StreamWriteCapability check instead of JsonGenerator.canWriteBinaryNatively()
  • #3561: Add DeserializationContext as an argument for SettableBeanProperty.set(...)
  • #3601: Change Optional deserialization from "absent" value into null, from "empty"
  • #4381: Prevent construction of null-valued JsonNodes (like TextNode)
  • #4603: Keep full stacktrace when re-throwing exception with DatabindException during deserialization
  • #4664: Change EnumNamingStrategy.convertEnumToExternalName() to take MapperConfig argument
  • #4840: Increase minimum Android SDK required to 34 for Jackson 3.0
  • #4891: Change 3.0 to use module-info.java directly for build (instead of via Moditect)
  • #4907: Reduce/eliminate introspection on java.* classes
  • #4958: Extend, improve set of number value accessors for JsonNode (JsonNode.intValue() etc) [JSTEP-3]
  • #4991: Extend, improve set of non-number scalar value accessors for JsonNode (JsonNode.booleanValue() etc) [JSTEP-3]
  • #5003: Extend, improve set of JsonNode.asXxx() methods for number types
  • #5034: Extend, improve set of JsonNode.asXxx() methods for non-number types (Boolean, String)
  • #5078: Create proper MonthDeserializer and MonthSerializer (don't rely on EnumDeserializer/EnumSerializer)
  • #5093: Change the way BeanDescription passed during serializer construction to use Supplier
  • #5094: Change the way BeanDescription passed during deserializer construction to use Supplier
  • #5138: add asShort(), asFloat() conversion methods
  • #5153: Improve error handling for numeric values in POJONode
  • #5158: Add "optional" variants -- shortValueOpt(), floatValueOpt(), asShortOpt(), asFloatOpt()
  • #5169: Add missing methods in Serializers for Enum and TreeNode types (3.0)
  • #5244: Support accessing annotations via AnnotatedMember.annotations()
  • #5287: Change JsonNode.stringValue() of NullNode to return null, not fail (3.0)
  • #5302: Add one more parameter for AnnotationIntrospector.findPreferredCreator() method

New features

  • #1058: Add a way to pass standard and format-specific parser/generator flags during parser/generation construction
  • #1789: Add createGenerator methods in ObjectMapper, ObjectWriter
  • #1790: Add createParser methods in ObjectMapper, ObjectReader
  • #1883: Add "abstract type mapping" for deserialization from Map<ENUMTYPE,V> into EnumMap (and Set<ENUMTYPE> to EnumSet<EnumType>)
  • #1954: Add Builder pattern for creating configured ObjectMapper instances
  • #1955: Change the way Modules configure, interact with ObjectMapper
  • #2013: Allow use of java.nio.file.Path for readValue(), writeValue()
  • #2176: Add JsonMapper.shared() static method
  • #2382: Support AutoCloseable with SerializationFeature.CLOSE_CLOSEABLE
  • #2411: Allow valueToTree() via SerializationContext, add to ObjectWriter
  • #2539: Add Deserializers.hasDeserializerFor() (and something for DeserializerFactory) to allow detection of explicitly supported types
  • #2828: Add DatabindException as intermediate subtype of JsonMappingException
  • #3522: Support serializing ByteArrayOutputStream as "simple" Binary value
  • #3536: Create new exception type JsonNodeException for use by JsonNode-related problems
  • #5004: Add JsonMapper.builderWithJackson2Defaults()
  • #5025: Add support for automatic detection of subtypes (like @JsonSubTypes) from Java 17 sealed types
  • #5032: Merge jackson-datatype-jsr310 functionality into jackson-databind
  • #5110: Add missing ObjectMapper#createNonBlockingByteBufferParser() method
  • #5111: Improve support for deserializing from TokenBuffer (f.ex for content buffered for non-blocking parsing)
  • #5112: Add a MapperBuilder#findAndAddModules(ClassLoader) variant
  • #5314: Add MapperFeature.DETECT_PARAMETER_NAMES to allow disabling parameter-names functionality
  • #5318: Allow auto-detection of Properties-based Constructor even if class has no-parameters (default) Constructor

Fixes

  • #4310: ParameterNamesModule causes @ConstructorProperties to be ignored, constructor called with null value
  • #5231: Deserialization through setter with vararg parameter fails ClassCastException
  • #5309: Confusing exception for DoubleNode to Integer conversion in Jackson 3
  • #5319: TreeTraversingParser does not respect DeserializationFeature.ACCEPT_FLOAT_AS_INT

Changes, data formats

Avro

  • #522: JSTEP-8: rename AvroParser.Feature as AvroReadFeature, AvroGenerator.Feature as AvroWriteFeature

CBOR

  • #524: JSTEP-8: rename CBORGenerator.Feature as CBORWriteFeature
  • #582: Change defaults for CBORReadFeature.DECODE_USING_STANDARD_NEGATIVE_BIGINT_ENCODING and CBORWriteFeature.ENCODE_USING_STANDARD_NEGATIVE_BIGINT_ENCODING to true (enabled) in 3.0
  • #591: Change CBOR Features defaults for 3.0

CSV

  • #510: JSTEP-8: rename CsvParser.Feature as CsvReadFeature, CsvGenerator.Feature as CsvWriteFeature

Ion

  • #526: JSTEP-8: rename IonParser.Feature as IonReadFeature, IonGenerator.Feature as IonWriteFeature

Smile

  • #528: JSTEP-8: rename SmileParser.Feature as SmileReadFeature, SmileGenerator.Feature as SmileWriteFeature

XML

  • #687: JSTEP-8: rename FromXmlParser.Feature as XmlReadFeature, ToXmlGenerator.Feature as XmlWriteFeature
  • #701: Change 3.0 to use module-info.java directly, remove use of Moditect
  • #725: Change XmlWriteFeature.UNWRAP_ROOT_OBJECT_NODE default to true
  • #727: Change XmlWriteFeature.WRITE_NULLS_AS_XSI_NIL default to true
  • #728: Change XmlWriteFeature.AUTO_DETECT_XSI_TYPE default to true
  • #729: Change XmlWriteFeature.WRITE_XML_SCHEMA_CONFORMING_FLOATS default to true
  • #731: Support configureForJackson2() with XmlMapper
  • #732: Change XmlReadFeature.AUTO_DETECT_XSI_TYPE default to true

YAML

  • #106: Upgrade to snakeyaml-engine (from classic snakeyaml)
  • #215: .without(YAMLGenerator.Feature.WRITE_DOC_START_MARKER) seems to be ignored
  • #512: JSTEP-8: rename YAMLParser.Feature as YAMLReadFeature, YAMLGenerator.Feature as YAMLWriteFeature

Changes, data types

Guava

  • #24: Support for Guava's Immutable{Double,Int,Long}Array
  • #69: Add support for Guava primitives during deserialization

JSR-353

  • #65: jackson-datatype-jsr353 SPI class package name wrong

Changes, other Modules

Afterburner

  • #26: Improve handling of parent class loader for generated classes
  • #29: Use ByteBuddy (instead of "raw" ASM) for Afterburner
  • #225: Afterburner 3.0 fails to handle interface "default" methods
  • #284: Remove shade plugin from 3.0 Afterburner

Mr Bean

  • #28: Use ByteBuddy (instead of "raw" ASM) for Mr Bean

Changes, Providers

JAX-RS Providers

  • #123: Change jackson-module-jaxb-annotations dependency to optional in pom.xmls

Jakarta-RS Providers

  • Change jackson-module-jakarta-xmlbind-annotations dependency to optional in pom.xmls

Changes, JVM Languages

Kotlin

  • #887: Change 3.0 to use module-info.java directly [JSTEP-11]
  • #936: StrictNullChecks and SingletonSupport are now enabled by default
  • #952: The isRequired result from kotlin-module no longer overrides the result from JacksonAnnotationIntrospector or other AnnotationIntrospectors. Tests have confirmed that @JsonProperty(required = true) for nullable parameters has been changed to be determined as required.

Scala

The jackson-module-scala release notes are listed in its GitHub repository.

The main compatibility issues, other than the tool.jackson package names are

  • New ScalaModule builder
  • Dropped Scala 2.11 support
  • Dropped paranamer dependency

Changes, other components

jackson-jr

  • 96: Rename "com.fasterxml.jackson" -> "tools.jackson"
  • 185: Change 3.0 to use module-info.java directly [JSTEP-11]
Clone this wiki locally