By WebNest Studio Engineering Team
Spring Boot Tutorial
JSON with Jackson 3
Almost every Spring Boot API speaks JSON, and the library doing the work is Jackson. Spring Boot 4 moves to Jackson 3, a major version with a new package name (tools.jackson), immutable mappers built with builders, unchecked exceptions and better defaults. Jackson 2 is still available in a deprecated form to ease migration.
This lesson shows how Spring Boot configures Jackson, how to control JSON output with annotations, how to customise the mapper globally with properties and customizers, how to write custom serializers, and what changes when you migrate from Jackson 2.
What Changed in Jackson 3
Most core classes moved from com.fasterxml.jackson to tools.jackson (for example tools.jackson.databind.json.JsonMapper), but the annotations you use daily — @JsonProperty, @JsonIgnore, @JsonInclude, @JsonFormat — stay in com.fasterxml.jackson.annotation, so most model classes compile unchanged. JsonMapper is immutable and built with JsonMapper.builder(). Jackson exceptions are now unchecked (JacksonException extends RuntimeException). Java time types are supported out of the box and dates are written as ISO-8601 strings by default.
Spring Boot Integration
Spring Boot auto-configures a JsonMapper bean used by Spring MVC, RestClient and WebClient. Customise it with spring.jackson.* properties or with a JsonMapperBuilderCustomizer bean (the Jackson 3 replacement for Jackson2ObjectMapperBuilderCustomizer). Custom serializers can be registered with @JacksonComponent (formerly @JsonComponent). Spring Boot keeps the helpful default of not failing on unknown JSON properties, so clients can send extra fields safely.
Controlling Output with Annotations
Annotations on your DTOs shape the JSON contract:
@JsonProperty("full_name")— rename a field in JSON.@JsonIgnore— never serialise a field (e.g. an internal flag).@JsonInclude(JsonInclude.Include.NON_NULL)— omit null fields.@JsonFormat(pattern = "dd-MM-yyyy")— custom date format for one field.@JsonPropertyOrder,@JsonAlias,@JsonUnwrapped,@JsonView— ordering, accepting old names, flattening, and per-endpoint field sets.@JsonTypeInfo+@JsonSubTypes— polymorphic JSON (e.g. different payment method types).
DTOs Instead of Entities
Serialising JPA entities directly couples your API to your database schema, triggers lazy loading, and can leak fields such as password hashes. Map entities to records designed for the API (see the DTOs lesson). Records work perfectly with Jackson 3 without any annotations.
Examples
A DTO shaped with Jackson annotations
import com.fasterxml.jackson.annotation.*; // annotations keep their old package
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonPropertyOrder({"id", "fullName", "email"})
public record StudentDto(
Long id,
@JsonProperty("fullName") String name,
String email,
@JsonFormat(pattern = "dd-MM-yyyy") LocalDate joined,
Instant lastLogin,
String phone,
@JsonIgnore String internalNotes) {}
@GetMapping("/api/students/{id}")
public StudentDto get(@PathVariable Long id) {
return new StudentDto(id, "Asha Rao", "asha@webnest.in", LocalDate.of(2026, 1, 15),
Instant.parse("2026-09-27T08:30:00Z"), null, "VIP support");
}
{"id":7,"fullName":"Asha Rao","email":"asha@webnest.in","joined":"15-01-2026","lastLogin":"2026-09-27T08:30:00Z"}
(phone omitted because it is null; internalNotes never serialised)
Global configuration with properties and a JsonMapperBuilderCustomizer
# application.yml
spring:
jackson:
property-naming-strategy: SNAKE_CASE
default-property-inclusion: non_null
serialization:
indent-output: true # pretty-print (development only)
@Configuration
public class JacksonConfig {
@Bean
JsonMapperBuilderCustomizer jsonCustomizer() {
return builder -> builder
.enable(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES)
.defaultTimeZone(TimeZone.getTimeZone("Asia/Kolkata"));
}
}
{
"id" : 7,
"full_name" : "Asha Rao",
"email" : "asha@webnest.in"
}
A custom serializer registered with @JacksonComponent
// Serialise Money as {"amount":"1299.00","currency":"INR","display":"₹1,299.00"}
public record Money(BigDecimal amount, Currency currency) {}
@JacksonComponent
public class MoneyJson {
public static class Serializer extends ValueSerializer<Money> {
@Override
public void serialize(Money value, JsonGenerator gen, SerializationContext ctxt) {
NumberFormat fmt = NumberFormat.getCurrencyInstance(Locale.of("en", "IN"));
fmt.setCurrency(value.currency());
gen.writeStartObject();
gen.writeStringProperty("amount", value.amount().setScale(2).toPlainString());
gen.writeStringProperty("currency", value.currency().getCurrencyCode());
gen.writeStringProperty("display", fmt.format(value.amount()));
gen.writeEndObject();
}
}
}
{"price":{"amount":"1299.00","currency":"INR","display":"₹1,299.00"}}
Polymorphic JSON and using JsonMapper directly
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
@JsonSubTypes({
@JsonSubTypes.Type(value = CardPayment.class, name = "card"),
@JsonSubTypes.Type(value = UpiPayment.class, name = "upi")
})
public sealed interface Payment permits CardPayment, UpiPayment {}
public record CardPayment(String last4, String network) implements Payment {}
public record UpiPayment(String vpa) implements Payment {}
@Component
public class PaymentParser {
private final JsonMapper mapper; // tools.jackson.databind.json.JsonMapper (auto-configured)
public PaymentParser(JsonMapper mapper) {
this.mapper = mapper;
}
public Payment parse(String json) {
return mapper.readValue(json, Payment.class); // no checked IOException in Jackson 3
}
}
paymentParser.parse("""
{"type": "upi", "vpa": "asha@okbank"}
""");
UpiPayment[vpa=asha@okbank]
Common Mistakes
- Importing com.fasterxml.jackson.databind.ObjectMapper in a Spring Boot 4 app and getting a different (Jackson 2) mapper than Spring MVC uses; inject tools.jackson JsonMapper instead.
- Declaring a Jackson2ObjectMapperBuilderCustomizer in Boot 4 and wondering why it has no effect — use JsonMapperBuilderCustomizer.
- Returning JPA entities directly and leaking internal fields or triggering lazy-loading exceptions.
- Using the old spring.jackson.read.* / spring.jackson.write.* keys for JSON parser/generator features; in Spring Boot 4 they moved under spring.jackson.json.read.* and spring.jackson.json.write.*.
- Leaving indent-output enabled in production, increasing response size.
Exercise
Using the lesson's A DTO shaped with Jackson annotations example, create a small implementation or design sketch that demonstrates Spring Boot 4 uses Jackson 3: core classes live in tools.jackson, annotations stay in com.fasterxml.jackson.annotation.. Add a test case or scenario that would catch Importing com.fasterxml.jackson.databind.ObjectMapper in a Spring Boot 4 app and getting a different (Jackson 2) mapper than Spring MVC uses; inject tools.jackson JsonMapper instead., and describe the expected result.
Show hints
- Start with What Changed in Jackson 3 and compare your approach with A DTO shaped with Jackson annotations. Identify the decision or behavior the lesson recommends.
- Walk through your scenario step by step. Confirm that it follows Spring Boot 4 uses Jackson 3: core classes live in tools.jackson, annotations stay in com.fasterxml.jackson.annotation. and that it would catch the failure described by Importing com.fasterxml.jackson.databind.ObjectMapper in a Spring Boot 4 app and getting a different (Jackson 2) mapper than Spring MVC uses; inject tools.jackson JsonMapper instead..
Quick quiz
1. Which choice is a mistake to avoid in JSON with Jackson 3?
- A. Declaring a Jackson2ObjectMapperBuilderCustomizer in Boot 4 and wondering why it has no effect — use JsonMapperBuilderCustomizer.
- B. Spring Boot 4 uses Jackson 3: core classes live in tools.jackson, annotations stay in com.fasterxml.jackson.annotation.
- C. Importing com.fasterxml.jackson.databind.ObjectMapper in a Spring Boot 4 app and getting a different (Jackson 2) mapper than Spring MVC uses; inject tools.jackson JsonMapper instead.
Show answer
C. Avoid this approach: Importing com.fasterxml.jackson.databind.ObjectMapper in a Spring Boot 4 app and getting a different (Jackson 2) mapper than Spring MVC uses; inject tools.jackson JsonMapper instead. The lesson recommends: Spring Boot 4 uses Jackson 3: core classes live in tools.jackson, annotations stay in com.fasterxml.jackson.annotation.
Interview questions
A teammate is about to make this mistake: Importing com.fasterxml.jackson.databind.ObjectMapper in a Spring Boot 4 app and getting a different (Jackson 2) mapper than Spring MVC uses; inject tools.jackson JsonMapper instead. How would you diagnose and correct it using the lesson's guidance?
Show answer
Spring Boot 4 uses Jackson 3: core classes live in tools.jackson, annotations stay in com.fasterxml.jackson.annotation. Apply this in What Changed in Jackson 3; the example A DTO shaped with Jackson annotations shows one way to do it. Avoid Importing com.fasterxml.jackson.databind.ObjectMapper in a Spring Boot 4 app and getting a different (Jackson 2) mapper than Spring MVC uses; inject tools.jackson JsonMapper instead. and explain how your implementation or design prevents that failure.
Key Points to Remember
- Spring Boot 4 uses Jackson 3: core classes live in tools.jackson, annotations stay in com.fasterxml.jackson.annotation.
- JsonMapper is immutable and built with builders; Jackson exceptions are unchecked.
- Configure with spring.jackson.* properties or a JsonMapperBuilderCustomizer bean.
- Use @JsonProperty, @JsonInclude, @JsonFormat and @JsonIgnore to define the JSON contract on DTOs.
- @JacksonComponent registers custom serializers; @JsonTypeInfo handles polymorphic JSON.
Practice in the playground
Write and run your own code for this topic, or start from the exercise or an example. Runs plain Java 17. Frameworks such as Spring, and databases, are not available here. Your code for each topic is kept in this browser.
Run the examples
Change an input, predict the result, then compare it with the output. Explain why the result changes.
These examples need a JDK project with their libraries on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.
Written by
WebNest Studio Engineering Team
Practical lessons from developers working with Java, Python, React, databases and production systems.
Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering