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. Unlike most other Jackson annotations, annotation does not have specific universal interpretation: instead, effect depends on datatype of property being annotated (or more specifically, deserializer and serializer being used).

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.6, known special handling includes:

- `Date`: Shape can be `JsonFormat.Shape.STRING` or `JsonFormat.Shape.NUMBER`; pattern may contain `SimpleDateFormat`-compatible pattern definition.
- Can be used on Classes (types) as well, for modified default behavior, possibly overridden by per-property annotation
- `Enum`s: 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) `Enum`s 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.
- `Collection`s 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 be serialized as 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.
`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.Feature`s to explicitly enable with respect to handling of annotated property.
`JsonFormat.Feature[]`
`without`
Set of `JsonFormat.Feature`s 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 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

## 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`

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`

### with

JsonFormat.Feature[] with
Set of `JsonFormat.Feature`s 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.Feature`s to explicitly disable with respect to handling of annotated property. This will have precedence over possible global configuration.

Since:
  2.6

Default:
  `{}`