com.fasterxml.jackson.annotation

Annotation Type JsonProperty


  • @Target(value={ANNOTATION_TYPE,FIELD,METHOD,PARAMETER})
 @Retention(value=RUNTIME)
public @interface JsonProperty
    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.
    NOTE: for Enums, empty String is a valid value (and missing value is taken as empty String), unlike for regular properties, and does NOT mean "use default Enum name". (handling fixed in Jackson 2.19)

    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).

    • Field Summary

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

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element and Description
      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.
      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.
      int index
      Property that indicates numerical index of this property (relative to other properties specified for the Object).
      OptBoolean isRequired
      Property that MAY indicate whether a value (which may be explicit null) is required for a property during deserialization or not.
      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.
      boolean required
      Property similar to isRequired(), but one that only allows two values (true and false), defaulting to false.
      String value
      Defines name of the logical property, i.e.

    • Field Detail

      • USE_DEFAULT_NAME

        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

      • INDEX_UNKNOWN

        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

    • Element Detail

      • value

        public abstract 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.
        Default:
        ""

      • namespace

        public abstract 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
        Default:
        ""

      • required

        public abstract boolean required
        Property similar to isRequired(), but one that only allows two values (true and false), defaulting to false. It also has lower precedence than isRequired() in cases where both are specified.
        Since:
        2.0
        Default:
        false

      • isRequired

        public abstract OptBoolean isRequired
        Property that MAY indicate whether a value (which may be explicit null) is required for a property during deserialization or not. If specified as required ({code OptBoolean.TRUE}), deserialization should indicate a validity problem if no value is present in incoming content(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). If marked as not required ({code OptBoolean.FALSE}), no checking for value existence should be done. If not specified ({code OptBoolean.DEFAULT}), checking depends on higher level settings (some modules may specify default "required-ness" for certain kinds of properties).

        Note that as of 2.19, possible validation is only done 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.

        NOTE: as of Jackson 2.19, the older property, required(), may still be used, but will have lower precedence than this annotation -- basically it is only considered if this property has value OptBoolean.DEFAULT.

        Since:
        2.19
        Default:
        com.fasterxml.jackson.annotation.OptBoolean.DEFAULT

      • index

        public abstract 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
        Default:
        -1

      • defaultValue

        public abstract 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
        Default:
        ""

      • access

        public abstract 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 JsonProperty.Access.AUTO which means that access is determined solely based on visibility and other annotations.

        Since:
        2.6
        Default:
        com.fasterxml.jackson.annotation.JsonProperty.Access.AUTO

Copyright © 2008–2025 FasterXML. All rights reserved.