Top Description Inners Methods
com.fasterxml.jackson.annotation

public @Interface JsonTypeInfo

extends Annotation
Annotations
@Target:ANNOTATION_TYPE, TYPE, FIELD, METHOD, PARAMETER
@Retention:RUNTIME
@JacksonAnnotation
Imports
java.lang.annotation.ElementType, .Retention, .RetentionPolicy, .Target

Annotation used for configuring details of if and how type information is used with JSON serialization and deserialization, to preserve information about actual class of Object instances. This is necessarily for polymorphic types, and may also be needed to link abstract declared types and matching concrete implementation.

Some examples of typical annotations:

  // Include Java class name ("com.myempl.ImplClass") as JSON property "class"
  @JsonTypeInfo(use=Id.CLASS, include=As.PROPERTY, property="class")

  // Include logical type name (defined in impl classes) as wrapper; 2 annotations
  @JsonTypeInfo(use=Id.NAME, include=As.WRAPPER_OBJECT)
  @JsonSubTypes({com.myemp.Impl1.class, com.myempl.Impl2.class})
Alternatively you can also define fully customized type handling by using @JsonTypeResolver annotation (from databind package).

This annotation can be used both for types (classes) and properties. If both exist, annotation on property has precedence, as it is considered more specific.

When used for properties (fields, methods), this annotation applies to values: so when applied to structure types (like java.util.Collection, java.util.Map, arrays), will apply to contained values, not the container; for non-structured types there is no difference. This is identical to how JAXB handles type information annotations; and is chosen since it is the dominant use case. There is no per-property way to force type information to be included for type of container (structured type); for container types one has to use annotation for type declaration.

Note on visibility of type identifier: by default, deserialization (use during reading of JSON) of type identifier is completely handled by Jackson, and is not passed to deserializers. However, if so desired, it is possible to define property visible = true in which case property will be passed as-is to deserializers (and set via setter or field) on deserialization.

On serialization side, Jackson will generate type id by itself, except if there is a property with name that matches property(), in which case value of that property is used instead.

Note

use of type id of "class name" with very general base type (such as java.lang.Object or java.io.Serializable) can potentially open up security holes if deserializing content generated by untrusted sources. If content can not be trusted, it is necessary to either use "type name" as type id, or to limit possible types using other means.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
JsonTypeInfo.As

Definition of standard type inclusion mechanisms for type metadata.

public static enum
JsonTypeInfo.Id

Definition of different type identifiers that can be included in JSON during serialization, and used for deserialization.

public abstract static class
JsonTypeInfo.None

Deprecated Since 2.5, use any Annotation type (such as JsonTypeInfo), if such behavior is needed; this is rarely necessary.
This marker class that is only to be used with defaultImpl annotation property, to indicate that there is no default implementation specified.
public static class

Method Summary

Modifier and TypeMethod and Description
public Class<?>
defaultImpl()

Optional property that can be used to specify default implementation class to use for deserialization if type identifier is either not present, or can not be mapped to a registered type (which can occur for ids, but not when specifying explicit class to use).

public JsonTypeInfo.As
include()

Specifies mechanism to use for including type metadata (if any; for Id#NONE nothing is included); used when serializing, and expected when deserializing.

public String
property()

Property names used when type inclusion method (As#PROPERTY) is used (or possibly when using type metadata of type Id#CUSTOM).

public OptBoolean
requireTypeIdForSubtypes()

Specifies whether the type ID should be strictly required during polymorphic deserialization of its subtypes.

public JsonTypeInfo.Id
use()

Specifies kind of type metadata to use when serializing type information for instances of annotated type and its subtypes; as well as what is expected during deserialization.

public boolean
visible()

Property that defines whether type identifier value will be passed as part of JSON stream to deserializer (true), or handled and removed by TypeDeserializer (false).

Inherited from java.lang.annotation.Annotation:
annotationTypeequalshashCodetoString

Method Detail

defaultImplback to summary
public Class<?> defaultImpl()

Optional property that can be used to specify default implementation class to use for deserialization if type identifier is either not present, or can not be mapped to a registered type (which can occur for ids, but not when specifying explicit class to use). Property has no effect on choice of type id used for serialization; it is only used in deciding what to do for otherwise unmappable cases.

Note that while this property allows specification of the default implementation to use, it does not help with structural issues that may arise if type information is missing. This means that most often this is used with type-name -based resolution, to cover cases where new subtypes are added, but base type is not changed to reference new subtypes.

There are certain special values that indicate alternate behavior:

  • java.lang.Void means that objects with unmappable (or missing) type are to be mapped to null references. For backwards compatibility (2.5 and below), value of com.fasterxml.jackson.databind.annotation.NoClass is also allowed for such usage.
  • Placeholder value of JsonTypeInfo (that is, this annotation type itself} means "there is no default implementation" (in which case an error results from unmappable type). For backwards compatibility with earlier versions (2.5 and below), value of JsonTypeInfo.None may also be used.
includeback to summary
public JsonTypeInfo.As include()

Specifies mechanism to use for including type metadata (if any; for Id#NONE nothing is included); used when serializing, and expected when deserializing.

Note that for type metadata type of Id#CUSTOM, this setting may or may not have any effect.

propertyback to summary
public String property()

Property names used when type inclusion method (As#PROPERTY) is used (or possibly when using type metadata of type Id#CUSTOM). If POJO itself has a property with same name, value of property will be set with type id metadata: if no such property exists, type id is only used for determining actual type.

Default property name used if this property is not explicitly defined (or is set to empty String) is based on type metadata type (use) used.

requireTypeIdForSubtypesback to summary
public OptBoolean requireTypeIdForSubtypes()

Specifies whether the type ID should be strictly required during polymorphic deserialization of its subtypes.

If set to OptBoolean#TRUE, an InvalidTypeIdException will be thrown if no type information is provided. If set to OptBoolean#FALSE, deserialization may proceed without type information if the subtype is a legitimate target (non-abstract). If set to OptBoolean#DEFAULT, the global configuration of MapperFeature#REQUIRE_TYPE_ID_FOR_SUBTYPES is used for type ID handling.

Note

This setting is specific to this type and will always override the global configuration of MapperFeature.REQUIRE_TYPE_ID_FOR_SUBTYPES.

Since
2.16
useback to summary
public JsonTypeInfo.Id use()

Specifies kind of type metadata to use when serializing type information for instances of annotated type and its subtypes; as well as what is expected during deserialization.

visibleback to summary
public boolean visible()

Property that defines whether type identifier value will be passed as part of JSON stream to deserializer (true), or handled and removed by TypeDeserializer (false). Property has no effect on serialization.

Default value is false, meaning that Jackson handles and removes the type identifier from JSON content that is passed to JsonDeserializer.

Since
2.0
com.fasterxml.jackson.annotation back to summary

public final Enum JsonTypeInfo.As

extends Enum<JsonTypeInfo.As>
Class Inheritance

Definition of standard type inclusion mechanisms for type metadata. Used for standard metadata types, except for Id#NONE. May or may not be used for custom types (Id#CUSTOM).

Field Summary

Modifier and TypeField and Description
public static final JsonTypeInfo.As
EXISTING_PROPERTY

Inclusion mechanism similar to PROPERTY with respect to deserialization; but one that is produced by a "regular" accessible property during serialization.

public static final JsonTypeInfo.As
EXTERNAL_PROPERTY

Inclusion mechanism similar to PROPERTY, except that property is included one-level higher in hierarchy, i.e. as sibling property at same level as JSON Object to type.

public static final JsonTypeInfo.As
PROPERTY

Inclusion mechanism that uses a single configurable property, included along with actual data (POJO properties) as a separate meta-property.

public static final JsonTypeInfo.As
WRAPPER_ARRAY

Inclusion mechanism that wraps typed JSON value (POJO serialized as JSON) in a 2-element JSON array: first element is the serialized type identifier, and second element the serialized POJO as JSON Object.

public static final JsonTypeInfo.As
WRAPPER_OBJECT

Inclusion mechanism that wraps typed JSON value (POJO serialized as JSON) in a JSON Object that has a single entry, where field name is serialized type identifier, and value is the actual JSON value.

Constructor Summary

AccessConstructor and Description
private
As()

Method Summary

Modifier and TypeMethod and Description
public static JsonTypeInfo.As
public static JsonTypeInfo.As[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

EXISTING_PROPERTYback to summary
public static final JsonTypeInfo.As EXISTING_PROPERTY

Inclusion mechanism similar to PROPERTY with respect to deserialization; but one that is produced by a "regular" accessible property during serialization. This means that TypeSerializer will do nothing, and expects a property with defined name to be output using some other mechanism (like default POJO property serialization, or custom serializer).

Note that this behavior is quite similar to that of using JsonTypeId annotation; except that here TypeSerializer is basically suppressed; whereas with JsonTypeId, output of regular property is suppressed. This mostly matters with respect to output order; this choice is the only way to ensure specific placement of type id during serialization.

Since
2.3 but databind only since 2.5.
EXTERNAL_PROPERTYback to summary
public static final JsonTypeInfo.As EXTERNAL_PROPERTY

Inclusion mechanism similar to PROPERTY, except that property is included one-level higher in hierarchy, i.e. as sibling property at same level as JSON Object to type. Note that this mechanism can only be used for properties, not for types (classes). Trying to use it for classes will result in inclusion strategy of basic PROPERTY instead.

Note also that this mechanism can not be used for container values (arrays, java.util.Collections, java.util.Maps); it only works for scalar and POJO values.

PROPERTYback to summary
public static final JsonTypeInfo.As PROPERTY

Inclusion mechanism that uses a single configurable property, included along with actual data (POJO properties) as a separate meta-property.

Default choice for inclusion.

WRAPPER_ARRAYback to summary
public static final JsonTypeInfo.As WRAPPER_ARRAY

Inclusion mechanism that wraps typed JSON value (POJO serialized as JSON) in a 2-element JSON array: first element is the serialized type identifier, and second element the serialized POJO as JSON Object.

WRAPPER_OBJECTback to summary
public static final JsonTypeInfo.As WRAPPER_OBJECT

Inclusion mechanism that wraps typed JSON value (POJO serialized as JSON) in a JSON Object that has a single entry, where field name is serialized type identifier, and value is the actual JSON value.

Note

can only be used if type information can be serialized as String. This is true for standard type metadata types, but not necessarily for custom types.

Constructor Detail

Asback to summary
private As()

Method Detail

valueOfback to summary
public static JsonTypeInfo.As valueOf(String name)
valuesback to summary
public static JsonTypeInfo.As[] values()
com.fasterxml.jackson.annotation back to summary

public final Enum JsonTypeInfo.Id

extends Enum<JsonTypeInfo.Id>
Class Inheritance

Definition of different type identifiers that can be included in JSON during serialization, and used for deserialization.

Field Summary

Modifier and TypeField and Description
private final String
public static final JsonTypeInfo.Id
CLASS

Means that fully-qualified Java class name is used as the type identifier.

public static final JsonTypeInfo.Id
CUSTOM

Means that typing mechanism uses customized handling, with possibly custom configuration.

public static final JsonTypeInfo.Id
DEDUCTION

Means that no serialized typing-property is used.

public static final JsonTypeInfo.Id
MINIMAL_CLASS

Means that Java class name with minimal path is used as the type identifier.

public static final JsonTypeInfo.Id
NAME

Means that logical type name is used as type information; name will then need to be separately resolved to actual concrete type (Class).

public static final JsonTypeInfo.Id
NONE

This means that no explicit type metadata is included, and typing is purely done using contextual information possibly augmented with other annotations.

public static final JsonTypeInfo.Id
SIMPLE_NAME

Means that the simple name of the Java class, equivalent to the value returned by Class#getSimpleName(), is used as the default type identifier, unless explicit name is specified by annotation JsonTypeName.

Constructor Summary

AccessConstructor and Description
private
Id(String defProp)

Method Summary

Modifier and TypeMethod and Description
public String
public static JsonTypeInfo.Id
public static JsonTypeInfo.Id[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

_defaultPropertyNameback to summary
private final String _defaultPropertyName
CLASSback to summary
public static final JsonTypeInfo.Id CLASS

Means that fully-qualified Java class name is used as the type identifier.

CUSTOMback to summary
public static final JsonTypeInfo.Id CUSTOM

Means that typing mechanism uses customized handling, with possibly custom configuration. This means that semantics of other properties is not defined by Jackson package, but by the custom implementation.

DEDUCTIONback to summary
public static final JsonTypeInfo.Id DEDUCTION

Means that no serialized typing-property is used. Types are deduced based on the Object properties available in the input. Deduction is limited to the names of properties (not their values or, consequently, any nested values). Exceptions will be thrown if not enough unique information is present to select a single sub-type.
If deduction is being used annotation properties visible, property and include are ignored.

Note

being Property-based, will essentially only work for POJOs and not for other kinds of types (like arrays, java.util.Collections, java.util.Maps, scalars, etc); similarly, serialized form must be (JSON) Object.

On serialization, no type Id is written, and only regular properties are included.

Since
2.12
MINIMAL_CLASSback to summary
public static final JsonTypeInfo.Id MINIMAL_CLASS

Means that Java class name with minimal path is used as the type identifier. Minimal means that only the class name, and that part of preceding Java package name is included that is needed to construct fully-qualified name given fully-qualified name of the declared supertype; additionally a single leading dot ('.') must be used to indicate that partial class name is used. For example, for supertype "com.foobar.Base", and concrete type "com.foo.Impl", only ".Impl" would be included; and for "com.foo.impl.Impl2" only ".impl.Impl2" would be included

Note

leading dot ('.') MUST be used to denote partial (minimal) name; if it is missing, value is assumed to be fully-qualified name. Fully-qualified name is used in cases where subtypes are not in same package (or sub-package thereof) as base class.

If all related classes are in the same Java package, this option can reduce amount of type information overhead, especially for small types. However, please note that using this alternative is inherently risky since it assumes that the supertype can be reliably detected. Given that it is based on declared type (since ultimate supertype, java.lang.Object would not be very useful reference point), this may not always work as expected.

NAMEback to summary
public static final JsonTypeInfo.Id NAME

Means that logical type name is used as type information; name will then need to be separately resolved to actual concrete type (Class).

NONEback to summary
public static final JsonTypeInfo.Id NONE

This means that no explicit type metadata is included, and typing is purely done using contextual information possibly augmented with other annotations.

SIMPLE_NAMEback to summary
public static final JsonTypeInfo.Id SIMPLE_NAME

Means that the simple name of the Java class, equivalent to the value returned by Class#getSimpleName(), is used as the default type identifier, unless explicit name is specified by annotation JsonTypeName.
For instance:

  • For a class "com.example.MyClass", only "MyClass" is used.
  • For an inner class "com.example.MyClass$Inner", only "Inner" is used.

Note

This approach reduces verbosity but requires the simple names to be unique to avoid conflicts. If multiple classes share the same simple name, the last declared one will be used. This approach should be used with careful consideration of your type hierarchy.

Since
2.16

Constructor Detail

Idback to summary
private Id(String defProp)

Method Detail

getDefaultPropertyNameback to summary
public String getDefaultPropertyName()
valueOfback to summary
public static JsonTypeInfo.Id valueOf(String name)
valuesback to summary
public static JsonTypeInfo.Id[] values()
com.fasterxml.jackson.annotation back to summary

public abstract Class JsonTypeInfo.None

extends Object
Class Inheritance
Annotations
@Deprecated

Deprecated

Since 2.5, use any Annotation type (such as JsonTypeInfo), if such behavior is needed; this is rarely necessary.

This marker class that is only to be used with defaultImpl annotation property, to indicate that there is no default implementation specified.

Constructor Summary

AccessConstructor and Description
public
None()

Method Summary

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Noneback to summary
public None()
com.fasterxml.jackson.annotation back to summary

public Class JsonTypeInfo.Value

extends Object
implements JacksonAnnotationValue<JsonTypeInfo>, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, com.fasterxml.jackson.annotation.JacksonAnnotationValue

Field Summary

Modifier and TypeField and Description
protected final Class<?>
protected final JsonTypeInfo.Id
protected final boolean
protected final JsonTypeInfo.As
protected final String
protected final Boolean
protected static final JsonTypeInfo.Value
private static final long

Constructor Summary

AccessConstructor and Description
protected
Value(JsonTypeInfo.Id idType, JsonTypeInfo.As inclusionType, String propertyName, Class<?> defaultImpl, boolean idVisible, Boolean requireTypeIdForSubtypes)

Method Summary

Modifier and TypeMethod and Description
private static <T> boolean
_equal(T value1, T value2)

private static boolean
public static JsonTypeInfo.Value
construct(JsonTypeInfo.Id idType, JsonTypeInfo.As inclusionType, String propertyName, Class<?> defaultImpl, boolean idVisible, Boolean requireTypeIdForSubtypes)

public boolean
equals(Object
the reference object with which to compare.
o
)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

public static JsonTypeInfo.Value
public Class<?>
public JsonTypeInfo.Id
public boolean
public JsonTypeInfo.As
public String
public Boolean
public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

public static boolean
isEnabled(JsonTypeInfo.Value v)

Static helper method for simple(r) checking of whether there's a Value instance that indicates that polymorphic handling is (to be) enabled.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

public Class<JsonTypeInfo>
valueFor()

Implements com.fasterxml.jackson.annotation.JacksonAnnotationValue.valueFor.

Introspection method that may be used to find actual annotation that may be used as the source for value instance.

public JsonTypeInfo.Value
public JsonTypeInfo.Value
public JsonTypeInfo.Value
withIdVisible(boolean visible)

public JsonTypeInfo.Value
public JsonTypeInfo.Value
public JsonTypeInfo.Value
withRequireTypeIdForSubtypes(Boolean requireTypeIdForSubtypes)

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

_defaultImplback to summary
protected final Class<?> _defaultImpl
_idTypeback to summary
protected final JsonTypeInfo.Id _idType
_idVisibleback to summary
protected final boolean _idVisible
_inclusionTypeback to summary
protected final JsonTypeInfo.As _inclusionType
_propertyNameback to summary
protected final String _propertyName
_requireTypeIdForSubtypesback to summary
protected final Boolean _requireTypeIdForSubtypes
EMPTYback to summary
protected static final JsonTypeInfo.Value EMPTY
serialVersionUIDback to summary
private static final long serialVersionUID

Constructor Detail

Valueback to summary
protected Value(JsonTypeInfo.Id idType, JsonTypeInfo.As inclusionType, String propertyName, Class<?> defaultImpl, boolean idVisible, Boolean requireTypeIdForSubtypes)

Method Detail

_equalback to summary
private static <T> boolean _equal(T value1, T value2)
_equalsback to summary
private static boolean _equals(JsonTypeInfo.Value a, JsonTypeInfo.Value b)
constructback to summary
public static JsonTypeInfo.Value construct(JsonTypeInfo.Id idType, JsonTypeInfo.As inclusionType, String propertyName, Class<?> defaultImpl, boolean idVisible, Boolean requireTypeIdForSubtypes)
equalsback to summary
public boolean equals(Object o)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
o:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
fromback to summary
public static JsonTypeInfo.Value from(JsonTypeInfo src)
getDefaultImplback to summary
public Class<?> getDefaultImpl()
getIdTypeback to summary
public JsonTypeInfo.Id getIdType()
getIdVisibleback to summary
public boolean getIdVisible()
getInclusionTypeback to summary
public JsonTypeInfo.As getInclusionType()
getPropertyNameback to summary
public String getPropertyName()
getRequireTypeIdForSubtypesback to summary
public Boolean getRequireTypeIdForSubtypes()
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override
isEnabledback to summary
public static boolean isEnabled(JsonTypeInfo.Value v)

Static helper method for simple(r) checking of whether there's a Value instance that indicates that polymorphic handling is (to be) enabled.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations
@Override
valueForback to summary
public Class<JsonTypeInfo> valueFor()

Implements com.fasterxml.jackson.annotation.JacksonAnnotationValue.valueFor.

Doc from com.fasterxml.jackson.annotation.JacksonAnnotationValue.valueFor.

Introspection method that may be used to find actual annotation that may be used as the source for value instance.

Returns:Class<JsonTypeInfo>

Annotation class for which instances of this value class are created

Annotations
@Override
withDefaultImplback to summary
public JsonTypeInfo.Value withDefaultImpl(Class<?> impl)
withIdTypeback to summary
public JsonTypeInfo.Value withIdType(JsonTypeInfo.Id idType)
withIdVisibleback to summary
public JsonTypeInfo.Value withIdVisible(boolean visible)
withInclusionTypeback to summary
public JsonTypeInfo.Value withInclusionType(JsonTypeInfo.As inclusionType)
withPropertyNameback to summary
public JsonTypeInfo.Value withPropertyName(String propName)
withRequireTypeIdForSubtypesback to summary
public JsonTypeInfo.Value withRequireTypeIdForSubtypes(Boolean requireTypeIdForSubtypes)