Deserialization Features

Jackson on/off features: DeserializationFeature

Jackson defines a set of features that relate to deserialization (reading JSON into Java Objects), and that can be changed on per-call basis, by using ObjectReader; for example:

final ObjectReader r = objectMapper.reader(MyType.class);
// enable one feature, disable another
MyType value = r
  .with(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS)
  .without(DeserializationFeature.WRAP_EXCEPTIONS)
  .readValue(source);

You can also change defaults for ObjectMapper, to be used as the base for all ObjectReader instances, using enable(feature), disable(feature) and configure(feature, state) methods.

Settings can be divided in couple of loose categories, as follows.

Type conversions

• USE_BIG_DECIMAL_FOR_FLOATS (default: false)
  • Controls whether java.math.BigDecimal is used for deserializing JSON floating point numbers, when resulting type is a generic type java.lang.Object) or generic number type (java.lang.Number); if disabled type will be java.lang.Double.
  • Does not affect explicit type (i.e. if expected result type is java.lang.Double or such)
• USE_BIG_INTEGER_FOR_INTS (default: false)
  • Similar to USE_BIG_DECIMAL_FOR_FLOATS, but used when value to map is a JSON integer number (numeric value without decimal point). If enabled, type java.math.BigInteger}}} is used for binding to generic types; if disabled, java.lang.Integerorjava.lang.Long` is used (smallest applicable type that can contain actual value)
• USE_JAVA_ARRAY_FOR_JSON_ARRAY (default: false)
  • Determines whether to bind JSON Arrays as java.util.Lists or Object[] instances, when binding to nominal type of java.lang.Object: if disabled, as java.util.List, if enabled as Object[].
• READ_ENUMS_USING_TO_STRING (default: false)
  • Determines which method is used to determine expected serialization of an Enum: if false (default), use Enum.name(); if true, Enum.toString().

Structural conversions

• ACCEPT_SINGLE_VALUE_AS_ARRAY (default: false)
  • Allows auto-conversion from non-JSON-array values to single-element arrays and Collections (adding implicit "array wrapper"): this is sometimes necessary for interoperability, as some libraries and frameworks omit JSON arrays when serializing single-element arrays.
• UNWRAP_ROOT_VALUE (default: false)
  • Feature to allow "unwrapping" root-level JSON value, to match setting of SerializationFeature#WRAP_ROOT_VALUE used for serialization.
  • Will verify that the root JSON value is a JSON Object, and that it has a single property with expected root name. If not, a JsonMappingException is thrown; otherwise value of the wrapped property will be deserialized as if it was the root value.
• UNWRAP_SINGLE_VALUE_ARRAYS (default: false) (since 2.4
  • Allows auto-conversion from single-element arrays to non-JSON-array values : this is similar to the ACCEPT_SINGLE_VALUE_AS_ARRAY feature but works in the opposite manner (i.e. if you have a bound property that is not an array or collection, a single value array in JSON would be acceptable to bind to that property). If the JSON value contains more than one element in the array, deserialization will still fail.

Value conversions

• ACCEPT_EMPTY_ARRAY_AS_NULL_OBJECT (default: false)
  • Determines whether empty Array value ("[ ]" in JSON) is accepted as null value for regular POJOs ("beans") with data-binding: this can be useful when dealing endpoints written in a language like PHP that has loose typing and may represent missing objects as empty Arrays.
• ACCEPT_EMPTY_STRING_AS_NULL_OBJECT (default: false)
  • Determines whether empty String value is accepted as null value for regular POJOs ("beans") with data-binding: this can be useful when dealing endpoints written in a language that has loose typing and may represent missing objects as Empty Strings.
• READ_UNKNOWN_ENUM_VALUES_AS_NULL (default: false)
  • Feature that allows unknown Enum values to be parsed as Java null values. If disabled, unknown Enum values will throw exceptions.
  • Note that in some cases this will basically ignore unknown Enum values; this is the keys for keys of java.util.EnumMap and values of java.util.EnumSet (because nulls are not accepted in these cases.
• READ_DATE_TIMESTAMPS_AS_NANOSECONDS (default: false) -- Since Jackson 2.2
  • Feature that controls whether numeric timestamp values are expected to be written using nanosecond timestamps (enabled) or not (disabled); if disabled, standard millisecond timestamps are assumed.
• ADJUST_DATES_TO_CONTEXT_TIME_ZONE (default: true) -- since Jackson 2.2
  • Feature that specifies whether context provided java.util.TimeZone `SerializerProvider#getTimeZone()} should be used to adjust Date/Time values on deserialization, even if value itself contains timezone information.
  • If enabled, contextual TimeZone will essentially override any other TimeZone information; if disabled, it will only be used if value itself does not contain any TimeZone information.

Failure handling

• FAIL_ON_UNKNOWN_PROPERTIES (default: true)
  • Used to control whether encountering of unknown properties (one for which there is no setter; and there is no fallback "any setter" method defined using @JsonAnySetter annotation) should result in a JsonMappingException (when enabled), or just quietly ignored (when disabled)
• FAIL_ON_NULL_FOR_PRIMITIVES (default: false)
  • Determines whether JSON null is acceptable for Java primitive types (int, boolean, double etc); if set to 'false', default value is used; if 'true', a JsonProcessingException will be thrown.
• FAIL_ON_NUMBERS_FOR_ENUMS (default: false)
  • Determines whether JSON integer numbers (0, 1, 2, ...) can be deserialized into Java Enum types; if set to 'false', this is legal and value is used to deserialize value that matches Enum.ordinal(); if 'true', trying to deserialize JSON number into Enum throws a JsonProcessingException
• FAIL_ON_INVALID_SUBTYPE (default: true) (since Jackson 2.2)
  • Determines what happens when type information for polymorphic types (see @JsonTypeInfo) is either missing or invalid (unmappable); if enabled, exception is thrown; if disabled, null reference is used instead (as type can not be determined).
• FAIL_ON_READING_DUP_TREE_KEY (default: false) (since Jackson 2.3)
  • Determines what happens when incoming JSON has duplicate property names, when parsing as JSON Trees (JsonNode): if enabled, an exception is thrown; if false, no exception thrown and the last value is used.
• FAIL_ON_IGNORED_PROPERTIES (default: false) (since Jackson 2.3)
  • Determines what happens if an explicitly ignored property is encountered during deserialization; if true, a JsonMappingException will be thrown; if false, it will quietly skipped.
• WRAP_EXCEPTIONS (default:true)
  • Determines whether Jackson is to catch Exceptions other than IOException and its own exception types, to add more information on location and path to property.
  • If disabled, exceptions like IllegalArgumentException are passed as-is; if enabled, they will be caught and re-thrown as a Jackson exception (JsonMappingException or its subtype)

Other

• EAGER_DESERIALIZER_FETCH (default: true):
  • Determines whether ObjectReader should try to fetch JsonDeserializer to use when constructed and given type information to locate it.
  • The benefit of enabling this feature is that if ObjectReader is used more than once, lookup only occurs once; if disabled, lookup needs to be performed every time a deserialization (via readValue()) is called.