zjsonpatch: RFC 6902 JSON Patch for Java, on Jackson 2 or Jackson 3

Sending the difference instead of the whole document

zjsonpatch is an implementation of RFC 6902 JSON Patch written in Java, with extended JSON pointer support, and the project description is exactly that.

The use case the README spells out is bandwidth. JSON Patch defines a JSON document structure for representing changes to a JSON document, and using it avoids sending a whole document when only a part has changed, which reduces network requirements when JSON data travels between systems or across data centres.

The standard framing matters here, because it is what makes the output usable by anything. Combined with the HTTP PATCH method as described in RFC 5789, it performs partial updates on HTTP APIs in a way that is not vendor specific. A patch produced here is a list of operations in the RFC's own format, and any client that understands RFC 6902 can apply it, not only a Java one.

What the library adds on top of the specification is a pointer extension. A standard JSON pointer addresses array elements by index, which is fragile when the array is reordered between the two documents. The extension allows an element to be addressed by a key value pair, in the form /array/id=123/data.

The trade is stated clearly in the README. The user has to ensure that a unique field is used as the reference key, and if more than one array element matches the key value pair, the first element is selected. Key based referencing may be slow for large arrays, and the README advises using standard index based pointers for those.

The project is Apache-2.0 licensed, requires Java 17 or newer, and lives under the io.github.vishwakarma group id from version 0.5.0 onwards, with the older com.flipkart coordinates still published for 0.4.16 and below.

Two Jackson APIs, because one classpath holds one Jackson

The Jackson support is the most consequential design decision in the library, and the README explains it in unusually direct terms.

Both Jackson 2.x and Jackson 3.x are supported. Jackson 2.x means the com.fasterxml.jackson APIs, and Jackson 3.x means full compatibility through the tools.jackson APIs. The two can coexist as optional dependencies.

The public API mirrors that split. For Jackson 2.x you use JsonDiff and JsonPatch, and for Jackson 3.x you use Jackson3JsonDiff and Jackson3JsonPatch. The README gives the reason: the original public API is based on Jackson 2.x types and cannot be changed without breaking compatibility, and a unified API containing both is not possible since only one Jackson version may be on the classpath and the two use incompatible package structures.

The library then does something slightly clever to soften the split. Each API automatically uses its corresponding Jackson version internally, and the library detects the actual version of nodes by checking whether they are instances of specific JsonNode types, handling inheritance properly and working correctly even in mixed version scenarios.

So the practical rule for an adopter is simple and worth memorising: pick the class that matches your Jackson, and do not mix them. The cost is a slightly larger API surface, and the benefit is that adopting the library does not force a Jackson major version upgrade on a project that has already moved to 3.x.

The 0.6.0 change that breaks builds

Version 0.6.0 made every Jackson dependency optional, and the README has a dedicated section on the breaking change, which is a good sign about how the maintainers handle upgrades.

The reason given is to let consumers choose between Jackson 2.x and Jackson 3.x. All Jackson dependencies are marked as optional so that the choice belongs to the project using the library, and the listed motivations are preventing version conflicts when projects use different Jackson versions, allowing an explicit choice between the two, providing cleaner dependency management for consumers, and enabling Jackson 3.x support without forcing version upgrades.

The migration consequence is direct. If you were relying on zjsonpatch to transitively provide Jackson, you must add Jackson to your own pom.xml:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.18.2</version>
</dependency>

The README states the impact plainly: projects that do not explicitly declare Jackson dependencies will get compilation errors until Jackson is added to their dependencies.

That is a hard break for anyone upgrading without reading the notes, and it is worth checking your dependency tree before you bump the version rather than after the build turns red.

For a new project the choice is a pom.xml decision, and the README gives the three cases. Jackson 2.x only, Jackson 3.x only with tools.jackson.core jackson-databind at 3.0.0, or both, with the two databind dependencies declared together. The library itself is added to the dependencies section as io.github.vishwakarma with artifact zjsonpatch and a version placeholder, since the current version is stated separately as 0.6.3.

Diffing and applying, two static calls

The API surface for the actual work is small, which is what you want from a library that other people will call from request handlers.

Computing a patch with Jackson 2.x:

JsonNode patch = JsonDiff.asJson(JsonNode source, JsonNode target)

and with Jackson 3.x:

JsonNode patch = Jackson3JsonDiff.asJson(JsonNode source, JsonNode target)

Both source and target must be valid JSON objects or arrays, or values, and the README states the property that matters in practice: if the resulting patch is applied to source, it yields target.

The generated operations are the ones RFC 6902 defines, namely add, remove, replace, move and copy. Move and copy are worth noting because they are the operations that make a patch smaller, and the library also has a compaction step that rewrites some move and remove pairs into a single move operation, which the topics list refers to as compaction.

Applying a patch uses the matching class, JsonPatch for Jackson 2.x and Jackson3JsonPatch for Jackson 3.x.

Because the diff is computed as a document to be applied later, the typical usage is to compute the patch on the server where both versions are available, ship the patch, and apply it wherever the target document lives. That is also why the RFC 6902 and RFC 5789 framing matters: the patch is data, not code, and it survives the hop between languages and between data centres.

Complexity, and where it stops being quadratic

The README publishes a complexity analysis, which is unusual and useful.

Finding the patch is given as two figures. It is linear in the number of keys in the two documents, and for arrays it is quadratic in the length of the array against the same key, because the difference between two JSON arrays is found with a longest common subsequence. The quadratic term is the honest cost of diffing arrays, and it is the reason the key based pointer extension is documented as slow for large arrays.

Optimising the diff, which the README describes as compacting move and remove into move, is linear in the number of diffs before compaction, and quadratic in the number of diffs in the worst case of that compaction step.

Applying the diff is linear in the number of diffs, which is the number of operations in the patch.

That gives a clear shape. Generating a patch between two large documents is not cheap, and the expensive case is arrays. Applying it is cheap, because applying is proportional to the size of the patch rather than the size of the document, which is the whole reason to send a patch in the first place.

The code coverage table is also published, and it is a useful signal about how much of the library is exercised by its own tests: 100 percent of classes, 93.6 percent of methods and 96.2 percent of lines, across six classes.

Two Maven coordinates, a CircleCI build and a gitter room

The packaging has a wrinkle that will trip up anyone following an old tutorial.

Versions 0.4.16 and below were published under the com.flipkart group id, and versions 0.5.0 and above under io.github.vishwakarma. The README links the Sonatype Central overview page for each. If you are following a tutorial or a Stack Overflow answer that says com.flipkart.zjsonpatch, that answer is out of date, and a repository that has not been updated in a while may genuinely need the older coordinate.

The release history is sparse. 0.6.0 and 0.6.2 were both published on 2025-12-15, and 0.6.3 on 2026-07-25, with the last push to the repository on 2026-10-21. A library that is stable and rarely changes is a fine thing for a format implementation, but it does mean that the interesting churn happened at 0.6.0 with the Jackson change rather than in the patch algorithm.

The repository itself is conventional: a pom.xml, src/, and a.circleci/ directory with a CircleCI badge at the top of the README. There is also a.travis.yml, a.github/ directory, a CODE_OF_CONDUCT.md, an ISSUE_TEMPLATE.md, a CONTRIBUTING.md and a _config.yml, which suggests the project is set up for GitHub as much as for CircleCI.

The community channel is a Gitter room, which is the older of the two options, and the topics list jsondiff, jsondiffpatch and compaction alongside json, jsonpatch and json-document, which is a reasonable description of the problem this library occupies next to the other JSON diff libraries that exist.

Editorial conclusion

zjsonpatch suits Java teams that exchange JSON documents between services or between data centres and want to send only the difference, and it suits teams already on Jackson 3.x who cannot take a library that forces Jackson 2.x types. It does not suit a project that needs a patch to be applied by a non-Java client, since the output is standard RFC 6902 but the library itself is Java only, and it does not suit you if you expect array diffing to be fast, because the README states the array comparison is quadratic. Check three things before you adopt it: which Jackson version your project has, because the API class names differ and the wrong one will not compile, whether the 0.6.0 optional dependency change has already broken your build, and whether your documents contain large arrays, where the key based pointer extension is documented to be slow. The newest release is 0.6.3 from 2026-07-25 and the last push to the repository was on 2026-10-21.

Frequently asked questions

Official sources

1. flipkart-incubator/zjsonpatch on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases