Close

Jackson JSON - Using @JsonFormat to format Date and Enum

[Last Updated: Aug 4, 2020]

@JsonFormat is a general purpose annotation which can be used to serialize a particular type into a specific format.

package com.fasterxml.jackson.annotation;
 ...
public @interface JsonFormat{
    ...
    // Datatype-specific configuration to further define formatting aspects. 
    public String pattern() default "";
    
    //Structure to use for serialization
    public Shape shape() default Shape.ANY;
    
    //java.util.Locale to use for serialization (if needed)
    public String locale() default DEFAULT_LOCALE;
    
    //java.util.TimeZone to use for serialization (if needed)
    public String timezone() default DEFAULT_TIMEZONE;
    
    //whether "lenient" handling should be enabled. 
    //This is relevant mostly for deserialization of some textual
    // datatypes, especially date/time types
    public OptBoolean lenient() default OptBoolean.DEFAULT;

    //JsonFormat.Feature to explicitly enable for the annotated property
    public JsonFormat.Feature[] with() default { };

    //JsonFormat.Feature to explicitly disable for the annotated property 
    public JsonFormat.Feature[] without() default { };
   ....
}

This tutorial will show how to serialize Date/Calendar and Java Enum in a desired format.

Formatting Date

By default Date/Calendar are serialized as number (i.e. milliseconds since epoch). To serialize them as string, the attribute @JsonFormat#shape should be assigned to JsonFormat.Shape.STRING along with the attribute @JsonFormat#pattern assigned to a desired SimpleDateFormat-compatible pattern. We can also optionally specify @JsonFormat#timezone or @JsonFormat#locale values. For example

@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss Z", timezone="America/New_York")
    private Date startDate;

Formatting enum

By default enums are serialized by their names. To serialize them by ordinals, we can assign the shape as JsonFormat.Shape.NUMBER. For example:

@JsonFormat(shape = JsonFormat.Shape.NUMBER)
    private Dept dept;

Example

Java Object

public class Employee {
  private String name;
  @JsonFormat(shape = JsonFormat.Shape.STRING)
  private Date dateOfBirth;
  @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss Z", timezone="America/New_York")
  private Date startDate;
  @JsonFormat(shape = JsonFormat.Shape.NUMBER)
  private Dept dept;
    .............
}
public enum Dept {
  Admin, IT, Sales
}

With 'dateOfBirth' we just specify the string shape without any pattern; In that case a default String format will be serialized.

Serializing to JSON

public class ExampleMain {
  public static void main(String[] args) throws IOException {
      Employee employee = new Employee();
      employee.setName("Amy");
      employee.setDateOfBirth(Date.from(ZonedDateTime.now().minusYears(30).toInstant()));
      employee.setStartDate(Date.from(ZonedDateTime.now().minusYears(2).toInstant()));
      employee.setDept(Dept.Sales);

      System.out.println("-- before serialization --");
      System.out.println(employee);

      System.out.println("-- after serialization --");
      ObjectMapper om = new ObjectMapper();
      String jsonString = om.writeValueAsString(employee);
      System.out.println(jsonString);

      System.out.println("-- after deserialization --");
      System.out.println(om.readValue(jsonString, Employee.class));
  }
}
-- before serialization --
Employee{name='Amy', dateOfBirth=Thu Jul 28 20:20:18 CDT 1988, startDate=Thu Jul 28 20:20:18 CDT 2016, dept=Sales}
-- after serialization --
{"name":"Amy","dateOfBirth":"1988-07-29T01:20:18.763+0000","startDate":"2016-07-28 21:20:18 -0400","dept":2}
-- after deserialization --
Employee{name='Amy', dateOfBirth=Thu Jul 28 20:20:18 CDT 1988, startDate=Thu Jul 28 20:20:18 CDT 2016, dept=Sales}

Without @JsonFormat

If we remove all @JsonFormat:

public class Employee {
  private String name;
  private Date dateOfBirth;
  private Date startDate;
  private Dept dept;
    .............
}

In this case output is:

Employee{name='Amy', dateOfBirth=Thu Jul 28 15:51:51 CDT 1988, startDate=Thu Jul 28 15:51:51 CDT 2016, dept=Sales}
-- after serialization --
{"name":"Amy","dateOfBirth":586126311022,"startDate":1469739111026,"dept":"Sales"}
-- after deserialization --
Employee{name='Amy', dateOfBirth=Thu Jul 28 15:51:51 CDT 1988, startDate=Thu Jul 28 15:51:51 CDT 2016, dept=Sales}

Example Project

Dependencies and Technologies Used:

  • jackson-databind 2.9.6: General data-binding functionality for Jackson: works on core streaming API.
  • JDK 10
  • Maven 3.5.4

Using @JsonFormat to format Date and Enum Select All Download
  • jackson-json-format
    • src
      • main
        • java
          • com
            • logicbig
              • example
                • Employee.java

    See Also