@JsonFormat Jackson Annotation

@JsonFormat annotation is used to format the fields or properties while serializing. It is most commonly used to format the Date/Time properties but has some other uses, which we will discuss in this post.

Attributes of the JsonFormat Annotation

  • lenient
  • locale
  • pattern
  • shape
  • timezone
  • with
  • without

In this post, we are going to look at the below points

Let’s have a look at the above points one by one.

Formatting of Date type field without using the @JsonFormat Annotation

Let us take an Employee class with only three properties – age, name, and joiningDate along with their getters and setters.

Employee.java
import java.util.Date;

public class Employee {

	public String name;
	public int age;
	public Date joiningDate;

    // getters and setters
	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}

	public Date getJoiningDate() {
		return joiningDate;
	}

	public void setJoiningDate(Date joiningDate) {
		this.joiningDate = joiningDate;
	}

	

}

And now, let’s try to serialize the above class’s object.

Codekru.java
import java.util.Date;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;

public class Codekru {

	public static void main(String[] args) throws JsonProcessingException {
		
		Employee emp = new Employee();
		emp.setAge(20);
		emp.setName("Codekru");
		emp.setJoiningDate(new Date());
		
		ObjectMapper mapper = new ObjectMapper();
		System.out.println(mapper.writeValueAsString(emp)); // serializing object

	}
}

If we run the above class, then we will get the below output

{"name":"Codekru","age":20,"joiningDate":1633850092449}

Here, we can see that we got the joiningDate in kind of a long integer value, which represents the time since the epoch. This is the default setting that comes with the Date value. But what if we wanted a specific Date Format like dd/MM/yyyy? Then how can we do that? This is where the @JsonFormat annotation will come into the picture.

Formatting of Date type field with @JsonFormat Annotation

We can also use the JsonFormat annotation at the field level or the getter method. We will use it at the field level, but it is up to you whether you want it at the field or the method level.

Employee.java
import java.util.Date;

import com.fasterxml.jackson.annotation.JsonFormat;
import com.fasterxml.jackson.annotation.JsonFormat.Shape;

public class Employee {

	public String name;
	public int age;

	@JsonFormat(shape = Shape.STRING, pattern = "dd/MM/yyyy")
	public Date joiningDate;

	// getters and setters

}

Now, let’s rerun the Codekru class and analyze its output.

{"name":"Codekru","age":20,"joiningDate":"10/10/2021"}

So, here we can see that joiningDate is printed in a specified format mentioned in the Employee class. The format should be compatible with the SimpleDateFormat.

You may have noted that we have used the shape = Shape.String in the JsonFormat annotation. It is used to know the structure used for the sterilization process. As we have mentioned Shape.String in our example, so it would convert the joiningDate into a corresponding string type value, which is also indicated by the JSON output. And if we have used Shape.Number instead of Shape.String, then it would have printed joiningDate as a numeric value representing the timestamp as shown below.

{"name":"Codekru","age":20,"joiningDate":1633854916341}

Formatting of enum type field without using the @JsonFormat Annotation

Let’s tweak our Employee class a bit and add a new enum named Dept into the class and the corresponding property.

public class Employee {

	enum Dept {
		IT, SECURITY, ADMIN
	}

	public String name;
	public int age;
	public Dept dept;

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}

	public Dept getDept() {
		return dept;
	}

	public void setDept(Dept dept) {
		this.dept = dept;
	}

}

And now, let’s again serialize the Employee class object

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;

import Test.Employee.Dept;

public class Codekru {

	public static void main(String[] args) throws JsonProcessingException {

		
		Employee emp = new Employee();
		emp.setAge(20);
		emp.setName("Codekru");
		emp.setDept(Dept.ADMIN);
		
		ObjectMapper mapper = new ObjectMapper();
		System.out.println(mapper.writeValueAsString(emp)); // serializing object

	}
}

Output –

{"name":"Codekru","age":20,"dept":"ADMIN"}

The ADMIN is treated as a string by default, but we can also treat the enum as an ordinal number using the JsonFormat annotation.

  • So, for IT, the ordinal value will be 0
  • For SECURITY, the ordinal value will be 1
  • And for ADMIN, the ordinal value would be 2

Formatting of enum type field with the @JsonFormat Annotation

Now, we will add the JsonFormat annotation over the dept field as illustrated below

public class Employee {

	enum Dept {
		IT, SECURITY, ADMIN
	}

	public String name;
	public int age;

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

	// getters and setters
}

Now, rerun the Codekru class, and below shall be the output

{"name":"Codekru","age":20,"dept":2}

Here the value corresponding to the dept property represents the ordinal number for the ADMIN.

Reference Article – https://www.javadoc.io/doc/com.fasterxml.jackson.core/jackson-annotations/2.9.8/com/fasterxml/jackson/annotation/JsonFormat.html

We hope that you have liked the article. If you have any doubts or concerns, please feel free to write us in the comments or mail us at [email protected].

Other Jackson Annotations –

Liked the article? Share this on

Leave a Comment

Your email address will not be published. Required fields are marked *