Implement Jackson3 support and maintain Jackson2 support

[smals-mavh]

Summary by cubic

Adds Jackson 3 support alongside Jackson 2 so JsonNullable works on both runtimes. Also adds a Java 17 module and updates CI to JDK 17.

• New Features

  • Jackson 3: JsonNullableJackson3Module with serializers, deserializers, type/value serializer modifiers, and unwrapping writer.
  • Auto-discovery for Jackson 3 via META-INF/services/tools.jackson.databind.JacksonModule.
  • Test coverage for both versions using Jackson2Processor and Jackson3Processor with parameterized tests.

• Refactors

  • Renamed Jackson 2 classes to JsonNullableJackson2* and wired JsonNullableModule to these implementations.
  • Split BOMs in pom.xml (jackson2-bom and jackson3-bom), added a Java 17 module, and dropped module-info “provides” in favor of service loading due to optional deps.
  • Updated GitHub Actions to JDK 17 and added explicit jackson-databind 2.x to integration tests.
  • Removed deprecated Jackson 3 API usage.

^{Written for commit 460051d. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 36 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="pom.xml">

<violation number="1" location="pom.xml:40">
P2: Jackson 3 requires Java 17+, but the build is pinned to Java 8. Adding the Jackson 3 BOM/tools.jackson dependencies will make builds fail with class file version incompatibility unless the toolchain is upgraded or Jackson 3 is isolated.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[smals-mavh]

Some extra context:

• Kept the name 'JsonNullableModule' instead of JsonNullableJackson2Module for example to keep some backwards compatibility
• The jackson library is marked as 'provided' in the pom now (to not have any jackson version conflicts downstream). The disadvantage is that users now need to add jackson to their pom.
  • On that note, we could add jackson-annotations since they're the same for both Jackson2 and Jackson3 for the moment. But might not be super future proof.
• Parameterized tests are a bit shoe-horned in some places, but to me this seemed to be the 'safest' route to make sure that all tests work with both Jackson versions.
• Tested in both Spring Boot 3 and Spring Boot 4 projects and had no issues (apart from having to add the jackson libs myself since they're not transitive anymore)

[SirBigoo]

I'm waiting this PR to be released because I can't migrate to spring 4 without breaking my app behavior... 💯

[antechrestos]

@wing328 is there any chance that this PR gets merged? This could be useful to add it once useJackson3 get supported by open api generator

[oneachoice]

I'm waiting :)

[mikomarrache]

Is there an ETA for releasing this PR? That will be very helpful for the migration to Spring Boot 4. Thanks!

[wing328]

I'll try to get it merged this week and cut a release

[wing328]

https://github.com/OpenAPITools/jackson-databind-nullable/actions/runs/21669192607/job/64654544893?pr=117

please review the build failure when you've time

[mikomarrache]

I just tested the PR and I found a regression.

The following code doesn't work - name is always undefined even if a name field is present in the JSON. It does work with release 0.2.6.

public static class Pet {
    
    @Size(max = 10)   
    public JsonNullable<String> name = JsonNullable.undefined();
    
    public Pet name(JsonNullable<String> name) {
        this.name = name;
        return this;
    }
}

The following code does work:

public static class Pet {
    
    @Size(max = 10)   
    public JsonNullable<String> name;
    
    public Pet name(JsonNullable<String> name) {
        this.name = name;
        return this;
    }
}

[pvdbosch]

I updated the PR to fix the integration tests (working together with @smals-mavh). The jackson dependencies aren't transitively added anymore, either jackson 2 or 3 has to be added explicitly. We still have to investigate the regression reported by @mikomarrache .

For projects using a module path, there's an issue: the SPI mechanism with provides can't be used to load the jackson module anymore, because it's become a choice between JsonNullableModule and JsonNullableJackson3Module, and JDK < 25 would make them both required. This is similar as #100 for Jakarta Validation.

We could support SPI from Java 25 onwards using multi-release jar, but I don't see a way to support SPI for Java 17 to 24 without making jackson 2 and 3 a mandatory dependency. Any preference on how to go forward with this or other ideas?

[smals-mavh]

@mikomarrache, could you tell a bit more about your setup. I was unable to reproduce.
The following testcase worked for me.

package org.openapitools.jackson.nullable;

import com.fasterxml.jackson.core.JsonProcessingException;
import jakarta.validation.constraints.Size;
import org.junit.jupiter.api.Test;
import tools.jackson.databind.json.JsonMapper;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

class DebugTest {

    public static class Pet {

        @Size(max = 10)
        public JsonNullable<String> name = JsonNullable.undefined();

        public Pet name(JsonNullable<String> name) {
            this.name = name;
            return this;
        }
    }

    private static String JSON = "{\"name\":\"testName\"}";

    @Test
    void petTestJackson3() {
        JsonMapper mapper = JsonMapper.builder().addModule(new JsonNullableJackson3Module()).build();
        Pet pet = mapper.readValue(JSON, Pet.class);
        assertTrue(pet.name.isPresent());
        assertEquals("testName", pet.name.get());
        assertEquals(JSON, mapper.writeValueAsString(pet));
    }

    @Test
    void petTestJackson2() throws JsonProcessingException {
        com.fasterxml.jackson.databind.json.JsonMapper mapper = new com.fasterxml.jackson.databind.json.JsonMapper();
        mapper.registerModule(new JsonNullableModule());
        Pet pet = mapper.readValue(JSON, Pet.class);
        assertTrue(pet.name.isPresent());
        assertEquals("testName", pet.name.get());
        assertEquals(JSON, mapper.writeValueAsString(pet));
    }

}

This is also more or less tested here: https://github.com/smals-mavh/jackson-databind-nullable/blob/implement-jackson3-with-jackson2-support/src/test/java/org/openapitools/jackson/nullable/JsonNullableSimpleTest.java#L134

Could you tell us more about the setup / share a reproducer?

[mikomarrache]

Sorry, my bad, I didn't explain the regression correctly. You can use this test:

package org.openapitools.jackson.nullable;

import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;

public class RegressionTest {

    public static class Pet {
        final JsonNullable<String> field1 = JsonNullable.undefined();

        public JsonNullable<String> getField1() {
            return field1;
        }
    }

    @Test
    void testJackson() throws com.fasterxml.jackson.core.JsonProcessingException {
        String json = "{\"field1\": \"value\"}";

        Pet petJackson2 = new com.fasterxml.jackson.databind.ObjectMapper()
            .registerModule(new JsonNullableModule()).readValue(json, Pet.class);

        Pet petJackson3 = tools.jackson.databind.json.JsonMapper.builder()
            .addModule(new JsonNullableJackson3Module()).build().readValue(json, Pet.class);

        assertEquals(JsonNullable.of("value"), petJackson2.getField1());
        assertEquals(JsonNullable.of("value"), petJackson3.getField1());
    }
}

[smals-mavh]

@mikomarrache , good catch!

I don't think this is really a regression in the json-nullable lib, but more a behavioral change in Jackson 3.
See config defaults changes.
Especially this issue
Apparently some changes are on its way on this matter for JDK26

Note that the jackson 2 test you provided still passes, but to let it work on jackson 3 I suppose we have two options.
1.

Pet petJackson3 = tools.jackson.databind.json.JsonMapper.builder()
                .enable(MapperFeature.ALLOW_FINAL_FIELDS_AS_MUTATORS)
                .addModule(new JsonNullableJackson3Module()).build().readValue(json, Pet.class);

But to be seen how future proof this will be.

2. annotate the class (or use records and it works automatically):

package org.openapitools.jackson.nullable;

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.MapperFeature;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;

class RegressionTest {

    public static class Pet {
        final JsonNullable<String> field1;

        public Pet() {
            field1 = JsonNullable.undefined();
        }

        public Pet(@JsonProperty("field1") JsonNullable<String> field1) {
            this.field1 = field1;
        }

        public JsonNullable<String> getField1() {
            return field1;
        }
    }

    public record OtherPet(JsonNullable<String> field1){}

    @Test
    void testJackson() throws com.fasterxml.jackson.core.JsonProcessingException {
        String json = "{\"field1\": \"value\"}";
        String undefinedJson = "{}";

        Pet petJackson2 = new com.fasterxml.jackson.databind.ObjectMapper()
                .disable(MapperFeature.ALLOW_FINAL_FIELDS_AS_MUTATORS)
                .registerModule(new JsonNullableModule()).readValue(json, Pet.class);

        OtherPet otherPetJackson2 = new com.fasterxml.jackson.databind.ObjectMapper()
                .disable(MapperFeature.ALLOW_FINAL_FIELDS_AS_MUTATORS)
                .registerModule(new JsonNullableModule()).readValue(json, OtherPet.class);

        Pet petJackson3 = tools.jackson.databind.json.JsonMapper.builder()
                .addModule(new JsonNullableJackson3Module()).build().readValue(json, Pet.class);

        OtherPet otherPetJackson3 = tools.jackson.databind.json.JsonMapper.builder()
                .addModule(new JsonNullableJackson3Module()).build().readValue(json, OtherPet.class);

        assertEquals(JsonNullable.of("value"), petJackson2.getField1());
        assertEquals(JsonNullable.of("value"), petJackson3.getField1());
        assertEquals(JsonNullable.of("value"), otherPetJackson2.field1());
        assertEquals(JsonNullable.of("value"), otherPetJackson3.field1());

        OtherPet otherPetJackson2Undefined = new com.fasterxml.jackson.databind.ObjectMapper()
                .disable(MapperFeature.ALLOW_FINAL_FIELDS_AS_MUTATORS)
                .registerModule(new JsonNullableModule()).readValue(undefinedJson, OtherPet.class);

        OtherPet otherPetJackson3Undefined = tools.jackson.databind.json.JsonMapper.builder()
                .addModule(new JsonNullableJackson3Module()).build().readValue(undefinedJson, OtherPet.class);

        assertEquals(JsonNullable.undefined(), otherPetJackson2Undefined.field1());
        assertEquals(JsonNullable.undefined(), otherPetJackson3Undefined.field1());
    }
}

I don't think this is an issue for this library, but might be an annoying behavioral change in Jackson 3.

[pvdbosch]

@wing328 , the PR should be fine now and build works. There's only a minor regression with JDK >= 17 using module-path, that the ServiceLoader mechanism doesn't work. I can't find a workaround for that, bc optional serviceloader dependencies aren't supported until JDK25.

[wing328]

thanks for the PR, which has been merged

for those looking for this feature, please help test the SNAPSHOT version to ensure it works for your use cases.

[SirBigoo]

thanks for the PR, which has been merged

for those looking for this feature, please help test the SNAPSHOT version to ensure it works for your use cases.

Just try snapshot version 0.2.10-SNAPSHOT on springboot v4 migrated project, still got my units tests failling because default serializer for Optional set Optinal.empty() and not null as before with springboot 3. Also tested directly on my running app. :(

Still working with Springboot v3 and 0.2.10-SNAPSHOT.

I'm using Java 17 / Springboot 4.0.2.

[smals-mavh]

@SirBigoo ,

Could you share a reproducer? My first guess would be a Jackson 2 / 3 behavioral change, but I can help verify if you wish.

[SirBigoo]

@SirBigoo ,

Could you share a reproducer? My first guess would be a Jackson 2 / 3 behavioral change, but I can help verify if you wish.

I investigate a little bit, it seems that the problem occurs when it exists a constructor with attribute provided. Do not have an example project to provide since I'm testing on a real project. I tested with an @RestController along with a direct autowired ObjectMapper and got same behavior (to be sure there is no component between those...). And I got same behavior when removing snapshot dependency.

There are two "regressions" on an attribute (I supposed linked due to object instance creation) when having a constructor with this attribute provided:

1. set Optional.empty() on non provided fields present in constructor during jackson deserialization insted of null
2. jakarta validation on controller (@Valid annotation processing along with @RequestBody) inside an Optional generic definition (eg. Optional<@notempty String>` are triggered even with no value provided; it was only triggered when setting a value previously and totally ignored when no value provided

I hope it's usefull, I'll try to investigate further...
I'll try a workaround by removing all constructors except no args and see if still occurs. But I'm not sure that this dependency is needed in this case; it seems that not having dependency make my following tests having same behavior).

Here is a simple test file to illustrate this behavior (only the null setting):

Test

package xxxx;

import org.junit.jupiter.api.MethodOrderer;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestMethodOrder;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.json.JsonTest;
import tools.jackson.databind.ObjectMapper;

import java.util.Optional;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;

@JsonTest
@TestMethodOrder(MethodOrderer.MethodName.class)
class ModelNoArgsJsonTest {
    @Autowired
    private ObjectMapper objectMapper;

    @Test
    void t001_no_body() { // OK
        final var model = objectMapper.readValue("{}", ModelNoArgs.class);
        assertNull(model.getTest());
    }

    @Test
    void t001_body_with_null() { // OK
        final var model = objectMapper.readValue("{\"test\":null}", ModelNoArgs.class);

        assertEquals(Optional.empty(), model.getTest());
    }

    @Test
    void t002_body_with_value() { // OK
        final var model = objectMapper.readValue("{\"test\":\"aze\"}", ModelNoArgs.class);

        assertEquals(Optional.of("aze"), model.getTest());
    }

    @Test
    void t100_no_body() { // KO = should be same result as t000
        final var model = objectMapper.readValue("{}", ModelArgs.class);

        assertNull(model.getTest());
    }

    @Test
    void t101_body_with_null() { // OK
        final var model = objectMapper.readValue("{\"test\":null}", ModelArgs.class);

        assertEquals(Optional.empty(), model.getTest());
    }

    @Test
    void t102_body_with_value() { // OK
        final var model = objectMapper.readValue("{\"test\":\"aze\"}", ModelArgs.class);

        assertEquals(Optional.of("aze"), model.getTest());
    }

    @Test
    void t200_no_body() { // KO = should be same result as t100 and it is ok for test2 value
        final var model = objectMapper.readValue("{}", ModelOneArg.class);

        assertNull(model.getTest());
        assertNull(model.getTest2());
    }

    @Test
    void t201_body_with_null() { // OK
        final var model = objectMapper.readValue("{\"test\":null}", ModelOneArg.class);

        assertEquals(Optional.empty(), model.getTest());
        assertNull(model.getTest2());
    }

    @Test
    void t202_body_with_value() { // OK
        final var model = objectMapper.readValue("{\"test\":\"aze\"}", ModelOneArg.class);

        assertEquals(Optional.of("aze"), model.getTest());
        assertNull(model.getTest2());
    }
}

Here are models used :

public class ModelNoArgs {
        protected Optional<String> test;

        public void setTest(Optional<String> test) {
            this.test = test;
        }

        public Optional<String> getTest() {
            return test;
        }
    }

    public class ModelArgs {
        protected Optional<String> test;

        public ModelArgs(Optional<String> test) {
            this.test = test;
        }

        public void setTest(Optional<String> test) {
            this.test = test;
        }

        public Optional<String> getTest() {
            return test;
        }
    }

    public class ModelOneArg {
        protected Optional<String> test;
        protected Optional<String> test2;

        public ModelOneArg(Optional<String> test) {
            this.test = test;
        }

        public void setTest(Optional<String> test) {
            this.test = test;
        }

        public Optional<String> getTest() {
            return test;
        }

        public Optional<String> getTest2() {
            return test2;
        }

        public void setTest2(Optional<String> test2) {
            this.test2 = test2;
        }
    }

[pvdbosch]

@SirBigoo , this seems related to the Jackson 3 upgrade or Spring Boot 4 rather than this module, seeing your examples don't use the @JsonNullable annotation.

On the first issue, Jackson 3.1 adds a configuration flag to map a missing property to a null value for Optional (see FasterXML/jackson-databind#5350 ); but then you'd have to override the default Jackson 3.0 version in Spring Boot 4.0 or wait on a next Spring Boot update.