71.3 Customize the Jackson ObjectMapper
Spring MVC (client and server side) uses HttpMessageConverters to negotiate content conversion in an HTTP exchange. If Jackson is on the classpath you already get the default converter(s) provided by Jackson2ObjectMapperBuilder, an instance of which is auto-configured for you.
The ObjectMapper (or XmlMapper for Jackson XML converter) instance created by default has the following customized properties:
MapperFeature.DEFAULT_VIEW_INCLUSIONis disabledDeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIESis disabled
Spring Boot has also some features to make it easier to customize this behavior.
You can configure the ObjectMapper and XmlMapper instances using the environment. Jackson provides an extensive suite of simple on/off features that can be used to configure various aspects of its processing. These features are described in six enums in Jackson which map onto properties in the environment:
| Jackson enum | Environment property | ||||
|---|---|---|---|---|---|
com.fasterxml.jackson.databind.DeserializationFeature |
`spring.jackson.deserialization.<feature_name>=true | false` | |||
com.fasterxml.jackson.core.JsonGenerator.Feature |
`spring.jackson.generator.<feature_name>=true | false` | |||
com.fasterxml.jackson.databind.MapperFeature |
`spring.jackson.mapper.<feature_name>=true | false` | |||
com.fasterxml.jackson.core.JsonParser.Feature |
`spring.jackson.parser.<feature_name>=true | false` | |||
com.fasterxml.jackson.databind.SerializationFeature |
`spring.jackson.serialization.<feature_name>=true | false` | |||
com.fasterxml.jackson.annotation.JsonInclude.Include |
`spring.jackson.serialization-inclusion=always | non_null | non_absent | non_default | non_empty` |
For example, to enable pretty print, set spring.jackson.serialization.indent_output=true. Note that, thanks to the use of relaxed binding, the case of indent_output doesn’t have to match the case of the corresponding enum constant which is INDENT_OUTPUT.
This environment-based configuration is applied to the auto-configured Jackson2ObjectMapperBuilder bean, and will apply to any mappers created using the builder, including the auto-configured ObjectMapper bean.
The context’s Jackson2ObjectMapperBuilder can be customized by one or more Jackson2ObjectMapperBuilderCustomizer beans. Such customizer beans can be ordered and Boot’s own customizer has an order of 0, allowing additional customization to be applied both before and after Boot’s customization.
Any beans of type com.fasterxml.jackson.databind.Module will be automatically registered with the auto-configured Jackson2ObjectMapperBuilder and applied to any ObjectMapper instances that it creates. This provides a global mechanism for contributing custom modules when you add new features to your application.
If you want to replace the default ObjectMapper completely, either define a @Bean of that type and mark it as @Primary, or, if you prefer the builder-based approach, define a Jackson2ObjectMapperBuilder @Bean. Note that in either case this will disable all auto-configuration of the `ObjectMapper.
If you provide any @Beans of type MappingJackson2HttpMessageConverter then they will replace the default value in the MVC configuration. Also, a convenience bean is provided of type HttpMessageConverters (always available if you use the default MVC configuration) which has some useful methods to access the default and user-enhanced message converters.
See also the Section 71.4, “Customize the @ResponseBody rendering” section and the WebMvcAutoConfiguration source code for more details.