Skip to content

JSTEP 2

Jump to bottom
wrongwrong edited this page Feb 1, 2025 · 46 revisions

(Back to JSTEP page)

Jackson 3 default settings, behavior changes

Author

Tatu Saloranta (@cowtowncoder)

Version history

  • 2025-01-31: Update wrt SerializationFeature.WRITE_DURATIONS_AS_TIMESTAMPS default change
  • 2025-01-29: Update wrt DeserializationFeature.FAIL_ON_TRAILING_TOKENS default change
  • 2025-01-19: Add Kotlin module proposed change links
  • 2024-12-09: Update with latest
  • 2024-07-21: DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES default changed
  • 2024-06-06: DeserializationFeature.READ_ENUMS_USING_TO_STRING, SerializationFeature.WRITE_ENUMS_USING_TO_STRING defaults changed
  • 2024-05-31: MapperFeature.ALLOW_FINAL_FIELDS_AS_MUTATORS default changed
  • 2024-03-01: minor update on default changes
  • 2022-09-18: add proposed default change to Date/Times-as-timestamps DeserializationFeatures
  • 2019-02-10: create first version from earlier notes

Status

Work-in-progress as of Jackson 2.18 (and will remain until 3.0.0 release)

Overview

During Jackson 2.x development, certain default settings have proven either problematic by development team, or non-intuitive/non-optimal by users: latter indicated both by filed issues and comments on mailing list discussions. Since default settings and behavior are important part of the public API, changes have had to wait until major version change in most cases.

This document details proposed/planned as well as implemented changes.

Changes to jackson-core defaults

JsonReadFeature

No changes

JsonWriteFeature

  • JsonWriteFeature.ESCAPE_FORWARD_SLASHES now defaults to true (see core#1200)

StreamReadConstraints

  • DEFAULT_MAX_DEPTH to 500 (from 1,000) (see core#1233)

StreamWriteConstraints

  • DEFAULT_MAX_DEPTH to 500 (from 1,000) (see core#1233)

StreamReadFeature

  • USE_FAST_DOUBLE_PARSER: enabled by default in 3.0 (see core#1231)
  • USE_FAST_BIG_NUMBER_PARSER: enabled by default in 3.0 (see core#1231)

StreamWriteFeature

  • USE_FAST_DOUBLE_WRITER: enabled by default in 3.0 (see core#1231)

Changes to jackson-databind defaults

MapperFeature

First, following deprecated features are to be removed from 3.0:

  • USE_STD_BEAN_NAMING: should always be enabled, no need for old slightly differing algorithm
  • AUTO_DETECT_xxx: old limited settings superceded by more granular settings -- frees up 5 features

And defaults to following features have been changed:

  • ALLOW_FINAL_FIELDS_AS_MUTATORS: default to false -- while enabling may be useful sometimes, it confuses users in general and is unlikely to even work with future JDKs/JVMs
  • USE_GETTERS_AS_SETTERS: default to false -- earlier default was based on JAXB but is quite confusing for users
  • SORT_PROPERTIES_ALPHABETICALLY: default to true (false really doesn't make much sense since it is unstable, and arbitrary based on JVM/JDK)

DeserializationFeature

Changes completed:

  • FAIL_ON_UNEXPECTED_VIEW_PROPERTIES: default to true (as per databind#437)
  • FAIL_ON_UNKNOWN_PROPERTIES: default to false (TOP REQUEST by users) databind#493
  • READ_ENUMS_USING_TO_STRING: default to true (instead of false that relies on name()) databind#4566
  • FAIL_ON_NULL_FOR_PRIMITIVES: default to true (databind#4858)
    • Setting to false would allowing coercion from JSON null into Java int, long and so on. For some users, and especially on "low null" languages like Kotlin, such coercion is rarely expected.
  • FAIL_ON_TRAILING_TOKENS: default to true (databind#3406)

Other changes, potential:

  • Although all features still make sense, would make sense to try to combine some, and/or create new type of configuration to use instead of feature -- for example
    • FAIL_xxx are all kind of similar. DeserializationFail, or "check" or... ?
    • READ_xxx_as_yyy, similarly
    • ACCEPT_xxx_as_yyy, similarly

SerializationFeature

Changes completed:

  • WRITE_ENUMS_USING_TO_STRING: default to true (to keep symmetry between its DeserializationFeature.READ_ENUMS_USING_TO_STRING counterpart) databind#4567
  • FAIL_ON_EMPTY_BEANS: default to false databind#3070
  • FAIL_ON_ORDER_MAP_BY_INCOMPARABLE_KEY : was added in 2.19. Changed default in 3.0 via databind#4781
  • WRITE_DURATIONS_AS_TIMESTAMPS: change default to false to serialize as ISO-8601 String -- databind#4846

Changes proposed:

  • Writing date/time values as ISO-8601 Strings instead of (Java style) timestamps
    • WRITE_DATES_AS_TIMESTAMPS: change default to false to serialize as ISO-8601 String -- databind#4845
    • WRITE_DATE_KEYS_AS_TIMESTAMPS: RETAIN default of false -- no change

Other changes, potential:

  • Most if not all features seem to make sense, but there are groups that could use unification of some kind
    • FAIL_ON_xxx
    • WRITE_xxx_as_yyy

Changes to Date/Time defaults

Changes to defaults completed:

  • none yet

Changes to defaults proposed:

  • Disable lenient setting (that is: default to "strict")
  • Check defaults of date/time handling

Changes to jackson-module-kotlin defaults

Kotlin module has a few proposed/accept changes.

Misc other default setting, behavior changes

JsonNode handling

  • DecimalNode creation via JsonNodeFactory: default to NOT truncating trailing zeroes (minimal trimming), because JsonNode should by default expose content as close to way it came.
Clone this wiki locally