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.Integer or java.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, coercion

• ACCEPT_EMPTY_ARRAY_AS_NULL_OBJECT (default: false) (since 2.5)
  • 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.
• ACCEPT_FLOAT_AS_INT (default: true) (since 2.6)
  • Determines whether coercion from a floating point value (like 1.25) is allowed into integral types (int, long, Integer, Long, BigInteger) or not.
  • If not allowed, attempts will result in a JsonMappingException
  • If allowed, floating-point value will be truncated to matching integral value
• ADJUST_DATES_TO_CONTEXT_TIME_ZONE (default: true) (since 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.
• READ_DATE_TIMESTAMPS_AS_NANOSECONDS (default: false) (since 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.
• 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_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE (default: false) (since 2.8)
  • Feature that allows unknown Enum values to be ignored and in their place, use a predefined value (specified using the @JsonEnumDefaultValue annotation)
  • Example:

    enum MyEnum { A, B, @JsonEnumDefaultValue UNKNOWN }
    ...
    final ObjectMapper mapper = new ObjectMapper();
    mapper.enable(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE);
    
    MyEnum value = mapper.readValue("\"foo\"", MyEnum.class);
    assertSame(MyEnum.UNKNOWN, value);
    

Failure handling

• FAIL_ON_IGNORED_PROPERTIES (default: false) (since 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.
• 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_INVALID_SUBTYPE (default: true) (since 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_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_READING_DUP_TREE_KEY (default: false) (since 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_UNRESOLVED_OBJECT_IDS (default: true) (since 2.5)
  • Feature that determines what happens if an Object Id reference is encountered that does not refer to an actual Object with that id ("unresolved Object Id")
  • If enabled, a JsonMappingException will be thrown
  • If disabled, null reference is used in place of resolved Java Object
• FAIL_ON_MISSING_CREATOR_PROPERTIES (default: false) (since 2.6)
  • Feature that determines what happens if one or more Creator properties (properties bound to parameters of Creator method (constructor or static factory method)) are missing value to bind to from content.
  • If enabled, a JsonMappingException (with information like name of the first missing property) will be thrown
  • If disabled, the "null value" for matching type is used instead (null value is determined by JsonSerializer for the type, usually null but custom deserializers may choose other placeholder).
• 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.