Marker annotation that can be used to define a non-static method as a "setter" or "getter" for a logical property accessor (depending on its signature), or a non-static Object field to be used (serialized, deserialized) as a logical property (to assign value or get value from)

Value ("") indicates that the name of field (or, derived name of an accessor method (setter / getter)) is to be used as the property name without any modifications; a non-empty value can be used to specify a different name. Property name refers to the name used externally, as the property name in JSON objects (as opposed to internal name of field in Java Object).

Note

annotation with non-empty Value can NOT be used if declaring multiple Java fields in a single declaration like:

 public class POJO {
    \@JsonProperty("a")
    public int a, b, c;

since it would associate same annotation for all fields, leading to name collision.

Starting with Jackson 2.6 this annotation may also be used to change serialization of Enum like so:

public enum MyEnum {
    @JsonProperty("theFirstValue") THE_FIRST_VALUE,
    @JsonProperty("another_value") ANOTHER_VALUE;
}

as an alternative to using JsonValue annotation.

Starting with Jackson 2.12 it is also possible to specify namespace of property: this property is only used by certain format backends (most notably XML).

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	JsonProperty.Access Various options for `access` property, specifying how property may be accessed during serialization ("read") and deserialization ("write") (note that the direction of read and write is from perspective of the property, not from external data format: this may be confusing in some contexts).

Field Summary

Modifier and Type	Field and Description
public static final int	INDEX_UNKNOWN Marker value used to indicate that no index has been specified.
public static final String	USE_DEFAULT_NAME Special value that indicates that handlers should use the default name (derived from method or field name) for property.

Method Summary

Modifier and Type	Method and Description
public JsonProperty.Access	access() Optional property that may be used to change the way visibility of accessors (getter, field-as-getter) and mutators (constructor parameter, setter, field-as-setter) is determined, either so that otherwise non-visible accessors (like private getters) may be used; or that otherwise visible accessors are ignored.
public String	defaultValue() Property that may be used to document expected default value for the property: most often used as source information for generating schemas (like JSON Schema or protobuf/thrift schema), or documentation.
public int	index() Property that indicates numerical index of this property (relative to other properties specified for the Object).
public String	namespace() Optional namespace to use with data formats that support such concept (specifically XML); if so, used with `value` to construct fully-qualified name.
public boolean	required() Property that indicates whether a value (which may be explicit null) is expected for property during deserialization or not.
public String	value() Defines name of the logical property, i.e. JSON object field name to use for the property.

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Field Detail

INDEX_UNKNOWN	back to summary
public static final int INDEX_UNKNOWN Marker value used to indicate that no index has been specified. Used as the default value as annotations do not allow "missing" values. Since 2.4

INDEX_UNKNOWN

back to summary

public static final int INDEX_UNKNOWN

Marker value used to indicate that no index has been specified. Used as the default value as annotations do not allow "missing" values.

Since: 2.4

USE_DEFAULT_NAME	back to summary
public static final String USE_DEFAULT_NAME Special value that indicates that handlers should use the default name (derived from method or field name) for property. Since 2.1

USE_DEFAULT_NAME

back to summary

public static final String USE_DEFAULT_NAME

Special value that indicates that handlers should use the default name (derived from method or field name) for property.

Since: 2.1

Method Detail

access back to summary

access	back to summary
public JsonProperty.Access access() Optional property that may be used to change the way visibility of accessors (getter, field-as-getter) and mutators (constructor parameter, setter, field-as-setter) is determined, either so that otherwise non-visible accessors (like private getters) may be used; or that otherwise visible accessors are ignored. Default value os `Access#AUTO` which means that access is determined solely based on visibility and other annotations. Since 2.6

public JsonProperty.Access access()

Optional property that may be used to change the way visibility of accessors (getter, field-as-getter) and mutators (constructor parameter, setter, field-as-setter) is determined, either so that otherwise non-visible accessors (like private getters) may be used; or that otherwise visible accessors are ignored.

Default value os Access#AUTO which means that access is determined solely based on visibility and other annotations.

Since: 2.6

defaultValue back to summary

defaultValue	back to summary
public String defaultValue() Property that may be used to document expected default value for the property: most often used as source information for generating schemas (like JSON Schema or protobuf/thrift schema), or documentation. It may also be used by Jackson extension modules; core `jackson-databind` does not have any automated handling beyond simply exposing this value through bean property introspection. It is possible that in future this annotation could be used for value defaulting, and especially for default values of Creator properties, since they support `required()` in 2.6 and above. Since 2.5

public String defaultValue()

Property that may be used to document expected default value for the property: most often used as source information for generating schemas (like JSON Schema or protobuf/thrift schema), or documentation. It may also be used by Jackson extension modules; core `jackson-databind` does not have any automated handling beyond simply exposing this value through bean property introspection.

It is possible that in future this annotation could be used for value defaulting, and especially for default values of Creator properties, since they support required() in 2.6 and above.

Since: 2.5

index	back to summary
public int index() Property that indicates numerical index of this property (relative to other properties specified for the Object). This index is typically used by binary formats, but may also be useful for schema languages and other tools. Since 2.4

index

back to summary

public int index()

Property that indicates numerical index of this property (relative to other properties specified for the Object). This index is typically used by binary formats, but may also be useful for schema languages and other tools.

Since: 2.4

namespace back to summary

namespace	back to summary
public String namespace() Optional namespace to use with data formats that support such concept (specifically XML); if so, used with `value` to construct fully-qualified name. Since 2.12

public String namespace()

Optional namespace to use with data formats that support such concept (specifically XML); if so, used with value to construct fully-qualified name.

Since: 2.12

required back to summary

required	back to summary
public boolean required() Property that indicates whether a value (which may be explicit null) is expected for property during deserialization or not. If expected, `BeanDeserialized` should indicate this as a validity problem (usually by throwing an exception, but this may be sent via problem handlers that can try to rectify the problem, for example, by supplying a default value). Note that as of 2.6, this property is only used for Creator Properties, to ensure existence of property value in JSON: for other properties (ones injected using a setter or mutable field), no validation is performed. Support for those cases may be added in the future. State of this property is exposed via introspection, and its value is typically used by Schema generators, such as one for JSON Schema. Also note that the required value must come directly from the input source (e.g., JSON) and not from secondary sources, such as defaulting logic or absent value providers. If secondary sources are expected to supply the value, this property should be set to `false`. This is important because validation of `required` properties occurs before the application of secondary sources. Since 2.0

public boolean required()

Property that indicates whether a value (which may be explicit null) is expected for property during deserialization or not. If expected, BeanDeserialized should indicate this as a validity problem (usually by throwing an exception, but this may be sent via problem handlers that can try to rectify the problem, for example, by supplying a default value).

Note that as of 2.6, this property is only used for Creator Properties, to ensure existence of property value in JSON: for other properties (ones injected using a setter or mutable field), no validation is performed. Support for those cases may be added in the future. State of this property is exposed via introspection, and its value is typically used by Schema generators, such as one for JSON Schema.

Also note that the required value must come directly from the input source (e.g., JSON) and not from secondary sources, such as defaulting logic or absent value providers. If secondary sources are expected to supply the value, this property should be set to false. This is important because validation of required properties occurs before the application of secondary sources.

Since: 2.0

value	back to summary
public String value() Defines name of the logical property, i.e. JSON object field name to use for the property. If value is empty String (which is the default), will try to use name of the field that is annotated. Note that there is no default name available for constructor arguments, meaning that Empty String is not a valid value for constructor arguments.

com.fasterxml.jackson.annotation back to summary

public final Enum JsonProperty.Access

Class Inheritance

extends Enum<JsonProperty.Access>

java.lang.Object
java.lang.Enum
com.fasterxml.jackson.annotation.JsonProperty.Access

Various options for access property, specifying how property may be accessed during serialization ("read") and deserialization ("write") (note that the direction of read and write is from perspective of the property, not from external data format: this may be confusing in some contexts).

Note that while this annotation modifies access to annotated property, its effects may be further overridden by JsonIgnore property: if both annotations are present on an accessors, JsonIgnore has precedence over this property. This annotation property is, however, preferred over use of "split" JsonIgnore/JsonProperty combination.

Since: 2.6

Field Summary

Modifier and Type	Field and Description
public static final JsonProperty.Access	AUTO Access setting which means that visibility rules are to be used to automatically determine read- and/or write-access of this property.
public static final JsonProperty.Access	READ_ONLY Access setting that means that the property may only be read for serialization (value accessed via "getter" Method, or read from Field) but not written (set) during deserialization.
public static final JsonProperty.Access	READ_WRITE Access setting that means that the property will be accessed for both serialization (writing out values as external representation) and deserialization (reading values from external representation), regardless of visibility rules.
public static final JsonProperty.Access	WRITE_ONLY Access setting that means that the property may only be written (set) as part of deserialization (using "setter" method, or assigning to Field, or passed as Creator argument) but will not be read (get) for serialization, that is, the value of the property is not included in serialization.

Constructor Summary

Access	Constructor and Description
private	Access()

Method Summary

Modifier and Type	Method and Description
public static JsonProperty.Access	valueOf(String name)
public static JsonProperty.Access[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

AUTO	back to summary
public static final JsonProperty.Access AUTO Access setting which means that visibility rules are to be used to automatically determine read- and/or write-access of this property.

READ_ONLY	back to summary
public static final JsonProperty.Access READ_ONLY Access setting that means that the property may only be read for serialization (value accessed via "getter" Method, or read from Field) but not written (set) during deserialization. Put another way, this would reflect "read-only POJO", in which value contained may be read but not written/set.

READ_WRITE	back to summary
public static final JsonProperty.Access READ_WRITE Access setting that means that the property will be accessed for both serialization (writing out values as external representation) and deserialization (reading values from external representation), regardless of visibility rules.

WRITE_ONLY	back to summary
public static final JsonProperty.Access WRITE_ONLY Access setting that means that the property may only be written (set) as part of deserialization (using "setter" method, or assigning to Field, or passed as Creator argument) but will not be read (get) for serialization, that is, the value of the property is not included in serialization.

Constructor Detail

Access	back to summary
private Access()

Method Detail

valueOf	back to summary
public static JsonProperty.Access valueOf(String name)

values	back to summary
public static JsonProperty.Access[] values()

public @Interface JsonProperty

Nested and Inner Type Summary

Field Summary

Method Summary

Field Detail

Method Detail

public final Enum JsonProperty.Access

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail