JacksonAnnotations

Jackson Core (Data-Binding) Annotations

Here is a brief outline of Jackson annotations that exist as of version 2.3. Version in which an annotation was added is included, if it was after version 2.0.

Applicability indicator like "(class, property)" defines where annotation can be used; pseudo-type of property indicates any of (method, field, constructor parameter).

Class means that annotation can be added to types
property indicates that annotation can be used on fields, methods and constructor parameters

Annotation class: general

@JsonAutoDetect (class): what kinds of methods (setters, getters, creators) can be auto-detected, in addition to explicit marking using annotations
@JsonIgnore (property): annotation used to completely disregard annotated method, regardless of auto-detection or other annotations
@JsonIgnoreProperties (class, property) can be used to indicate that certain properties are to be ignored for serialization and/or deserialization (handling differs a bit depending on which operation is affected):
- String[] value() defines '''logical''' property names to ignore (names derived from getter/setter names, or by explicit annotations)
- boolean ignoreUnknown() defines whether "unknown" JSON properties can be silently ignored during deserialization or not; does not affect serialization.
@JsonProperty (property) can be used to denote:
- Property to serialize (when applied to a "getter" method)
- Property to deserialize (when applied to a "setter" method)
- Field-backed property to serialize and deserialize (when applied to a non-static member field)
- Takes optional property name parameter, omitting the parameter results in property name defaulting to method/field name, so that:
  - Method int size() would be considered a getter for integer property "size"
  - Method void size(int) would be considered a setter for integer property "size"
  - Field String FirstName would be considered accessible String property with name "FirstName" (no name mangling used for field names)
@JsonPropertyDescription (property) can be used to define a human readable description for a logical property.
- Currently only used by JSON Schema module to include description
@JsonUnwrapped (property; i.e method, field) Properties that are marked with this annotation will be "unwrapped", that is, properties that would normally be written as properties of a child JSON Object are instead added as properties of enclosing JSON Object.

Annotation class: Polymorphic type handling

Jackson allows fully configurable Polymorphic Type Handling, using following annotations:

@JsonTypeInfo (class) is the main annotation used to enable polymorphic type handling for a type and its subtypes.
@JsonSubTypes (class) allows enumerating sub-types (classes) of given class: it is used if (and only if) sub-types can not be otherwise detected. This is the case when logical type names are used instead of physical Java class names
@JsonTypeName (class) is used to define logical type name for a class
@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.

Annotation class: Instance dependencies

Cyclic dependencies are tricky things to handle. Jackson offers some annotation-based support for handling them:

@JsonManagedReference and @JsonBackReference can be used to properly handle so-called child/parent references; formerly such reference could handle cyclic dependencies (and error); or require manual handling.

TODO: include @JsonTypeInfo

Annotation class: serialization

@JsonValue (method): used to mark a method thats return value is to be used as serialization for the object; often used to mark String-producing methods (like toString()) to produce JSON primitive value serialization
@JsonSerialize (method, field) can be used to denote:
Explicit serializer to use, with using(JsonSerializer) property
Explicit type to use (instead of actual run time type), with as(JsonSerializer) property (must be compatible with run time type, i.e. super-type)
Which bean properties to include (based on kind of value they have) with include() property: by default all properties are included, but can omit null-valued properties or properties with "default" value (value assigned by default bean constructor)
@JsonPropertyOrder (class) can be used to indicate explicit (but possibly partial) ordering for properties on serialization.
String[] value() defines order for included properties (values contained are '''logical''' property names) affected
In absence of explicit ordering, creator-associated properties are output before other properties; but this has lower precedence than explicit ordering.
boolean alphabetic() (default 'false'): defines whether to order properties alphabetically for output, unless explicit ordering exists
Has lower priority than other settings: creator-associated properties have higher precedence.
@JsonView (method, field) can be used to indicate whether associated property is part of specific [JSON View]](JacksonJsonViews).
Also indicates that associated field/method is to be auto-detected as a property (even if it's not named or have visibility to be otherwise auto-detected)
@JsonFilter (class): indicates which BeanPropertyFilter to use for dynamic filtering of properties of annotated class. In addition, one has to define PropertyFilterProvider for ObjectWriter (either using ObjectMapper.filteredWriter(), or ObjectWriter.withFilters()) that is used to dynamically resolve actual filter in use when serializing.
@JsonIgnoreType (class): indicates that properties with annotated type are never to be serialized; this is useful for ignoring metadata accessors used by proxy types or generated classes.

Jackson 1.x also defined following legacy annotations

@JsonGetter (method): used to mark getter methods, as well as configure "logical" (external) name of the associate property (if it needs to differ from Bean naming convention)

Annotation class: deserialization

@JsonAnySetter (method): used to mark 2-argument (String == key, Object == value) method to call when an unknown property is encountered (instead of throwing an exception)
@JsonCreator (method): used to mark static methods to use for instantiating instances of type that contains method (must have single-argument signature with String/int/double argument). Needed for non-public methods, or ones named something other than valueOf().
@JsonDeserialize (method, field) can be used to denote:
Explicit deserializer to use, with using(JsonDeserializer) property
Explicit types to use with as(JsonSerializer) property (must be compatible with declared type, i.e. subtype)
Similarly keyAs() and contentAs() for specifying key type for Maps, content type for Collections, arrays.
@JacksonInject (method, property, constructor parameter): used to mark properties (as indicated by setters, fields and constructor parameter) for which value can be "injected" (resolved using InjectableValues object ObjectMapper is configured with) during deserialization, before binding data from JSON.

Jackson 1.0 also defined following legacy annotations:

@JsonSetter method: used to mark setter methods needed by deserialization, as well as configure "logical" (external) name of the associated property (if it needs to differ from Bean naming convention)

Regarding type-definining annotations: since annotations can not defined Generic type information, but formal declarations can, the actual type information will be a combination of the two: for example, if formal type is List, and one of annotations above defines real class to be ArrayList, actual type used would be ArrayList.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly