JacksonAnnotations - FasterXML Wiki

Jackson Core (Data-Binding) Annotations

Here is a brief outline of Jackson annotations that exist as of version 1.5.

Annotation class: general

@JsonAutoDetect (class): which kinds of methods (setters, getters, creators) can be auto-detected, in addition to explicit marking using annotations
- Starting with Jackson 1.5, this annotation has many more properties to granularly configure Jackson property auto-detection settings.
@JsonIgnore (method/field): annotation used to completely disregard annotated method, regardless of auto-detection or other annotations
(Jackson 1.1+) @JsonProperty (method, field) 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)
(Jackson 1.4+) @JsonIgnoreProperties (class) 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.
(Jackson 1.9+) @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

Starting with version 1.5, 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 (available since version 1.6) can be used to properly handle child/parent references; formerly such reference could handle cyclic dependencies (and error); or require manual handling.

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
(Jackson 1.1+) @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)
(Jackson 1.4+) @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 (from version 1.4 onwards); 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.
(Jackson 1.4+) @JsonView (method, field) can be used to indicate whether associated property is part of specific JSON View.
- As of 1.6, this annotation 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)
(Jackson 1.7+) @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.
(Jackson 1.7+) @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.0 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)
@JsonUseSerializer (method, class): used to specify serializer to use, instead of locating it based on runtime type
- NOTE: removed in Jackson 1.5 (replaced by @JsonSerialize)
@JsonWriteNullProperties (class): used to suppress writing out of properties that have null value

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 excpetion)
(Jackson 1.2+) @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".
(Jackson 1.1+) @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)
(Removed from 1.9) @JsonClass (method, class): used to specify concrete type to deserialize to, instead of declared type (must be same type or subtype) -- replaced by @JsonDeserialize.as
(Removed from 1.9) @JsonContentClass (method): similar to @JsonClass, but used with Map/Collection/array content values -- replaced by @JsonDeserialize.contentAs
(Removed from 1.9) @JsonKeyClass (method, class): similar to @JsonClass, but used with Map key values -- replaced by @JsonDeserialize.keyAs
(Removed from 1.5) @JsonUseDeserializer (method, class): used to specify deserializer to use, instead of locating it based on declared type (replaced by @JsonDeserialize)