Jackson Core (Data-Binding) Annotations
Important note: Jackson 1.x and 2.x annotations live in different Java and Maven packages: see Jackson 2.0 for full explanation:
1.x annotations are in Java package org.codehaus.jackson.annotate, in Jackson core jar
2.x annotations are in Java package com.fasterxml.jackson.annotation, in "jackson-databind" jar.
Annotations contained are mostly same, except where otherwise denoted (some only added in 2.0; others deprecated in 1.x, removed from 2.0)
Annotation class: meta annotations
@JacksonAnnotation (annotation): marker annotation added to all annotation types Jackson provides. With 1.x, only ones marked with this are aggregated; with 2.x this is no longer necessary
Annotation class: general
@JsonAutoDetect (class): which kinds of methods (setters, getters, creators) can be auto-detected, in addition to explicit marking using annotations
@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.
Note: Jackson 2.0+ added "prefix" and "suffix" properties, which can be used to add name prefix and/or suffix, useful for logical grouping of related properties.
- Identifier can be either virtual (present in JSON, but not part of POJO) or explicit (set as a property, written from property)
- Use any property name; but always written as property (unlike type id): defined using "property"
- Have different scopes (to allow for ids that are only unique within scope ("scope" property)
- Identifier generator (for virtual ids) can be one of pre-defined ones (simple int sequence, UUID, property-based), or fully custom one: specified with "generator"
(Jackson 2.1+) @JsonNaming (included in 'jackson-databind', NOT in 'jackson-annotations') allows overriding the default PropertyNamingStrategy on per-class basis; mostly to support sets of external types that use some alternative naming from that of core types of application.
Annotation class: Polymorphic type handling
@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.
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)
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<String>_, and one of annotations above defines real class to be _ArrayList_, actual type used would be _ArrayList<String>_.
It is also possible to use JAXB annotations in addition to or instead of these core annotations.
- Features for: