How To Serialize and Deserialize Enums with Jackson

1. Overview

In this quick tutorial, we’ll learn how to control the way Java Enums are serialized and deserialized with Jackson 2.

To dig a little deeper and learn other cool things we can do with Jackson 2, head on over to the main Jackson tutorial.

2. Controlling the Enum Representation

Let’s define the following Enum:

public enum Distance {
    KILOMETER("km", 1000), 
    MILE("miles", 1609.34),
    METER("meters", 1), 
    INCH("inches", 0.0254),
    CENTIMETER("cm", 0.01), 
    MILLIMETER("mm", 0.001);

    private String unit;
    private final double meters;

    private Distance(String unit, double meters) {
        this.unit = unit;
        this.meters = meters;
    }

    // standard getters and setters
}

3. Serializing Enums to JSON

3.1. Default Enum Representation

By default, Jackson will represent Java Enums as a simple String. For instance:

new ObjectMapper().writeValueAsString(Distance.MILE);

Will result in:

"MILE"

However, when marshaling this Enum to a JSON Object, we would like to get something like:

{"unit":"miles","meters":1609.34}

3.2. Enum as a JSON Object

Starting with Jackson 2.1.2, there’s now a configuration option that can handle this kind of representation. This can be done via the @JsonFormat annotation at the class level:

@JsonFormat(shape = JsonFormat.Shape.OBJECT)
public enum Distance { ... }

This will lead to the desired result when serializing this enum for Distance.MILE:

{"unit":"miles","meters":1609.34}

3.3. Enums and @JsonValue

Another simple way of controlling the marshaling output for an enum is using the @JsonValue annotation on a getter:

public enum Distance { 
    ...
 
    @JsonValue
    public String getMeters() {
        return meters;
    }
}

What we’re expressing here is that getMeters() is the actual representation of this enum. So the result of serializing will be:

1609.34

3.4. Custom Serializer for Enum

If we’re using a version of Jackson earlier than 2.1.2, or if even more customization is required for the enum, we can use a custom Jackson serializer. First, we’ll need to define it:

public class DistanceSerializer extends StdSerializer {
    
    public DistanceSerializer() {
        super(Distance.class);
    }

    public DistanceSerializer(Class t) {
        super(t);
    }

    public void serialize(
      Distance distance, JsonGenerator generator, SerializerProvider provider) 
      throws IOException, JsonProcessingException {
        generator.writeStartObject();
        generator.writeFieldName("name");
        generator.writeString(distance.name());
        generator.writeFieldName("unit");
        generator.writeString(distance.getUnit());
        generator.writeFieldName("meters");
        generator.writeNumber(distance.getMeters());
        generator.writeEndObject();
    }
}

Then we can apply the serializer to the class that’ll be serialized:

@JsonSerialize(using = DistanceSerializer.class)
public enum TypeEnum { ... }

This results in:

{"name":"MILE","unit":"miles","meters":1609.34}

4. Deserializing JSON to Enum

First, let’s define a City class that has a Distance member:

public class City {
    
    private Distance distance;
    ...    
}

Then we’ll discuss the different ways of deserializing a JSON string to an Enum.

4.1. Default Behavior

By default, Jackson will use the Enum name to deserialize from JSON.

For example, it’ll deserialize the JSON:

{"distance":"KILOMETER"}

To a Distance.KILOMETER object:

City city = new ObjectMapper().readValue(json, City.class);
assertEquals(Distance.KILOMETER, city.getDistance());

If we want Jackson to case-insensitively deserialize from JSON by the Enum name, we need to customize the ObjectMapper to enable the ACCEPT_CASE_INSENSITIVE_ENUMS feature.

Let’s say we have another JSON:

{"distance":"KiLoMeTeR"}

Now, let’s do a case-insensitive deserialization:

ObjectMapper objectMapper = JsonMapper.builder()
  .enable(MapperFeature.ACCEPT_CASE_INSENSITIVE_ENUMS)
  .build();
City city = objectMapper.readValue(json, City.class);
                                                     
assertEquals(Distance.KILOMETER, city.getDistance());

As the test above shows, we enable the ACCEPT_CASE_INSENSITIVE_ENUMS feature with the JsonMapper builder.

4.2. Using @JsonValue

We’ve learned how to use @JsonValue to serialize Enums. We can use the same annotation for deserialization as well. This is possible because Enum values are constants.

First, let’s use @JsonValue with one of the getter methods, getMeters():

public enum Distance {
    ...

    @JsonValue
    public double getMeters() {
        return meters;
    }
}

The return value of the getMeters() method represents the Enum objects. Therefore, when deserializing the sample JSON:

{"distance":"0.0254"}

Jackson will look for the Enum object that has a getMeters() return value of 0.0254. In this case, the object is Distance.INCH:

assertEquals(Distance.INCH, city.getDistance());

4.3. Using @JsonProperty

The @JsonProperty annotation is used on enumeration instances:

public enum Distance {
    @JsonProperty("distance-in-km")
    KILOMETER("km", 1000), 
    @JsonProperty("distance-in-miles")
    MILE("miles", 1609.34);
 
    ...
}

By using this annotation, we’re simply telling Jackson to map the value of the @JsonProperty to the object annotated with this value.

As a result of the above declaration, the example JSON string:

{"distance": "distance-in-km"}

Will be mapped to the Distance.KILOMETER object:

assertEquals(Distance.KILOMETER, city.getDistance());

4.4. Using @JsonCreator

Jackson invokes methods annotated with @JsonCreator to get an instance of the enclosing class.

Consider the JSON representation:

{
    "distance": {
        "unit":"miles", 
        "meters":1609.34
    }
}

Then we’ll define the forValues() factory method with the @JsonCreator annotation:

public enum Distance {
   
    @JsonCreator
    public static Distance forValues(@JsonProperty("unit") String unit,
      @JsonProperty("meters") double meters) {
        for (Distance distance : Distance.values()) {
            if (
              distance.unit.equals(unit) && Double.compare(distance.meters, meters) == 0) {
                return distance;
            }
        }

        return null;
    }

    ...
}

Note the use of the @JsonProperty annotation to bind the JSON fields with the method arguments.

Then, when we deserialize the JSON sample, we’ll get the result:

assertEquals(Distance.MILE, city.getDistance());

4.5. Using a Custom Deserializer

We can use a custom deserializer if none of the described techniques are available. For example, we might not have access to the Enum source code, or we might be using an older Jackson version that doesn’t support one or more of the annotations covered so far.

According to our custom deserialization article, in order to deserialize the JSON provided in the previous section, we’ll start by creating the deserialization class:

public class CustomEnumDeserializer extends StdDeserializer<Distance> {

    @Override
    public Distance deserialize(JsonParser jsonParser, DeserializationContext ctxt)
      throws IOException, JsonProcessingException {
        JsonNode node = jsonParser.getCodec().readTree(jsonParser);

        String unit = node.get("unit").asText();
        double meters = node.get("meters").asDouble();

        for (Distance distance : Distance.values()) {
           
            if (distance.getUnit().equals(unit) && Double.compare(
              distance.getMeters(), meters) == 0) {
                return distance;
            }
        }

        return null;
    }
}

Then we’ll use the @JsonDeserialize annotation on the Enum to specify our custom deserializer:

@JsonDeserialize(using = CustomEnumDeserializer.class)
public enum Distance {
   ...
}

And our result is:

assertEquals(Distance.MILE, city.getDistance());

5. Conclusion

This article illustrated how to gain better control over the serialization and deserialization processes and formats of Java Enums.