Guide to @JsonFormat in Jackson

1. Overview

In this tutorial, we’ll see how to use @JsonFormat in Jackson.

@JsonFormat is a Jackson annotation that allows us to configure how values of properties are serialized or deserialized. For example, we can specify how to format Date and Calendar values according to a SimpleDateFormat format.

2. Maven Dependency

@JsonFormat is defined in the jackson-databind package, so we need the following Maven Dependency:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.17.2</version>
</dependency>

3. Getting Started

3.1. Using the Default Format

We’ll start by demonstrating the concepts of using the @JsonFormat annotation with a class representing a user.

Since we want to explain the details of the annotation, the User object will be created on request (and not stored or loaded from a database) and serialized to JSON:

public class User {
    private String firstName;
    private String lastName;
    private Date createdDate = new Date();

    // standard constructor, setters and getters
}

Building and running this code example returns the following output:

{"firstName":"John","lastName":"Smith","createdDate":1482047026009}

As we can see, the createdDate field is shown as the number of milliseconds since epoch, which is the default format used for Date fields.

3.2. Using the Annotation on a Getter

We’ll now use @JsonFormat to specify the format to serialize the createdDate field.

Let’s look at the User class updated for this change. We annotate the createdDate field as shown to specify the date format.

The data format used for the pattern argument is specified by SimpleDateFormat:

@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd@HH:mm:ss.SSSZ")
private Date createdDate;

With this change in place, we build the project again and run it.

And this is the output:

{"firstName":"John","lastName":"Smith","createdDate":"2016-12-18@07:53:34.740+0000"}

Here we’ve formatted the createdDate field using the specified SimpleDateFormat format using the @JsonFormat annotation.

The above example demonstrates using the annotation on a field. We can also use it in a getter method (a property).

For instance, we may have a property that is being computed on invocation. We can use the annotation on the getter method in such a case.

Note that we’ve also changed the pattern to return just the date part of the instant:

@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
public Date getCurrentDate() {
    return new Date();
}

And here’s the output:

{ ... , "currentDate":"2016-12-18", ...}

3.3. Specifying the Locale

In addition to specifying the date format, we can also specify the locale for serialization.

Not specifying this parameter results in performing serialization with the default locale:

@JsonFormat(
  shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd@HH:mm:ss.SSSZ", locale = "en_GB")
public Date getCurrentDate() {
    return new Date();
}

3.4. Specifying the Shape

Using @JsonFormat with shape set to JsonFormat.Shape.NUMBER results in the default output for Date types — as the number of milliseconds since the epoch.

The parameter pattern is not applicable to this case and is ignored:

@JsonFormat(shape = JsonFormat.Shape.NUMBER)
public Date getDateNum() {
    return new Date();
}

Let’s look at the output:

{ ..., "dateNum":1482054723876 }

4. Case-Insensitive Deserialization

Sometimes, we receive JSON documents from various sources, and they don’t follow the same letter case rule in property names. For example, one JSON document has “firstname”: “John”, but others may contain “firstName”: “John” or “FIRSTNAME”: “John”.

The default deserializer cannot automatically recognize the property names in different letter cases. Let’s understand the problem quickly through an example.

First, let’s say we have a JSON document as the input:

static final String JSON_STRING = "{\"FIRSTNAME\":\"John\",\"lastname\":\"Smith\",\"cReAtEdDaTe\":\"2016-12-18@07:53:34.740+0000\"}";

As we can see, the three properties “FIRSTNAME”, “lastname”, and “cReAtEdDaTe” follow completely different letter case rules. Now, if we deserialize this JSON document to a User object, UnrecognizedPropertyException will be raised:

assertThatThrownBy(() -> new ObjectMapper().readValue(JSON_STRING, User.class)).isInstanceOf(UnrecognizedPropertyException.class);

As the test above shows, we’ve used Assertj’s exception assertion to verify that the expected exception is thrown.

To solve this kind of problem, we must make our deserializer perform case-insensitive deserialization. So next, let’s explore how to achieve that using the @JsonFormat annotation.

The @JsonFormat annotation allows us to set a set of JsonFormat.Feature values via the with attribute: @JsonFormat(with = JsonFormat.Feature … ).

Furthermore, JsonFormat.Feature is an enum. It has predefined a set of options to specify property serialization or deserialization behaviors.

The ACCEPT_CASE_INSENSITIVE_PROPERTIES feature tells the deserializer to match property names case-insensitively. To use this feature, we can include it in a class-level @JsonFormat annotation.

Next, let’s create a UserIgnoreCase class with this annotation and feature:

@JsonFormat(with = JsonFormat.Feature.ACCEPT_CASE_INSENSITIVE_PROPERTIES)
class UserIgnoreCase {
    private String firstName;
    private String lastName;

    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd@HH:mm:ss.SSSZ")
    private Date createdDate;

    // the rest is the same as the User class
    ...
};

Now, if we deserialize our JSON input to UserIgnoreCase, it works as expected:

UserIgnoreCase result = new ObjectMapper().readValue(JSON_STRING, UserIgnoreCase.class);
SimpleDateFormat fmt = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSzz");
Date expectedDate = fmt.parse("2016-12-18T07:53:34.740+0000");
assertThat(result)
  .isNotNull()
  .returns("John", from(UserIgnoreCase::getFirstName))
  .returns("Smith", from(UserIgnoreCase::getLastName))
  .returns(expectedDate, from(UserIgnoreCase::getCreatedDate));

It’s worth mentioning that we’ve used Assertj’s returns() and from() to assert multiple properties in one single assertion. It’s pretty convenient and makes the code easier to read.

5. Conclusion

To sum up, we use @JsonFormat to control the output format of Date and Calendar types.