Guide to Jackson Annotations

1. Introduction

Jackson provides a number of annotations which help tweak various facets of JSON serialization and deserialization. In this guide, we present some important and commonly used Jackson annotations.

2. @JsonProperty

The annotation @JsonProperty is used to change the JSON property name used in serialization and deserialization. For example,

public class User {
    @JsonProperty("FirstName")
    private String firstName;
}

Output before and after:

// before
...
  "firstName" : "Harrison",
...

// after
  "FirstName" : "Harrison",
...

2.1. Confusion with required

The annotation @JsonProperty defines an attribute required which does not quite work the way it is expected. Despite being specified, it does not mark the property as required either during serialization or deserialization. It applies only when using @JsonProperty with @JsonCreator. For example, the following does not require the presence of the the property “FirstName“:

public class User {
    @JsonProperty(value="LastName", required=true)
    private String lastName;
}

2.2. @JsonProperty and @JsonCreator

@JsonProperty can be used with @JsonCreator to indicate the constructor to use when deserializing JSON. Consider the following class which does not implement a no-arguments default constructor but has a constructor taking appropriate arguments.

public class MyClass {
    private String firstName;
    private String lastName;

    public MyClass(String firstName,String lastName)
    {
	this.firstName = firstName;
	this.lastName = lastName;
    }
}

Create an instance of this class and serialize it to JSON.

MyClass obj = new MyClass("Harrison", "Ford");
System.out.println(mapper.writeValueAsString(obj));

// serialized to:
{
  "firstName" : "Harrison",
  "lastName" : "Ford",
}

Deserializing this JSON results in a JsonMappingException. That is because Jackson cannot create an instance of the class in the absence of a default constructor.

Exception in thread "main" com.fasterxml.jackson.databind.JsonMappingException: Can not construct instance of sample.sample11$MyClass: no suitable constructor found, can not deserialize from Object value (missing default constructor or creator, or perhaps need to add/enable type information?)

What if you do not want to add a default constructor due to design considerations? Jackson offers a solution: use @JsonCreator with @JsonProperty to properly mark the constructor. The constructor takes two arguments, both of which are marked required. With this change, Jackson is able to create an instance of MyClass with the proper arguments.

public class MyClass {
    private String firstName;
    private String lastName;
    private Address address;

    @JsonCreator
    public MyClass(@JsonProperty(value = "firstName",required = true) String firstName,
		   @JsonProperty(value = "lastName", required = true) String lastName)
    {
	this.firstName = firstName;
	this.lastName = lastName;
    }
}

3. @JsonIgnore

Property-level annotation used to ignore specified properties. These properties are ignored during both serialization and deserialization. For instance, the following property password is neither written to JSON nor read from JSON.

...
    @JsonIgnore
    private String password;
...

4. @JsonIgnoreProperties

Class level annotation used to ignore multiple properties.

@JsonIgnoreProperties({"bar", "baz"})
public class MyClass
{
    private String foo;
    private String bar;
    private Integer baz;
    ...
}

Additionally, you can use this annotation to ignore unknown properties during deserialization. If unknown properties are present in the JSON, you will get an UnrecognizedPropertyException.

@JsonIgnoreProperties(ignoreUnknown=true, {"bar", "baz"})
public class MyClass
{
    private String foo;
    private String bar;
    ...
}

Parsing the following JSON will not result in an exception due to specifying ignoreUnknown.

{
  "foo" : "value of foo",
  "bar" : "value of bar",
  "qux" : "value of qux"
}

5. @JsonIgnoreType

To ignore a particular class (or built-in type) during serialization and deserialization, use the @JsonIgnoreType annotation on the class. In the following, the MyClass.address property will not be serialized or deserialized.

@JsonIgnoreType
public class Address {
    private String address1;
    ...
}

public class MyClass {
    private Address address;
    private String firstName;
    private String lastName;
}

Note that MyClass.address property has bot been serialized. It will be ignored during deserialization.

{
  "firstName" : "Harrison",
  "lastName" : "Ford"
}

6. @JsonFormat

@JsonFormat is used to specify some extra details when serializing certain types especially dates.

The date field in the following class is serialized by default as a timestamp.

public class MyClass
{
    private Date createdDate = new Date();
}

// serialized to:
{
  "createdDate" : 1485913763410
}

Annotate the date field with @JsonFormat and use pattern to set the date format:

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

Serialization now shows the date in the specified format:

{
  "createdDate" : "2017-02-01@01:58:28.130+0000"
}

Deserialization also works as expected. If the date is not specified in the same format as required by the pattern, you get the following exception:

Exception in thread "main" com.fasterxml.jackson.databind.exc.InvalidFormatException: Can not deserialize value of type java.util.Date from String "...": expected format "yyyy-MM-dd@HH:mm:ss.SSSZ" ...

7. @JsonUnwrapped

You can use @JsonUnwrapped to indicate to Jackson that a contained object should be unwrapped during serialization i.e. the contained object properties should be included among the properties of the parent. An example:

public class Address {
    private String address1;
    private String address2;
    private String city;
    private String state;
    private String zip;
}

public class MyClass {
    private String firstName;
    private String lastName;
    @JsonUnwrapped
    private Address address;
}

When an object of MyClass is serialized, the properties of address are included among the properties of MyClass:

{
  "firstName" : "Harrison",
  "lastName" : "Ford",
  "address1" : "123 Main Street",
  "address2" : null,
  "city" : "Hollywood",
  "state" : "CA",
  "zip" : "33023"
}

To prevent clashes between the parent and child object properties, a prefix or suffix can be specified to be added to the child properties:

public class MyClass {
    private String firstName;
    private String lastName;
    @JsonUnwrapped(prefix="addr.")
    private Address address;
}

The resulting JSON is now:

{
  "firstName" : "Harrison",
  "lastName" : "Ford",
  "addr.address1" : "123 Main Street",
  "addr.address2" : null,
  "addr.city" : "Hollywood",
  "addr.state" : "CA",
  "addr.zip" : "33023"
}

During deserialization, either of the forms shown are accepted without errors.

// normal form
{
  "firstName" : "Harrison",
  "lastName" : "Ford",
  "address" : {
    "address1" : "123 Main Street",
    "address2" : null,
    "city" : "Hollywood",
    "state" : "CA",
    "zip" : "33023"
  }
}

// no prefix
{
  "firstName" : "Harrison",
  "lastName" : "Ford",
  "address1" : "123 Main Street",
  "address2" : null,
  "city" : "Hollywood",
  "state" : "CA",
  "zip" : "33023"
}

// with prefix
{
  "firstName" : "Harrison",
  "lastName" : "Ford",
  "addr.address1" : "123 Main Street",
  "addr.address2" : null,
  "addr.city" : "Hollywood",
  "addr.state" : "CA",
  "addr.zip" : "33023"
}

8. @JsonGetter

This annotation can be used on a no-arguments method returning non-void, with the value specified to indicate the name of a logical property. An example, serializing an object of the class below will include a property “joe” defined as the value returned from the method theDate().

public class MyClass {
    private String firstName;
    private String lastName;

    @JsonGetter("joe")
    public Date theDate()
    {
	return new Date();
    }
}

// serialized to:
{
 "firstName" : "Harrison",
 "lastName" : "Ford",
 "joe" : 1485931403261
}

9. @JsonAnyGetter and @JsonAnySetter

In some instances, you may have a situation where a class has dynamic properties stored in a Map and these properties need to be exposed to JSON. In this situation, the getter method or the Map field can be marked with the @JsonAnyGetter annotation. An example will illustrate the point.

public class MyClass {
    private String firstName;
    private String lastName;
    private Address address;
    private Map<String,Object> moreProps = new HashMap<>();
}

// set properties
MyClass obj = new MyClass();
...
obj.setAddress(address);
obj.getMoreProps().put("born", "Chicago, Illinois");
System.out.println(mapper.writeValueAsString(obj));

// serialized to:
{
  "firstName" : "Harrison",
  "lastName" : "Ford",
  "moreProps" : {
    "born" : "Chicago, Illinois"
  }
}

As expected, the Map field appears as a separate object within the container object. Using the @JsonAnyGetter merges the Map entries into the parent JSON.

public class MyClass {
    private String firstName;
    private String lastName;
    private Address address;
    private Map<String,Object> moreProps = new HashMap<>();

    @JsonAnyGetter
    public Map<String,Object> getMoreProps() {
        return moreProps;
    }
}

// create and set object properties here as before
MyClass obj = new MyClass();
...

// serialized to:
{
  "firstName" : "Harrison",
  "lastName" : "Ford",
  "born" : "Chicago, Illinois"
}

That takes care of serialization. How about deserialization? JSON serialized for the above case cannot directly be used for deserialization as it results in an UnrecognizedPropertyException.

The solution is to use @JsonAnySetter on a method which accepts a key and a value to set the property. See below.

public class MyClass {
    ... // as before

    @JsonAnySetter
    public void setMore(String key,Object value)
    {
	moreProps.put(key, value);
    }
}

With this method definition and annotation in place, deserialization is also a breeze.

10. @JsonValue

@JsonValue can be used to serialize the complete state of an object using a single method rather than the usual serialization using properties. An example will help clarify the picture.

The following class marks the toString() method with @JsonValue. When serializing this object, Jackson uses the representation returned from this method as the value of the object. Note that the value returned is not valid JSON.

public class Address {
    private String address1;
    private String address2;
    private String city;
    private String state;
    private String zip;

    @JsonValue
    public String toString()
    {
	StringBuilder sbuf = new StringBuilder();
	sbuf.append(address1).append("|")
	    .append(address2).append("|")
	    .append(city).append("|")
	    .append(state).append("|")
	    .append(zip).append("|");
	return sbuf.toString();
    }
}

Serializing an instance of the above class yields:

"123 Main Street|null|Hollywood|CA|33023|"

Let us see how this works when included as a part of another class.

public class MyClass {
    private String firstName;
    private String lastName;
    private Address address;
}

After suitable initialization and serialization, we have the following JSON output. Note that the method annotated with @JsonValue was used for converting the value of Address to its representation.

{
  "firstName" : "Harrison",
  "lastName" : "Ford",
  "address" : "123 Main Street|null|Hollywood|CA|33023|"
}

10.1. @JsonValue and @JsonCreator

Now, how do we deserialize this JSON into the proper object? We make use of the @JsonCreator annotation to mark a static factory method (or a constructor) which can create the object from its string representation. This method does the opposite of what the @JsonValue method does: it splits the string representation and sets the appropriate fields.

public class Address {
    private String address1;
    private String address2;
    ...

    @JsonCreator
    static public Address fromString(String value)
    {
	String[] values = value.split("\\|");
	Address obj = new Address();
	int index = 0;
	if ( index < values.length ) {
	    obj.setAddress1(values[index]);
	    index++;
	}
	if ( index < values.length ) {
	    obj.setAddress2(values[index]);
	    index++;
	}
	if ( index < values.length ) {
	    obj.setCity(values[index]);
	    index++;
	}
	if ( index < values.length ) {
	    obj.setState(values[index]);
	    index++;
	}
	if ( index < values.length ) {
	    obj.setZip(values[index]);
	    index++;
	}
	return obj;
    }
}

11. @JsonPropertyOrder

Sometimes you may need to specify the order in which the properties are serialized. By default properties are serialized in the order they are defined in the class. If this order is not satisfactory, you can use @JsonPropertyOrder to specify the order of appearance.

The following definition illustrates the point. Note the order in which the properties are serialized in JSON.

public class MyClass {
    private Address address;
    private String firstName;
    private String lastName;
}

// serialized by default as:
{
  "address" : {
    "address1" : "123 Main Street",
    "address2" : null,
    "city" : "Hollywood",
    "state" : "CA",
    "zip" : "33023"
  },
  "firstName" : "Harrison",
  "lastName" : "Ford"
}

Now applying the @JsonPropertyOrder annotation as shown rearranges the order to the required.

@JsonPropertyOrder(value = {"firstName", "lastName", "address"})
static public class MyClass {
    private Address address;
    ...
}

// serialized to:
{
  "firstName" : "Harrison",
  "lastName" : "Ford",
  "address" : {
    "address1" : "123 Main Street",
    "address2" : null,
    "city" : "Hollywood",
    "state" : "CA",
    "zip" : "33023"
  }
}

12. Mixin Annotations

Sometimes the class being used in JSON conversion may not be available for direct modification to add or remove annotations. Maybe the class is a part of a library and hence cannot be edited. How can we declare the annotations that we want on such classes? We use Mixins! Mixin classes can be declared with the desired annotations and added to the ObjectMapper using the addMixIn() method.

Example class:

public class MyClass
{
    private String foo;
    private String bar;
    private Integer baz;
    ...
}

Declare and add a mixin class like this. (The class can be a local class.)

@JsonIgnoreProperties(ignoreUnknown=true)
class Mixin {
    @JsonIgnore
    private Integer baz;
};
mapper.addMixIn(MyClass.class, Mixin.class);

Sample output from serialization. Note that property baz is ignored.

{
  "foo" : "value of foo",
  "bar" : "value of bar"
}

Deserializing this JSON does not cause an exception since ignoreUnknown is set in the mixin.

{
  "foo" : "value of foo",
  "bar" : "value of bar",
  "qux" : "value of qux"
}

Summary

In this article, we looked at some of the most common Jackson annotations for JSON serialization and deserialization.