SerdeProof

See how your JSON changes before moving to Jackson 3 or Spring Boot 4.

Spring Boot 4.0 and Spring Framework 7.0 make Jackson 3 the default. Jackson 3 writes dates as ISO-8601 strings instead of timestamps and sorts properties alphabetically (Spring blog). SerdeProof runs your own DTOs, mapper settings and sample payloads on both versions, each in its own JVM, and reports:

• which payloads one version accepts and the other rejects,
• which values in the JSON output changed, such as a date that became a string,
• whether JSON written by one version can still be read by the other.

It compares JSON by structure and value, so a failing snapshot test caused only by the new property order shows up as no difference. Use it as a CI gate while you upgrade: approve the changes you expect, with a reason and an expiry date, and the build fails only on new ones.

java -jar lib/serdeproof-cli-0.1.1.jar run --manifest serdeproof.json \
  --json reports/run.json --junit reports/run.xml --markdown reports/summary.md

--markdown writes a short summary for a pull request or a GitHub Actions job summary (--markdown "$GITHUB_STEP_SUMMARY" --force).

Try the release without building

Download serdeproof-0.1.1.zip and SHA256SUMS from Releases, verify the archive's SHA-256, and extract the whole archive. With Java 17+ installed, open a terminal inside the extracted serdeproof-0.1.1 folder and run:

java -jar lib/serdeproof-cli-0.1.1.jar run --manifest examples/release-demo.json --json reports/first.json --junit reports/first.xml --as-of 2026-10-08

The command intentionally exits 1: the example Jackson 2 → 3 payloads have differences to review. Add --markdown reports/first.md for a readable summary, or open reports/first.json: its summary should show 17 fixtures processed, 12 unexpected differences, 5 untested fixtures and 0 infrastructure errors. Each fixture includes four producer/consumer checks. Exit 2 means the experiment could not complete, not an ordinary migration finding. The same command works on PowerShell as one line.

The demo result was reproduced on macOS arm64 with Java 17 on 2026-10-12. Use 0.1.1 or later for the process-ownership fix described in the changelog. No Maven install or hosted service is needed for this release demo. Keep all lib/ JARs together; copying only the CLI JAR does not supply the demo adapters. Reports default to hashed identities; --details reveals fixture IDs, paths within JSON and rule metadata. Neither mode writes fixture payload values. Choose new report filenames for another run, or explicitly use --force to replace reports you have reviewed. See the examples guide to interpret acceptance, roundtrip loss and reviewed exceptions.

Build and adapt the maintained example

Install a JDK 17 or newer and run these commands from a source checkout (or the release ZIP's source/ directory). The Maven wrapper downloads pinned Maven 3.9.11 from Maven Central.

./mvnw -B -ntp clean install
python3 scripts/smoke.py
java -jar serdeproof-cli/target/serdeproof-cli-0.1.1.jar run \
  --manifest examples/demo.json --json reports/demo.json --junit reports/demo.xml \
  --as-of 2026-10-08 --details

On Windows PowerShell use .\mvnw.cmd and python; the java command is identical when written on one line. The demo intentionally finds differences, so the last command exits 1. Exit 2 means an incomplete or invalid experiment; it must not be treated as a compatibility finding. For another run, choose fresh report filenames or add --force to replace the previous reports.

The GitHub release distributes a ZIP and standalone executable JARs. Unzip the ZIP and use its lib/serdeproof-cli-0.1.1.jar with examples/release-demo.json. Release assets are unsigned and not notarized. Coordinates are installed locally by mvn install; they are not published to Maven Central.

Bring your DTO and mapper

Implement the dependency-free SerializerAdapter in a tiny test-support module compiled twice, once for each application's dependency version. This Jackson 2 sketch keeps mapper definition failures separate from payload rejection:

public AdapterResult evaluate(String type, byte[] input, byte[] configuration)
        throws Exception {
    Order dto;
    try {
        dto = serviceMapper.readValue(input, Order.class);
    } catch (InvalidDefinitionException mapperFailure) {
        throw mapperFailure;
    } catch (JsonProcessingException invalidPayload) {
        throw new RejectedInputException();
    }
    return new AdapterResult(serviceMapper.writeValueAsBytes(dto),
                             observeOrder(dto));
}

output is what your real serializer writes. observation is JSON describing the domain facts you care about—for example the instant, enum identity and exact amount. Keep observations stable across versions and include relevant fields. Unexpected exceptions are infrastructure failures, not accepted rejections. The complete custom adapter example includes the DTO, a custom mapper module, the adapter, and a library caller. The install smoke compiles and executes it against installed artifacts.

Configure explicit classpath entries for each version in the manifest. Paths are relative to that manifest and may contain spaces or Unicode. Do not put both versions of Jackson in one adapter classpath. No shell command, server, database, hosted service or credentials are required.

This is the beginning of the README. Read the rest at the original. Read the full README ↗