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.
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: 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.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.
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)
@JsonClass (method, class): used to specify concrete type to deserialize to, instead of declared type (must be same type or subtype)
@JsonContentClass (method): similar to @JsonClass, but used with Map/Collection/array content values
@JsonKeyClass (method, class): similar to @JsonClass, but used with Map key values
@JsonUseDeserializer (method, class): used to specify deserializer to use, instead of locating it based on declared type
NOTE: removed in Jackson 1.5 (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>_.
See also
As of Jackson 1.1, it is also possible to use JAXB annotations in addition to or instead of these core annotations.