How to Migrate Spring Boot 4.x to Jackson 3.x: Key Breaking Changes and Upgrade Guide

Major Breaking Changes

1. Package and GroupId changes

Most significant change is the complete package rename:

Old Jackson 2.x:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.JsonProcessingException;

New Jackson 3.x:

<dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>
import tools.jackson.databind.ObjectMapper;
import tools.jackson.core.JsonProcessingException;

Note: jackson-annotations remains under com.fasterxml.jackson package.

2. ObjectMapper construction change

Jackson 2.x way:

ObjectMapper mapper = new ObjectMapper();
mapper.configure(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY, true);
mapper.configure(JsonGenerator.Feature.ESCAPE_NON_ASCII, true);

Jackson 3.x forces Builder mode:

import tools.jackson.databind.json.JsonMapper;
ObjectMapper mapper = JsonMapper.builder()
    .enable(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY)
    .enable(JsonWriteFeature.ESCAPE_NON_ASCII)
    .build();

Important change: ObjectMapper and JsonFactory become immutable objects and must be created via the Builder pattern.

3. Exception handling change

Jackson 2.x:

try {
    Person person = mapper.readValue(json, Person.class);
} catch (IOException e) {
    // must catch IOException
    log.error("JSON parsing failed", e);
}

Jackson 3.x:

// JacksonException now extends RuntimeException
Person person = mapper.readValue(json, Person.class);
// no mandatory catch, optional handling only

4. API method signature changes

Feature enum renames: JsonGenerator.Feature → JsonWriteFeature, JsonParser.Feature → JsonReadFeature. Other APIs such as DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES remain unchanged and compatible.

5. Type handling changes

Generic TypeReference usage stays the same, but internal implementation is optimized.

Spring Boot 4.x Integration Impact

1. Auto‑configuration changes

Jackson auto‑configuration in Spring Boot 4.x adapts to the new API:

@Configuration
public class JacksonConfig {
    @Bean
    @Primary
    public ObjectMapper objectMapper() {
        return JsonMapper.builder()
            .enable(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY)
            .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
            .build();
    }
}

2. Spring MVC integration

Controller code remains unchanged; Spring Boot 4.x will automatically use Jackson 3.x for serialization/deserialization:

@RestController
public class ApiController {
    @PostMapping("/api/users")
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // Spring Boot 4.x will use Jackson 3.x here
        return ResponseEntity.ok(userService.create(user));
    }
}

3. Configuration property adjustments

application.yml Jackson settings need compatibility verification:

spring:
  jackson:
    serialization:
      write-dates-as-timestamps: false
    deserialization:
      fail-on-unknown-properties: false
    # some property names may change; consult the latest docs

Migration Strategy

1. Step‑by‑step migration plan

Phase 1: Dependency update

<!-- Update all Jackson related dependencies -->
<dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>3.0.0</version>
</dependency>

Phase 2: Package name replacement

com.fasterxml.jackson.databind -> tools.jackson.databind
com.fasterxml.jackson.core -> tools.jackson.core

Phase 3: Code refactoring

Convert all ObjectMapper creation to Builder mode

Remove unnecessary checked‑exception catches

Update feature configuration code to use new enums

2. Automated migration tools

Use OpenRewrite to automate the migration:

<plugin>
    <groupId>org.openrewrite.maven</groupId>
    <artifactId>rewrite-maven-plugin</artifactId>
    <version>5.40.2</version>
    <configuration>
        <activeRecipes>
            <recipe>org.openrewrite.java.jackson.UpgradeJackson_2_3</recipe>
        </activeRecipes>
    </configuration>
</plugin>

Run the migration:

mvn rewrite:run

Summary

Package name changes from com.fasterxml.jackson to tools.jackson.

ObjectMapper must be created via Builder mode.

Exception handling shifts from checked to runtime exceptions.

References

Jackson 3.0 Release Notes

Spring Framework 7.0 Jackson 3.x Support