JsonFormat
Date: 2016-12-03

com.fasterxml.jackson.annotation

## Annotation Type JsonFormat

-     @Target(value={ANNOTATION_TYPE,FIELD,METHOD,PARAMETER,TYPE})
      @Retention(value=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 `java.text.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

- - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `java.lang.String` | `locale` `Locale` to use for serialization (if needed).
    `java.lang.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).
    `java.lang.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.

- - ### Element Detail

    - #### pattern

          public abstract java.lang.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

          public abstract 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:
        com.fasterxml.jackson.annotation.JsonFormat.Shape.ANY

    - #### locale

          public abstract java.lang.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

          public abstract java.lang.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 defaults (`TimeZone.getDefault()`) unless explicitly set to another locale.
      Default:
        "##default"

    - #### with

          public abstract 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

          public abstract 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:
        {}