Jackson Data-Binding Annotations

In addition to core Jackson annotations, jackson-databind adds a small set of annotations that are tied to types defined in databind package. These are used for more fine-grained definition of handlers.

Serialization (writing JSON)

• @JsonSerialize (method, field) can be used to denote:
  • Explicit serializer (of type JsonSerializer) to use, with following properties:
    • using for value of property itself
    • keyUsing for keys of java.util.Map valued properties
    • contentUsing for contents of structured values (elements of arrays, java.util.Collections, values of java.util.Maps)
    • nullUsing when serializing Java null valued properties (NEW with 2.3)
  • Explicit type to use (instead of actual run time type) with
    • as for property value
    • keyAs for java.util.Map keys
    • contentAs for elements/values of structured types
    • NOTE: type used must be compatible with nominal type (a super type)
  • Whether static or dynamic typing (default: static typing) is to be used: typing property
    • Allowed values are DYNAMIC (for dynamic runtime type), STATIC (to use declared, "nominal" type) or DEFAULT_TYPING to use defaults for ObjectMapper
  • Converter object (of type Converter) to use
    • converter for property value itself, or
    • contentConverter for values of structured types (elements of array, java.util.Collections; values of java.util.Maps)

Deserialization (reading JSON)

• @JsonDeserialize (method, field) can be used to denote:
  • Explicit deserializer to use:
    • using for values (scalars or structured)
    • contentUsing for values of structured types (elements of arrays and java.util.Collections, values of java.util.Maps)
    • keyUsing for keys of java.util.Maps
  • Explicit types to use with
    • as property (must be compatible with declared type, i.e. subtype)
    • Similarly keyAs() and contentAs() for specifying key type for java.util.Maps, content type for Collections, arrays.
  • Builder object (of any type) to use: builder
  • Converter object (of type Converter) to use
    • converter for property value itself, or
    • contentConverter for values of structured types (elements of array, java.util.Collections; values of java.util.Maps)
• @JsonNaming (Class) is used to indicate PropertyNamingStrategy to use for annotated type
  • Note that databind module includes implementation of two alternate naming strategies:
    • PropertyNamingStrategy.LowerCaseWithUnderScoresStrategy: supports "C-style" naming, like first_name (instead of Java "firstName")
    • PropertyNamingStrategy.PascalCaseStrategy: supports names like "FirstName"
• @JsonPOJOBuilder (Class) is used to configure so-called Builder objects; builders can be specified using @JsonDeserialize.builder property
• @JsonValueInstantiator (Class) is used to specify custom ValueInstantiator to use for annotated type
  • Use of ValueInstantiator is an advanced topic.

Polymorphic type handling

Following annotations work together with standard @JsonTypeInfo annotation defined by core annotations package.

• @JsonTypeResolver (class) can be used to plug in a custom type information handler, to replace default one (for specific class)
• @JsonTypeIdResolver (class) can be used to replace standard type id converter (type to/from JSON String) with a custom version; for example, to create more convenient handler for using logical type names.

See also

It is also possible to use JAXB annotations in addition to or instead of these core annotations.