zjsonpatch

The library supports extended JSON pointers that allow referencing array elements via a unique key instead of a numeric index. This is useful for targeting specific objects within an array.

Syntax: /array/key=value/path (e.g., /a/id=2/data)

Requirements & Warnings:

• You must ensure the field used as a reference key is unique.
• If multiple elements match the key-value pair, the first matching element is selected.
• Key-based referencing can be slow for large arrays; use standard index-based pointers for performance in those cases.

// Example: Accessing data in an array of objects via ID
// JSON: {"a": [{"id": 1, "data": "abc"}, {"id": 2, "data": "def"}]}
// Path: /a/id=2/data
// Result: "def"

Because Jackson 2.x and 3.x use incompatible package structures, zjsonpatch provides two distinct sets of public APIs. You must use the class set that matches the Jackson version present on your classpath:

• For Jackson 2.x: Use JsonDiff and JsonPatch.
• For Jackson 3.x: Use Jackson3JsonDiff and Jackson3JsonPatch.

The library internally detects the specific JsonNode types to ensure correct operation even in mixed-version scenarios.

In version 0.6.0, Jackson dependencies were changed from transitive to optional. If your project relied on zjsonpatch to provide Jackson, you will encounter compilation errors. You must now explicitly add jackson-databind to your pom.xml to resolve this.

<!-- Add this to your pom.xml dependencies -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.18.2</version>
</dependency>

By default, the library optimizes diffs by compacting move and remove operations into Move operations. To prevent this optimization and return standard operations, use DiffFlags.dontNormalizeOpIntoMoveAndCopy().

### Jackson 2.x API
EnumSet<DiffFlags> flags = DiffFlags.dontNormalizeOpIntoMoveAndCopy().clone();
JsonNode patch = JsonDiff.asJson(JsonNode source, JsonNode target, flags);

### Jackson 3.x API
EnumSet<DiffFlags> flags = DiffFlags.dontNormalizeOpIntoMoveAndCopy().clone();
JsonNode patch = Jackson3JsonDiff.asJson(JsonNode source, JsonNode target, flags);

Mutate the source JSON document directly by applying the patch. This is more memory-efficient than .apply() but modifies the original object.

Limitations: This is an extension to RFC 6902 and does not support operations that require the source document to be fully changed in place (due to Jackson mutability constraints). The following operations are not supported for in-place application:

• remove with an empty or root path
• replace with an empty or root path
• move, add, or copy targeting an empty or root path

### Jackson 2.x API
JsonPatch.applyInPlace(JsonNode patch, JsonNode source);

### Jackson 3.x API
Jackson3JsonPatch.applyInPlace(JsonNode patch, JsonNode source);

Apply a generated patch to a source JSON document to produce a target document.

Note: The standard .apply() method performs the operation on a clone of the source, meaning the original source object remains unmodified.

### Jackson 2.x API
JsonNode target = JsonPatch.apply(JsonNode patch, JsonNode source);

### Jackson 3.x API
JsonNode target = Jackson3JsonPatch.apply(JsonNode patch, JsonNode source);

Compute a JSON patch that, when applied to a source document, will transform it into the target document. Both source and target must be valid JSON objects, arrays, or values.

Supported operations in the generated patch include add, remove, replace, move, and copy.

### Jackson 2.x API
JsonNode patch = JsonDiff.asJson(JsonNode source, JsonNode target)

### Jackson 3.x API
JsonNode patch = Jackson3JsonDiff.asJson(JsonNode source, JsonNode target)

The Diff class provides static factory methods to create individual JSON Patch operations. These operations represent changes like replace, add, remove, move, or copy as defined in RFC 6902. Note that while the class is package-private in this file, it is the primary structure used to represent a single patch operation within the library.

// Example of generating a replace operation
Diff diff = Diff.generateDiff(
    Operation.REPLACE, 
    path, 
    targetValue
);

// Example of generating a replace operation with source value
Diff diffWithSource = Diff.generateDiff(
    Operation.REPLACE, 
    path, 
    sourceValue, 
    targetValue
);

Once a Diff object is created, you can inspect the details of the patch operation using the following methods:

• getOperation(): Returns the type of operation (e.g., add, remove, replace, move, copy).
• getPath(): Returns the AbstractJsonPointer representing the location of the operation.
• getValue(): Returns the JsonNodeWrapper containing the value associated with the operation (used for add and replace).
• getSrcValue(): Returns the JsonNodeWrapper containing the original value (used specifically in replace operations).
• getToPath(): Returns the AbstractJsonPointer destination (used specifically for move operations).