Mapper Features

Jackson on/off features: MapperFeature

Jackson defines a set of per-mapper configuration, which can ONLY be defined before using ObjectMapper -- meaning that these settings can not be changed on-the-fly, on per-request basis. They configure fundamental POJO introspection details, and resulting built objects (serializers, deserializers, related) are heavily cached. If you need differing settings for these, you have to use separate ObjectMapper instances.

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

Annotation handling

• USE_ANNOTATIONS (default: true): whether any annotation processing is used or not
  • may be useful on platforms where annotation-processing is hideously expensive (like Android)

Introspection, property detection

• AUTO_DETECT_CREATORS (default: true)
  • If enabled, some Creator methods (constructor, static factory method that returns value of this type) may be automatically detected, without explicit @JsonCreator annotation
  • To be auto-detected, Creator method has to:
    • Be public
    • Take only one argument, of type: String, int, long or boolean
    • For factory methods, name of the method has to be valueOf; other factory methods are not auto-detected
  • Only "delegating" style is supported, as of Jackson 2.7 (this may change in future)
• AUTO_DETECT_FIELDS (default: true)
• AUTO_DETECT_GETTERS (default: true)
• AUTO_DETECT_IS_GETTERS (default: true)
• AUTO_DETECT_SETTERS (default: true)
• REQUIRE_SETTERS_FOR_GETTERS (default: false)
• USE_GETTERS_AS_SETTERS (default: true)
• INFER_CREATOR_FROM_CONSTRUCTOR_PROPERTIES (default: true) (since 2.9)
• INFER_PROPERTY_MUTATORS (default: true) (since 2.2)
  • If enabled, mutators (field or setter used for changing POJO property value) may be inferred: that is, un-annotated, not-visible field or setter can be considered mutator if (and only if!) there is a fully visible or explicitly annotated (@JsonProperty) accessor (getter or field) with same logical name.
  • Enabled by default for convenience: may be disabled if fully explicit annotations are desired.
• ALLOW_FINAL_FIELDS_AS_MUTATORS (default: true) (since 2.2): Feature that determines whether member fields declared as 'final' may be auto-detected to be used mutators (used to change value of the logical property) or not
  • If enabled, 'final' access modifier has no effect, and such fields may be detected according to usual visibility and inference rules; if disabled, such fields are NOT used as mutators except if explicitly annotated for such use.
  • Feature is enabled by default, for backwards compatibility reasons.
• ALLOW_VOID_VALUED_PROPERTIES (default: false (2.x)) (since 2.12)
  • Feature that determines whether nominal property type of Void is allowed for Getter methods to indicate null valued pseudo-property or not.
  • If enabled, such properties are recognized (mostly to support use by some code generation frameworks, non-Java JVM languages like Kotlin, Scala); if disabled, such property accessors (or at least getters) are ignored.
  • Feature is disabled by default in Jackson 2.x, for backwards compatibility reasons; will be enabled in 3.0
• ALLOW_IS_GETTERS_FOR_NON_BOOLEAN (default: {@code false}) (since 2.14)
  • Feature that determines where getters with is-Prefix are detected for non-{@code boolean} return types; if disabled only methods that return {@code boolean} or {@code Boolean} qualify as "is-getters".
  • Specifically added to support Kotlin properties

Reflection, access

• CAN_OVERRIDE_ACCESS_MODIFIERS (default: true)
  • Feature that determines whether method and field access modifier settings can be overridden when accessing properties. If enabled, method AccessibleObject#setAccessible may be called to enable access to otherwise unaccessible objects.
• OVERRIDE_PUBLIC_ACCESS_MODIFIERS (default: true) (since 2.7)
  • If CAN_OVERRIDE_ACCESS_MODIFIERS is enabled, this feature further determines whether setAccessible(true) is called on members (methods, fields, constructors):
    • For non-public members (or, public members of non-public classes), call is always made since Reflection access is not possible otherwise
    • For public members (of public classes), calls is only made if this feature is enabled

Name handling

• SORT_PROPERTIES_ALPHABETICALLY (default: false): Feature that defines default property serialization order used: either alphabetic (true), or "whatever order JDK exposes fields in" (false).
  • Only applies to POJO fields, does not apply to java.util.Map serialization!
  • Note that this is just the default behavior, and can be overridden by explicit overrides in classes, for example with @JsonPropertyOrder
• USE_WRAPPER_NAME_AS_PROPERTY_NAME (default: false) (since 2.2): Feature that can be enabled to make property names be overridden by wrapper name (usually detected with annotations as defined by {@link AnnotationIntrospector#findWrapperName}. If enabled, all properties that have associated non-empty Wrapper name will use that wrapper name instead of property name.
  • If disabled, wrapper name is only used for wrapping (if anything).
• ACCEPT_CASE_INSENSITIVE_ENUMS (default: false) (since 2.9)
• ACCEPT_CASE_INSENSITIVE_PROPERTIES (default: false) (since 2.5: Feature that will allow for more forgiving deserialization of incoming JSON.
  • If enabled, the bean properties will be matched using their lower-case equivalents, meaning that any case-combination (incoming and matching names are canonicalized by lower-casing) should work.
  • Note that there is additional performance overhead since incoming property names need to be lower-cased before comparison, for cases where there are upper-case letters. Overhead is more significant if non-lower-case characters are included (i.e. name needs to be changed on the fly)
• ACCEPT_CASE_INSENSITIVE_VALUES (default: false) (since 2.10)
• ALLOW_EXPLICIT_PROPERTY_RENAMING (default: false) (since 2.7)
  • Feature that when enabled will allow explicitly named properties (i.e., fields or methods annotated with @com.fasterxml.jackson.annotation.JsonProperty ("explicitName")) to be re-named by a PropertyNamingStrategy, if one is configured.
• USE_STD_BEAN_NAMING (default: false) (since 2.5): Feature that may be enabled to enforce strict compatibility with Bean name introspection, instead of slightly different mechanism Jackson defaults to.
  • Specific difference is that Jackson always lower cases leading upper-case letters, so "getURL()" becomes "url" property; whereas standard Bean naming only lower-cases the first letter if it is NOT followed by another upper-case letter (so "getURL()" would result in "URL" property).

Other

• ALLOW_COERCION_OF_SCALARS (default: true) (since 2.9)
  • Feature that determines whether coercions from secondary representations are allowed for simple non-textual scalar types: numbers and booleans. This includes primitive types and their wrappers, but excludes java.lang.String (always allowed) and date/time types (not allowed)
  • As an example, if enabled, JSON String value "1.25" could be bound to java.lang.double value; but if feature disabled, an exception would occur
• DEFAULT_VIEW_INCLUSION (default: true)
  • Feature that determines whether properties that have no view annotations are included in JSON serialization views (see @com.fasterxml.jackson.annotation.JsonView details on JSON Views).
  • If enabled, non-annotated properties will be included; when disabled, they will be excluded. So this feature changes between "opt-in" (feature disabled) and "opt-out" (feature enabled) modes.
• IGNORE_DUPLICATE_MODULE_REGISTRATIONS (default: true): Feature that determines whether multiple registrations of same module should be ignored or not
  • if enabled, only the first registration call results in module being called, and possible duplicate calls are silently ignored; if disabled, no checking is done and all registration calls are dispatched to module.
• IGNORE_MERGE_FOR_UNMERGEABLE (default: true) (since 2.9)
• USE_BASE_TYPE_AS_DEFAULT_IMPL (default: false) (since 2.10)
• USE_STATIC_TYPING (default: false)
• BLOCK_UNSAFE_POLYMORPHIC_BASE_TYPES (default: false) (since 2.11)
  • Setting that may be enabled to reconfigure default com.fasterxml.jackson.databind.jsontype.PolymorphicTypeValidator used by legacy ObjectMapper.enableDefaultTyping() methods as well as default used for annotation-based polymorphic handling so that it uses com.fasterxml.jackson.databind.jsontype.DefaultBaseTypeLimitingValidator.
  • This will block use of a set of "unsafe" base types such as {@link java.lang.Object} through methods that do not require passing of explicit com.fasterxml.jackson.databind.jsontype.PolymorphicTypeValidator.
  • It is still possible to override actual validator used; this only affects default settings.
  • Enabling of this setting is strongly recommended for security reasons
  • Feature is disabled by default in 2.x for backwards compatibility reasons: but enabled behavior will become default in 3.0.