Package com.fasterxml.jackson.annotation

Annotation Type JsonInclude

@Target({ANNOTATION_TYPE,METHOD,FIELD,TYPE,PARAMETER})
@Retention(RUNTIME)
public @interface JsonInclude

Annotation used to indicate when value of the annotated property (when used for a field, method or constructor parameter), or all properties of the annotated class (when used for a class), is to be serialized. Without annotation property values are always included, but by using this annotation one can specify simple exclusion rules to reduce amount of properties to write out.

Note that the main inclusion criteria (one annotated with value()) is checked on Java object level, for the annotated type, and NOT on JSON output -- so even with JsonInclude.Include.NON_NULL it is possible that JSON null values are output, if object reference in question is not `null`. An example is AtomicReference instance constructed to reference null value: such a value would be serialized as JSON null, and not filtered out.

To base inclusion on value of contained value(s) (like java.util.Map entries), you will typically also need to specify content() annotation; for example, specifying only value() as JsonInclude.Include.NON_EMPTY for a Map would exclude Maps with no entries (empty Maps), but would include Maps elements with null values (even though nulls are considered "empty" values). To exclude Maps with only `null`-valued entries, you would use both annotations like so:

public class Bean {
   @JsonInclude(value=Include.NON_EMPTY, content=Include.NON_NULL)
   public Map<String,String> entries;
}

(in which case filtering first excludes Map entries with null values and then excludes Maps that have no entries left).
Similarly you could exclude Maps map entries with "empty" values, or "non-default" values (see JsonInclude.Include.NON_EMPTY and JsonInclude.Include.NON_DEFAULT for more details).

In addition to Maps, content concept is also supported for referential types (like AtomicReference).

(For Jackson 2 only) Note that `content` is NOT currently (as of Jackson 2.20) supported for arrays or Collections; support may be added in future versions (but if so, will be configurable to allow disabling it).

(For Jackson 3 only) As of Jackson 3.1.0, content() also supports Collections and Arrays when tools.jackson.databind.SerializationFeature#APPLY_JSON_INCLUDE_FOR_CONTAINERS feature is enabled -- disabled by default for backward-compatibility (see [databind#5369] for more detail).

Since:

2.0

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
JsonInclude.Include	content	Inclusion rule to use for entries ("content") of annotated Maps and referential types (like AtomicReference); defaults to JsonInclude.Include.ALWAYS.
java.lang.Class<?>	contentFilter	Specifies type of "Filter Object" to use in case content() is JsonInclude.Include.CUSTOM: if so, an instance is created by calling HandlerInstantiator (of ObjectMapper), which by default simply calls zero-argument constructor of the Filter Class.
JsonInclude.Include	value	Inclusion rule to use for instances (values) of types (Classes) or properties annotated; defaults to JsonInclude.Include.ALWAYS.
java.lang.Class<?>	valueFilter	Specifies type of "Filter Object" to use in case value() is JsonInclude.Include.CUSTOM: if so, an instance is created by calling HandlerInstantiator (of ObjectMapper), which by default simply calls zero-argument constructor of the Filter Class.

Element Detail

value

JsonInclude.Include value

Inclusion rule to use for instances (values) of types (Classes) or properties annotated; defaults to JsonInclude.Include.ALWAYS.

Returns:

Inclusion rule for value itself

Default:

com.fasterxml.jackson.annotation.JsonInclude.Include.ALWAYS

content

JsonInclude.Include content

Inclusion rule to use for entries ("content") of annotated Maps and referential types (like AtomicReference); defaults to JsonInclude.Include.ALWAYS.

Returns:

Inclusion rule for content (elements, values of structured types)

Since:

2.5

Default:

com.fasterxml.jackson.annotation.JsonInclude.Include.ALWAYS

valueFilter

java.lang.Class<?> valueFilter

Specifies type of "Filter Object" to use in case value() is JsonInclude.Include.CUSTOM: if so, an instance is created by calling HandlerInstantiator (of ObjectMapper), which by default simply calls zero-argument constructor of the Filter Class.

Whether the value is to be included or not is determined by calling Filter's equals(value) method: if it returns true value is NOT included (it is "filtered out"); if false value IS included ("not filtered out").

Since:

2.9

Default:

java.lang.Void.class

contentFilter

java.lang.Class<?> contentFilter

Specifies type of "Filter Object" to use in case content() is JsonInclude.Include.CUSTOM: if so, an instance is created by calling HandlerInstantiator (of ObjectMapper), which by default simply calls zero-argument constructor of the Filter Class.

Whether the content value is to be included or not is determined by calling Filter's equals(value) method: if it returns true content value is NOT included (it is "filtered out"); if false content value IS included ("not filtered out").

Since:

2.9

Default:

java.lang.Void.class