Customize Jackson ObjectMapper in Spring Boot: Serialization & Deserialization

Jackson is the default JSON processing library in Spring Boot since version 1.2.0, and for good reason — it's fast, flexible, and battle-tested. But the default ObjectMapper configuration is a one-size-fits-all solution that will bite you in production. I've seen it happen: a LocalDateTime serialized as an array of integers, a null field causing a 500 error, or a circular reference blowing up the stack. These aren't hypotheticals; they're scars from late-night war rooms.

In this guide, we'll go beyond the basics. You'll learn how to customize Jackson ObjectMapper in Spring Boot 3.x (and 2.x) for both serialization and deserialization. We'll cover global configuration via application.properties, programmatic customization with Jackson2ObjectMapperBuilder, custom serializers and deserializers for complex domains like payment-processing, and mix-ins for third-party classes. We'll also dissect a real production incident where a misconfigured mapper caused a billing outage. By the end, you'll have a battle-ready ObjectMapper that handles edge cases, legacy formats, and strict API contracts without breaking a sweat.

Understanding Spring Boot's Default ObjectMapper

When you add spring-boot-starter-web to your project, Spring Boot auto-configures an ObjectMapper bean with sensible defaults. But "sensible" is relative. In Spring Boot 2.x, the default mapper does NOT include JavaTimeModule for Java 8 date/time types — that's a landmine. It also allows unknown properties during deserialization by default (FAIL_ON_UNKNOWN_PROPERTIES = false), which can silently swallow API contract violations. In Spring Boot 3.x, the defaults improved slightly, but you still need to explicitly configure date formats and naming strategies for most real-world apps.

Let's inspect the default behavior. Create a simple controller that returns a DTO with a LocalDateTime field.

@RestController
public class DefaultMapperController {

    @GetMapping("/invoice")
    public Invoice getInvoice() {
        return new Invoice(123, "ACME Corp", LocalDateTime.now());
    }

    record Invoice(int id, String customer, LocalDateTime createdAt) {}
}

What the Official Docs Won't Tell You

The official Spring Boot documentation tells you about spring.jackson.* properties and Jackson2ObjectMapperBuilder, but it glosses over the real-world pitfalls. Here's what I've learned from 15+ years of production battles:

First, Jackson2ObjectMapperBuilder is your best friend for programmatic configuration. But don't just chain methods blindly — order matters. For example, calling modules() after modulesToInstall() will overwrite the default modules. Use modules() once with a list.

Second, the @JsonFormat annotation on a field overrides global settings, but only if Jackson can find the annotation. If you use Lombok's @Builder or records, ensure the annotation is on the getter or constructor parameter, not just the field. I've spent hours debugging why a @JsonFormat(pattern = "yyyy-MM-dd") was ignored — Lombok generated the getter without the annotation.

Third, never use ObjectMapper directly in a @PostConstruct of a configuration class. Spring Boot may not have fully initialized the auto-configured mapper yet. Instead, create a @Bean method that returns a configured ObjectMapper and inject it where needed.

Finally, the spring.jackson.property-naming-strategy property in application.properties is powerful but limited. For complex naming strategies (e.g., snake_case for some fields, camelCase for others), you need a custom PropertyNamingStrategy or mix-ins.

@Configuration
public class JacksonConfig {

    @Bean
    public Jackson2ObjectMapperBuilder jacksonBuilder() {
        Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder();
        builder.serializationInclusion(JsonInclude.Include.NON_NULL)
               .failOnUnknownProperties(true)
               .propertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE)
               .modulesToInstall(new JavaTimeModule());
        // Don't call .modules() again here — it will overwrite JavaTimeModule
        return builder;
    }
}

Global Configuration via application.properties

The simplest way to customize Jackson is through application.properties (or YAML). Spring Boot exposes a set of spring.jackson.* properties that control the ObjectMapper globally. This is ideal for cross-cutting concerns like date format, null handling, and property naming strategy. However, these properties are limited to what Spring Boot exposes — for advanced customization, you'll need programmatic configuration.

Here's a battle-tested configuration for a REST API that communicates with external services:

# Jackson global configuration
spring.jackson.serialization.write-dates-as-timestamps=false
spring.jackson.date-format=yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
spring.jackson.time-zone=UTC
spring.jackson.default-property-inclusion=non_null
spring.jackson.deserialization.fail-on-unknown-properties=true
spring.jackson.property-naming-strategy=SNAKE_CASE
spring.jackson.serialization.write-enums-using-to-string=true
spring.jackson.deserialization.read-enums-using-to-string=true

Custom Serializers for Complex Types

When global configuration isn't enough, you need custom serializers. This is common in payment-processing systems where you need to mask sensitive data like credit card numbers or format monetary amounts with precision. Writing a custom serializer gives you full control over the JSON output.

Let's create a serializer for a MonetaryAmount class that outputs a formatted string with currency code.

public class MonetaryAmountSerializer extends StdSerializer<MonetaryAmount> {

    public MonetaryAmountSerializer() {
        super(MonetaryAmount.class);
    }

    @Override
    public void serialize(MonetaryAmount value, JsonGenerator gen, SerializerProvider provider)
            throws IOException {
        gen.writeString(String.format("%s %.2f", value.getCurrency().getCurrencyCode(),
                value.getNumber().doubleValueExact()));
    }
}

// Register in config
@Bean
public ObjectMapper objectMapper() {
    SimpleModule module = new SimpleModule();
    module.addSerializer(MonetaryAmount.class, new MonetaryAmountSerializer());
    return new ObjectMapper().registerModule(module);
}

Custom Deserializers for Legacy Formats

Deserialization is where most production incidents happen. You receive JSON from an external API that uses a legacy format — dates as timestamps, enums as integers, or nested objects as flat strings. A custom deserializer can normalize this data into your domain model without changing the external contract.

Consider a legacy CRM that sends dates as Unix timestamps in milliseconds. We need to deserialize them into LocalDateTime.

public class UnixTimestampDeserializer extends StdDeserializer<LocalDateTime> {

    public UnixTimestampDeserializer() {
        super(LocalDateTime.class);
    }

    @Override
    public LocalDateTime deserialize(JsonParser p, DeserializationContext ctxt) throws IOException {
        long timestamp = p.getValueAsLong();
        return LocalDateTime.ofInstant(Instant.ofEpochMilli(timestamp), ZoneOffset.UTC);
    }
}

// Register in config
SimpleModule module = new SimpleModule();
module.addDeserializer(LocalDateTime.class, new UnixTimestampDeserializer());
objectMapper.registerModule(module);

Mix-Ins: Modifying Third-Party Classes

Mix-ins are Jackson's secret weapon for modifying serialization/deserialization of classes you don't control — think library classes, generated code, or legacy domain objects. Instead of subclassing or modifying the source, you create an abstract class with annotations and tell ObjectMapper to apply it to the target class.

Imagine you use a third-party library that has a Customer class with a getSsn() method. You want to exclude SSN from JSON output without touching the library's code.

// Assume third-party class: com.external.Customer with getSsn()

public abstract class CustomerMixin {
    @JsonIgnore
    abstract String getSsn();

    @JsonProperty("full_name")
    abstract String getName();
}

// Register in config
@Bean
public ObjectMapper objectMapper() {
    ObjectMapper mapper = new ObjectMapper();
    mapper.addMixIn(Customer.class, CustomerMixin.class);
    return mapper;
}

Testing Your ObjectMapper Configuration

You can't trust what you don't test. In production, a misconfigured ObjectMapper can silently corrupt data or throw exceptions at the worst moment. I always add integration tests that verify serialization and deserialization of every DTO that crosses a service boundary. Use @JsonTest from Spring Boot to load only the Jackson infrastructure, or write plain unit tests with a configured ObjectMapper.

Here's a comprehensive test for our custom configuration:

@SpringBootTest
@AutoConfigureJsonTesters
class JacksonConfigTest {

    @Autowired
    private JacksonTester<Invoice> jacksonTester;

    @Test
    void shouldSerializeLocalDateTimeAsIsoString() throws Exception {
        Invoice invoice = new Invoice(1, "Test", LocalDateTime.of(2024, 3, 15, 14, 30, 0));
        assertThat(jacksonTester.write(invoice))
                .hasJsonPathStringValue("$.createdAt")
                .extractingJsonPathStringValue("$.createdAt")
                .startsWith("2024-03-15T14:30:00");
    }

    @Test
    void shouldFailOnUnknownProperties() {
        String json = "{\"id\":1,\"unknown\":\"value\"}";
        assertThatThrownBy(() -> jacksonTester.parseObject(json))
                .isInstanceOf(UnrecognizedPropertyException.class);
    }
}

Performance Tuning for High-Throughput APIs

In high-throughput systems like real-time analytics or payment processing, ObjectMapper performance matters. Jackson is fast, but misconfiguration can introduce bottlenecks. Here are lessons from optimizing ObjectMapper for 10,000+ requests per second:

First, avoid @JsonFormat on fields that are serialized millions of times. Each invocation uses reflection to read the annotation. Instead, use a custom serializer or global configuration. Second, enable ObjectMapper's WRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED sparingly — it can confuse clients. Third, use @JsonInclude(Include.NON_EMPTY) instead of NON_NULL to also exclude empty collections, reducing payload size.

Finally, consider using AfterburnerModule for zero-reflection serialization. It generates bytecode at runtime that accesses fields directly, bypassing reflection. In Spring Boot 3.x, you can add it as a dependency and register it as a module.

@Configuration
public class PerformanceConfig {

    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.registerModule(new AfterburnerModule());
        mapper.configure(SerializationFeature.WRITE_SINGLE_ELEM_ARRAYS_UNWRAPPED, false);
        mapper.setSerializationInclusion(JsonInclude.Include.NON_EMPTY);
        // Disable features that cause performance overhead
        mapper.disable(MapperFeature.DEFAULT_VIEW_INCLUSION);
        mapper.disable(DeserializationFeature.ADJUST_DATES_TO_CONTEXT_TIME_ZONE);
        return mapper;
    }
}