Jackson Top

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:


1. Overview

In this tutorial, we demonstrate how to use @JsonFormat in Jackson.

@JsonFormat is a Jackson annotation that we use to specify how to format fields and/or properties for JSON output.

Specifically, this annotation allows us to 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:


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:


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 = "[email protected]: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":"[email protected]: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:

  shape = JsonFormat.Shape.STRING, pattern = "[email protected]: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. Conclusion

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

The sample code shown above is available over on GitHub.

Jackson bottom

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:

Jackson footer banner
Comments are closed on this article!