Package com.fasterxml.jackson.annotation

Annotation Type JsonFormat

@Target({ANNOTATION_TYPE,FIELD,METHOD,PARAMETER,TYPE})
@Retention(RUNTIME)
public @interface JsonFormat

General-purpose annotation used for configuring details of how values of properties are to be serialized and deserialized. Unlike most other Jackson annotations, annotation does not have specific universal interpretation: instead, effects depend on datatype of property being annotated (or more specifically, deserializer and serializer being used).

Annotation can be used on Classes (types) as well, for modified default behavior, possibly overridden by per-property annotations.

Common uses include choosing between alternate representations -- for example, whether Date is to be serialized as number (Java timestamp) or String (such as ISO-8601 compatible time value) -- as well as configuring exact details with pattern() property.

As of Jackson 2.20, known special handling includes:
(NOTE: list is incomplete)

• For Date/Time types:
  • Choice between textual String representation and numeric alternatives (timestamps) with shape property (shape can be JsonFormat.Shape.STRING or JsonFormat.Shape.NUMBER; for some types also JsonFormat.Shape.ARRAY)
  • {code timezone} may be used to override either Jackson default (UTC) or time-date values timezone
  • {code lenient} may be used to enable/disable lenient (vs strict) parsing of values (default being lenient
  • For Date or Calendar: pattern may specify SimpleDateFormat-compatible pattern definitions.
  • For java.time.* types: pattern may specify DateTimeFormatter-compatible pattern definitions.
  • For org.joda.time.* types pattern may specify Joda's org.joda.time.format.DateTimeFormat-compatible pattern definitions.
• Enums: Shapes JsonFormat.Shape.STRING and JsonFormat.Shape.NUMBER can be used to change between numeric (index) and textual (name or toString()); but it is also possible to use JsonFormat.Shape.OBJECT to serialize (but not deserialize) Enums as JSON Objects (as if they were POJOs). NOTE: serialization as JSON Object only works with class annotation; will not work as per-property annotation.
• Collections can be serialized as (and deserialized from) JSON Objects, if JsonFormat.Shape.OBJECT is used. NOTE: can ONLY be used as class annotation; will not work as per-property annotation.
• Number subclasses can use JsonFormat.Shape.STRING to serialize to a string. This is useful to prevent large numeric values from being rounded to their closest double values when deserialized by JSON parsers (for instance JSON.parse() in web browsers) that do not support numbers with more than 53 bits of precision. When serializing Number to a string, it is possible to specify radix, the numeric base used to output the number in.

  They can also be serialized to full objects if JsonFormat.Shape.OBJECT is used. Otherwise, the default behavior of serializing to a scalar number value will be preferred. NOTE: can ONLY be used as class annotation; will not work as per-property annotation.

Since:

2.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	JsonFormat.Feature	Set of features that can be enabled/disabled for property annotated.
static class	JsonFormat.Features	Helper class that encapsulates information equivalent to Boolean valued EnumMap.
static enum	JsonFormat.Shape	Value enumeration used for indicating preferred Shape; translates loosely to JSON types, with some extra values to indicate less precise choices (i.e.
static class	JsonFormat.Value	Helper class used to contain information from a single JsonFormat annotation.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
OptBoolean	lenient	Property that indicates whether "lenient" handling should be enabled or disabled.
String	locale	Locale to use for serialization (if needed).
String	pattern	Datatype-specific additional piece of configuration that may be used to further refine formatting aspects.
int	radix	Property that indicates the numeric base used to output Number properties when JsonFormat.Shape.STRING is specified.
JsonFormat.Shape	shape	Structure to use for serialization: definition of mapping depends on datatype, but usually has straight-forward counterpart in data format (JSON).
String	timezone	TimeZone to use for serialization (if needed).
JsonFormat.Feature[]	with	Set of JsonFormat.Features to explicitly enable with respect to handling of annotated property.
JsonFormat.Feature[]	without	Set of JsonFormat.Features to explicitly disable with respect to handling of annotated property.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_LOCALE	Value that indicates that default Locale (from deserialization or serialization context) should be used: annotation does not define value to use.
static final int	DEFAULT_RADIX	This is a marker signaling that a configured default radix should be used, which typically means 10, when serializing Number properties with JsonFormat.Shape.STRING.
static final String	DEFAULT_TIMEZONE	Value that indicates that default TimeZone (from deserialization or serialization context) should be used: annotation does not define value to use.

Field Details

DEFAULT_LOCALE

static final String DEFAULT_LOCALE

Value that indicates that default Locale (from deserialization or serialization context) should be used: annotation does not define value to use.

See Also:

• Constant Field Values

DEFAULT_TIMEZONE

static final String DEFAULT_TIMEZONE

Value that indicates that default TimeZone (from deserialization or serialization context) should be used: annotation does not define value to use.

NOTE: default here does NOT mean JVM defaults but Jackson databindings default, usually UTC, but may be changed on ObjectMapper.

See Also:

• Constant Field Values

DEFAULT_RADIX

static final int DEFAULT_RADIX

This is a marker signaling that a configured default radix should be used, which typically means 10, when serializing Number properties with JsonFormat.Shape.STRING.

Since:

2.21

See Also:

• Constant Field Values

Element Details

pattern

String pattern

Datatype-specific additional piece of configuration that may be used to further refine formatting aspects. This may, for example, determine low-level format String used for Date serialization; however, exact use is determined by specific JsonSerializer (2.x) / ValueSerializer (3.x)

Default:

""

shape

JsonFormat.Shape shape

Structure to use for serialization: definition of mapping depends on datatype, but usually has straight-forward counterpart in data format (JSON). Note that commonly only a subset of shapes is available; and if 'invalid' value is chosen, defaults are usually used.

Default:

ANY

locale

String locale

Locale to use for serialization (if needed). Special value of DEFAULT_LOCALE can be used to mean "just use the default", where default is specified by the serialization context, which in turn defaults to system defaults (Locale.getDefault()) unless explicitly set to another locale.

Default:

"##default"

timezone

String timezone

TimeZone to use for serialization (if needed). Special value of DEFAULT_TIMEZONE can be used to mean "just use the default", where default is specified by the serialization context, which in turn defaults to system default (UTC) unless explicitly set to another timezone.

Default:

"##default"

lenient

OptBoolean lenient

Property that indicates whether "lenient" handling should be enabled or disabled. This is relevant mostly for deserialization of some textual datatypes, especially date/time types.

Note that underlying default setting depends on datatype (or more precisely deserializer for it): for most date/time types, default is for leniency to be enabled.

Since:

2.9

Default:

DEFAULT

radix

int radix

Property that indicates the numeric base used to output Number properties when JsonFormat.Shape.STRING is specified. For example, if 2 is used, then the output will be a binary representation of a number as a string, and with 16, the number will be outputted in the hexadecimal form.

Since:

2.21

Default:

-1

with

JsonFormat.Feature[] with

Set of JsonFormat.Features to explicitly enable with respect to handling of annotated property. This will have precedence over possible global configuration.

Since:

2.6

Default:

{}

without

JsonFormat.Feature[] without

Set of JsonFormat.Features to explicitly disable with respect to handling of annotated property. This will have precedence over possible global configuration.

Since:

2.6

Default:

{}