Close

Jackson JSON - Using @JsonInclude to define properties inclusion rules

[Updated: Jun 29, 2018, Created: Jun 28, 2018]

@JsonInclude annotation can be used to indicate when the annotated property can be serialized. Normally property values are always included, but by using this annotation we can specify simple exclusion rules based on property values.

This annotation can be used on a field, method or constructor parameter. It can also be used on class in which case the specified rules are applied to all properties of the class.

Following is the @JsonInclude definition snippet:

package com.fasterxml.jackson.annotation;
 .....
@Target({ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.FIELD,
    ElementType.TYPE, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotation
public @interface JsonInclude{
    public Include value() default Include.ALWAYS;//inclusion rules
    public Include content() default Include.ALWAYS;//rules on content (e.g. Map's elements)
    public Class<?> valueFilter() default Void.class;//used for values when Include.CUSTOM
    public Class<?> contentFilter() default Void.class;//used for contents values when Include.CUSTOM 
     ..
    public enum Include{
        ALWAYS,//always include property
        NON_NULL,//do not include property with null value
        NON_ABSENT,//no null values including no content null values like Optional, AtomicReference etc
        NON_EMPTY,//NON_NULL + NON_ABSENT + values like empty Collections/Map/arrays/String etc are excluded
        NON_DEFAULT,//no default values, e.g. no primitives with default values  
        CUSTOM,// a custom filter for exclusion specified by JsonInclude.valueFilter()
        USE_DEFAULTS//use defaults either from class level or ObjectMapper level
        ;
    }
......
}

In following example we will focus on exclusion of properties with null values only; in upcoming tutorials we will explore other settings.

Example

Java Object

@JsonInclude(JsonInclude.Include.NON_NULL)
public class Employee {
  private String name;
  private String dept;
  private String address;
    .............
}

Main class

public class ExampleMain {
  public static void main(String[] args) throws IOException {
      Employee employee = Employee.of("Trish", null, null);
      ObjectMapper om = new ObjectMapper();
      String jsonString = om.writeValueAsString(employee);
      System.out.println(jsonString);
  }
}
{"name":"Trish"}

As seen above 'dept' and 'address' properties were not included during serialization because we set null for them.

Without @JsonInclude

If we don't use @JsonInclude on Employee class then output will be:

{"name":"Trish","dept":null,"address":null}

Using ObjectMapper#setDefaultPropertyInclusion()

This method or ObjectMapper#setSerializationInclusion() can be used to specify inclusion rules globally. For example following will produce the same output as our above example:

public class Employee {
    private String name;
    private String dept;
    private String address;
...
}
public class ExampleMain {
    public static void main(String[] args) throws IOException {
        Employee employee = Employee.of("Trish", null, null);
        ObjectMapper om = new ObjectMapper();
        om.setDefaultPropertyInclusion(JsonInclude.Include.NON_NULL);
        String jsonString = om.writeValueAsString(employee);
        System.out.println(jsonString);
    }
}

Example Project

Dependencies and Technologies Used:

  • jackson-databind 2.9.6: General data-binding functionality for Jackson: works on core streaming API.
  • JDK 10
  • Maven 3.5.4

@JsonInclude Example Select All Download
  • jackson-json-include-annotation
    • src
      • main
        • java
          • com
            • logicbig
              • example
                • Employee.java

    See Also