Skip to content

Jackson Release 3.0

Jump to bottom
Tatu Saloranta edited this page Mar 29, 2025 · 99 revisions

Version 3.0 is under development, as of March 2025 (and since late 2017).

It 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

Pre-releases

So far, following pre-release versions have been released:

  • 3.0.0-rc1 (07-Mar-2025)
    • note: problems with Gradle metadata
  • 3.0.0-rc2 (28-Mar-2025)
    • note: still problems with Gradle metadata (some fixed, not all)

Changes, compatibility

JDK

Java 17 is now required for all components (even jackson-annotations that does not use post-JDK-8 features but has module-info.java to process)

Android

From 2.18 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)

Major changes/features in 3.0

  1. Removal of all deprecated methods, functionality, as of 2.x
    • Remove format-auto-detection (interesting idea but not widely used and few formats beyond JSON, XML, Smile, Avro support detection)
  2. Renaming of artifacts (as per JSTEP-1)
    • Maven group-ids: from "com.fasterxml.jackson" to "tools.jackson"
    • Java packages: from "com.fasterxml.jackson" to "tools.jackson"
  3. Native use of module-info.java, instead of baking in via Moditect module (as per JSTEP-11)
  4. Out of 3 "Java 8 modules", that were separate in Jackson 2.x, two 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, ...)
  5. 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 will 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
  6. 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
  7. 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

Accumulated changes

Changes:

  • Regular entries included in 3.0.0-rc2
  • Separate entries to be included 3.0.0-rc3

Changes, core

Annotations

  • #272: Require JDK17 for jackson-annotations 3.0 for proper module-info.java
  • #274: Change 3.0 to use module-info.java directly for build (instead of via Moditect)
  • Change JsonInclude.value, JsonInclude.content to USE_DEFAULTS (from ALWAYS)

Streaming

  • #378: Change default for TokenStreamFactory.Feature.INTERN_FIELD_NAMES to false
  • #402: Remove dataformat-auto-detection functionality
  • #411: Rename JsonStreamContext as TokenStreamContext
  • #413: Remove ObjectCodec: replace with ObjectWriteContext / ObjectReadContext
  • #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
  • #551: Remove JsonGenerator.setPrettyPrinter() from 3.0
  • #663: Rename JsonEOFException as UnexpectedEndOfInputException
  • #668: Add JacksonException.Reference (demote from JsonMappingException/DatabindException)
  • #670: Replace references to "field" in JsonGenerator, JsonParser method names with "property"
  • #671: Replace getCurrentLocation()/getTokenLocation() with currentLocation()/currentTokenLocation()
  • #676: Remove JsonGenerator.canWriteBinaryNatively(), canWriteFormattedNumbers() (replaced by StreamWriteCapability equivalents)
  • #680: Allow use of java.nio.file.Path as parser source, generator target
  • #689: Remove existing "request payload" functionality
  • #785: Make JsonGenerator.writeXxx() methods chainable
  • #793: Rename "com.fasterxml.jackson" -> "tools.jackson"
  • #1090: Remove BufferRecyclers.SYSTEM_PROPERTY_TRACK_REUSABLE_BUFFERS
  • #1125: Remove TokenStreamFactory.Feature.USE_THREAD_LOCAL_FOR_BUFFER_RECYCLING
  • #1200: Change JsonWriteFeature.ESCAPE_FORWARD_SLASHES default to true for 3.0
  • #1231: Enable Fast Floating-Point reading/writing by default in 3.0
  • #1233: Lower default maxNestingDepth of StreamReadConstraints / StreamWriteConstraints to 500 in 3.0
  • #1269: Change JsonFactory.builder() configuration of RecyclerPool to avoid allocation default implementation (in 3.0)
  • #1364: rename JsonLocation as TokenStreamLocation [JSTEP-6]
  • #1373: Change TreeNode.propertyName() return type from Iterator<JsonNode> to Collection<JsonNode> (3.0)
  • #1378: Rename JsonParser.getText() as .getString() [JSTEP-6]
  • #1380: Change 3.0 to use module-info.java directly (and not via Moditect)
  • #1401: Rename TreeNode.isContainerNode() as isContainer()
  • #1411: Add JsonFactoryBuilder.configureForJackson2(), JsonFactoryBuilder builderWithJackson2Defaults()
  • Rename JsonGenerator.Feature.AUTO_CLOSE_JSON_CONTENT as AUTO_CLOSE_CONTENT
  • Add TreeCodec.nullNode(), TreeNode.isNull() methods
  • Change the way JsonLocation.NA is included in exception messages
  • Minimum Java baseline: Java 17

Databind

Functionality removal (3.0.0-rc2)

  • #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
  • Remove MappingJsonFactory
  • #4659: Remove use of global static TypeFactory singleton from 3.0
  • #4875: Remove JsonNode.fields() from 3.0

Functionality changes (3.0.0-rc2)

  • #493: Change DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES default to false
  • #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
  • #1916: Change MapperFeature.USE_GETTERS_AS_SETTERS) default to false
  • #1994: Limit size of SerializerCache, auto-flush on exceeding
  • #1995: Limit size of DeserializerCache, auto-flush on exceeding
  • #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()
  • #3070: Disable SerializationFeature.FAIL_ON_EMPTY_BEANS by default
  • #3406: Change default of DeserializationFeature.FAIL_ON_TRAILING_TOKENS to true for 3.0
  • #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)
  • #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)
  • #4589: Remove MapperFeature.SORT_CREATOR_PROPERTIES_BY_DECLARATION_ORDER from 3.0; make logic default
  • #4664: Change EnumNamingStrategy.convertEnumToExternalName() to take MapperConfig argument
  • #4835: Remove dynamic work-arounds wrt accessing Record definition
  • #4840: Increase minimum Android SDK required to 34 for Jackson 3.0
  • #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
  • #4891: Change 3.0 to use module-info.java directly for build (instead of via Moditect)
  • #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)

Naming changes (3.0.0-rc2)

  • #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]

New features (3.0.0-rc2)

  • #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
  • #4968: Add JsonMapper builder support in Jackson 3.0 for optionally creating mappers with Jackson2 config defaults
  • #5004: Add JsonMapper.builderWithJackson2Defaults()
  • #5025: Add support for automatic detection of subtypes (like @JsonSubTypes) from Java 17 sealed types

For 3.0.0-rc3

None yet

Changes, dataformats

Avro

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

CBOR

  • #524: JSTEP-8: rename CBORGenerator.Feature as CBORWriteFeature

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

  • #512: JSTEP-8: rename YAMLParser.Feature as YAMLReadFeature, YAMLGenerator.Feature as YAMLWriteFeature

Changes, datatypes

Guava

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

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

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 modules

Clone this wiki locally