### Example JSON patch data

Source: https://github.com/flipkart-incubator/zjsonpatch/blob/master/README.md

Sample JSON inputs and the resulting move operation patch.

```json
{"a": 0,"b": [1,2]}
```

```json
 {"b": [1,2,0]}
```

```json
[{"op":"move","from":"/a","path":"/b/2"}]
```

--------------------------------

### Extended JSON pointer example

Source: https://github.com/flipkart-incubator/zjsonpatch/blob/master/README.md

Demonstrates selecting a specific value using an extended JSON pointer path.

```json
{
  "a": [
    {
      "id": 1,
      "data": "abc"
    },
    {
      "id": 2,
      "data": "def"
    }
  ]
}
```

```jsonpath
/a/id=2/data
```

```json
"def"
```

--------------------------------

### RFC 6902 Patch Operations Reference

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Provides examples for all standard RFC 6902 operations and demonstrates an atomic update pattern using the test operation.

```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.flipkart.zjsonpatch.JsonPatch;

ObjectMapper mapper = new ObjectMapper();

// ADD: Insert value at path (or replace if path exists in object)
// Required fields: op, path, value
JsonNode addPatch = mapper.readTree("[{\"op\": \"add\", \"path\": \"/newField\", \"value\": \"hello\"}]");
JsonNode addArrayPatch = mapper.readTree("[{\"op\": \"add\", \"path\": \"/items/1\", \"value\": \"inserted\"}]");
JsonNode addEndPatch = mapper.readTree("[{\"op\": \"add\", \"path\": \"/items/-\", \"value\": \"appended\"}]");

// REMOVE: Delete value at path
// Required fields: op, path
JsonNode removePatch = mapper.readTree("[{\"op\": \"remove\", \"path\": \"/fieldToDelete\"}]");

// REPLACE: Replace value at path (path must exist)
// Required fields: op, path, value
JsonNode replacePatch = mapper.readTree("[{\"op\": \"replace\", \"path\": \"/status\", \"value\": \"updated\"}]");

// MOVE: Move value from one path to another
// Required fields: op, from, path
JsonNode movePatch = mapper.readTree("[{\"op\": \"move\", \"from\": \"/oldLocation\", \"path\": \"/newLocation\"}]");

// COPY: Copy value from one path to another
// Required fields: op, from, path
JsonNode copyPatch = mapper.readTree("[{\"op\": \"copy\", \"from\": \"/source\", \"path\": \"/duplicate\"}]");

// TEST: Verify value at path equals expected value (fails patch if not)
// Required fields: op, path, value
JsonNode testPatch = mapper.readTree("[{\"op\": \"test\", \"path\": \"/version\", \"value\": 1}]");

// Combined example: Atomic update with test-then-modify pattern
JsonNode source = mapper.readTree("{\"version\": 1, \"data\": \"original\"}");
JsonNode atomicPatch = mapper.readTree("[" +
    "{\"op\": \"test\", \"path\": \"/version\", \"value\": 1}," +  // Verify expected version
    "{\"op\": \"replace\", \"path\": \"/version\", \"value\": 2}," +  // Increment version
    "{\"op\": \"replace\", \"path\": \"/data\", \"value\": \"modified\"}" +  // Update data
"]");

try {
    JsonNode result = JsonPatch.apply(atomicPatch, source);
    System.out.println(result);
    // Output: {"version":2,"data":"modified"}
} catch (Exception e) {
    System.out.println("Patch failed - version mismatch");
}
```

--------------------------------

### Apply JSON Patch Immutably (Jackson 2.x)

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Applies a JSON patch to a source document, returning a new document. The original document remains unchanged. Includes examples for replacing, adding, and handling errors.

```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.flipkart.zjsonpatch.JsonPatch;
import com.flipkart.zjsonpatch.JsonPatchApplicationException;

ObjectMapper mapper = new ObjectMapper();

// Source document
JsonNode source = mapper.readTree("{\"name\": \"John\", \"items\": [1, 2, 3]}");

// Patch with multiple operations
JsonNode patch = mapper.readTree("[" +
    "{\"op\": \"replace\", \"path\": \"/name\", \"value\": \"Jane\"},"
    "{\"op\": \"add\", \"path\": \"/items/-\", \"value\": 4},"
    "{\"op\": \"add\", \"path\": \"/email\", \"value\": \"jane@example.com\"}"
 +"]");

// Apply patch - source remains unchanged
JsonNode result = JsonPatch.apply(patch, source);
System.out.println(result);
// Output: {"name":"Jane","items":[1,2,3,4],"email":"jane@example.com"}
System.out.println(source.get("name"));
// Output: "John" (unchanged)

// Array manipulation example
JsonNode arraySource = mapper.readTree("{\"data\": [1, 2, 3, 4]}");
JsonNode arrayPatch = mapper.readTree("[" +
    "{\"op\": \"remove\", \"path\": \"/data/1\"}," +
    "{\"op\": \"add\", \"path\": \"/data/0\", \"value\": 0}" +
    "]" );
JsonNode arrayResult = JsonPatch.apply(arrayPatch, arraySource);
System.out.println(arrayResult);
// Output: {"data":[0,1,3,4]}

// Error handling
try {
    JsonNode badPatch = mapper.readTree("[{\"op\": \"remove\", \"path\": \"/nonexistent\"}]");
    JsonPatch.apply(badPatch, source);
} catch (JsonPatchApplicationException e) {
    System.out.println("Patch failed: " + e.getMessage());
    System.out.println("Operation: " + e.getOperation());
    System.out.println("Path: " + e.getPath());
}
```

--------------------------------

### Jackson3JsonPatch.apply - Apply Patch (Jackson 3.x)

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Demonstrates how to apply JSON patches using the Jackson 3.x compatible version of JsonPatch. This includes immutable application, in-place mutation, validation, and applying patches with compatibility flags.

```APIDOC
## Jackson3JsonPatch.apply - Apply Patch (Jackson 3.x)

### Description
The Jackson 3.x compatible version of JsonPatch for applications using the `tools.jackson.*` package structure. Provides apply, applyInPlace, and validate methods.

### Method
`Jackson3JsonPatch.apply(JsonNode patch, JsonNode source)`
`Jackson3JsonPatch.applyInPlace(JsonNode patch, ObjectNode source)`
`Jackson3JsonPatch.validate(JsonNode patch)`
`Jackson3JsonPatch.apply(JsonNode patch, JsonNode source, EnumSet<CompatibilityFlags> flags)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- `patch` (JsonNode) - The JSON patch to apply.
- `source` (JsonNode) - The source JSON document.
- `source` (ObjectNode) - The mutable source JSON document for in-place application.
- `flags` (EnumSet<CompatibilityFlags>) - Optional compatibility flags.

### Request Example
```java
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.node.ObjectNode;
import com.flipkart.zjsonpatch.Jackson3JsonPatch;
import com.flipkart.zjsonpatch.CompatibilityFlags;
import com.flipkart.zjsonpatch.InvalidJsonPatchException;
import java.util.EnumSet;

ObjectMapper mapper = new ObjectMapper();

// Apply patch (immutable)
JsonNode source = mapper.readTree("{\"items\": [], \"count\": 0}");
JsonNode patch = mapper.readTree("[" +
    "{\"op\": \"add\", \"path\": \"/items/-\", \"value\": \"first\"}," +
    "{\"op\": \"replace\", \"path\": \"/count\", \"value\": 1}"
 +"]");

JsonNode result = Jackson3JsonPatch.apply(patch, source);
System.out.println(result);

// Apply in-place (mutates source)
ObjectNode mutableSource = (ObjectNode) mapper.readTree("{\"status\": \"pending\"}");
JsonNode updatePatch = mapper.readTree("[{\"op\": \"replace\", \"path\": \"/status\", \"value\": \"complete\"}]");
Jackson3JsonPatch.applyInPlace(updatePatch, mutableSource);
System.out.println(mutableSource);

// Validate patch structure
try {
    Jackson3JsonPatch.validate(patch);
    System.out.println("Patch is valid");
} catch (InvalidJsonPatchException e) {
    System.out.println("Invalid patch: " + e.getMessage());
}

// Apply with compatibility flags
EnumSet<CompatibilityFlags> flags = EnumSet.of(CompatibilityFlags.MISSING_VALUES_AS_NULLS);
JsonNode resultWithFlags = Jackson3JsonPatch.apply(patch, source, flags);
```

### Response
#### Success Response (200)
- `result` (JsonNode) - The patched JSON document (immutable apply).
- `mutableSource` (ObjectNode) - The mutated source JSON document (in-place apply).
- "Patch is valid" (String) or error message (validation).

#### Response Example
```json
{
  "items": ["first"],
  "count": 1
}
```
```json
{
  "status": "complete"
}
```
```

--------------------------------

### Apply Jackson 3.x JsonPatch

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Demonstrates immutable application, in-place mutation, validation, and the use of compatibility flags with the Jackson 3.x API.

```java
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.node.ObjectNode;
import com.flipkart.zjsonpatch.Jackson3JsonPatch;
import com.flipkart.zjsonpatch.CompatibilityFlags;
import com.flipkart.zjsonpatch.InvalidJsonPatchException;
import java.util.EnumSet;

ObjectMapper mapper = new ObjectMapper();

// Apply patch (immutable)
JsonNode source = mapper.readTree("{\"items\": [], \"count\": 0}");
JsonNode patch = mapper.readTree("[" +
    "{\"op\": \"add\", \"path\": \"/items/-\", \"value\": \"first\"}," +
    "{\"op\": \"replace\", \"path\": \"/count\", \"value\": 1}" +
"]");

JsonNode result = Jackson3JsonPatch.apply(patch, source);
System.out.println(result);
// Output: {"items":["first"],"count":1}

// Apply in-place (mutates source)
ObjectNode mutableSource = (ObjectNode) mapper.readTree("{\"status\": \"pending\"}");
JsonNode updatePatch = mapper.readTree("[{\"op\": \"replace\", \"path\": \"/status\", \"value\": \"complete\"}]");
Jackson3JsonPatch.applyInPlace(updatePatch, mutableSource);
System.out.println(mutableSource);
// Output: {"status":"complete"}

// Validate patch structure
try {
    Jackson3JsonPatch.validate(patch);
    System.out.println("Patch is valid");
} catch (InvalidJsonPatchException e) {
    System.out.println("Invalid patch: " + e.getMessage());
}

// Apply with compatibility flags
EnumSet<CompatibilityFlags> flags = EnumSet.of(CompatibilityFlags.MISSING_VALUES_AS_NULLS);
JsonNode resultWithFlags = Jackson3JsonPatch.apply(patch, source, flags);
```

--------------------------------

### Add zjsonpatch dependencies

Source: https://github.com/flipkart-incubator/zjsonpatch/blob/master/README.md

Include the library and the appropriate Jackson databind dependency for your project version.

```xml
<dependency>
    <groupId>io.github.vishwakarma</groupId>
    <artifactId>zjsonpatch</artifactId>
    <version>{version}</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.18.2</version>
</dependency>
<dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>3.0.0</version>
</dependency>
```

--------------------------------

### Maven Dependency for Jackson 2.x and 3.x

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Include this configuration for projects requiring support for both Jackson 2.x and 3.x.

```xml
<dependencies>
    <dependency>
        <groupId>io.github.vishwakarma</groupId>
        <artifactId>zjsonpatch</artifactId>
        <version>0.6.0</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.18.2</version>
    </dependency>
    <dependency>
        <groupId>tools.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>3.0.0</version>
    </dependency>
</dependencies>
```

--------------------------------

### Configure zjsonpatch dependencies

Source: https://github.com/flipkart-incubator/zjsonpatch/blob/master/README.md

Include the zjsonpatch library along with the required Jackson version in your Maven project.

```xml
<dependency>
    <groupId>io.github.vishwakarma</groupId>
    <artifactId>zjsonpatch</artifactId>
    <version>{version}</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.18.2</version>
</dependency>
```

```xml
<dependency>
    <groupId>io.github.vishwakarma</groupId>
    <artifactId>zjsonpatch</artifactId>
    <version>{version}</version>
</dependency>
<dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>3.0.0</version>
</dependency>
```

--------------------------------

### JsonPatch.apply with CompatibilityFlags

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Applies a JSON patch to a source document, with behavior modified by specific compatibility flags.

```APIDOC
## JsonPatch.apply

### Description
Applies a JSON patch to a source document. Behavior can be customized using CompatibilityFlags to handle missing values, non-existent array elements, or missing target objects.

### Parameters
- **patch** (JsonNode) - Required - The JSON Patch document to apply.
- **source** (JsonNode) - Required - The source JSON document.
- **flags** (EnumSet<CompatibilityFlags>) - Optional - Flags to control application behavior (e.g., MISSING_VALUES_AS_NULLS, REMOVE_NONE_EXISTING_ARRAY_ELEMENT, ALLOW_MISSING_TARGET_OBJECT_ON_REPLACE, FORBID_REMOVE_MISSING_OBJECT).

### Response
- **result** (JsonNode) - The resulting JSON document after applying the patch.
```

--------------------------------

### Control Patch Application with CompatibilityFlags

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Customize JSON patch application behavior using CompatibilityFlags to manage edge cases like missing values, non-existent array elements, and missing target objects during patch application.

```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.flipkart.zjsonpatch.JsonPatch;
import com.flipkart.zjsonpatch.CompatibilityFlags;
import com.flipkart.zjsonpatch.JsonPatchApplicationException;
import java.util.EnumSet;

ObjectMapper mapper = new ObjectMapper();

// MISSING_VALUES_AS_NULLS: Treat missing values as null during comparison
EnumSet<CompatibilityFlags> nullFlags = EnumSet.of(CompatibilityFlags.MISSING_VALUES_AS_NULLS);
JsonNode source = mapper.readTree("{"a": null}");
JsonNode patch = mapper.readTree("[{"op": "test", "path": "/b", "value": null}]");
// Without flag: would throw exception (path /b doesn't exist)
// With flag: treats missing /b as null, test passes
JsonNode result = JsonPatch.apply(patch, source, nullFlags);

// REMOVE_NONE_EXISTING_ARRAY_ELEMENT: Allow removing non-existent array indices
EnumSet<CompatibilityFlags> removeFlags = EnumSet.of(CompatibilityFlags.REMOVE_NONE_EXISTING_ARRAY_ELEMENT);
JsonNode arraySource = mapper.readTree("{"items": [1, 2]}");
JsonNode removePatch = mapper.readTree("[{"op": "remove", "path": "/items/5"}]");
// Without flag: throws exception (index 5 out of bounds)
// With flag: silently ignores the remove operation
JsonNode removeResult = JsonPatch.apply(removePatch, arraySource, removeFlags);

// ALLOW_MISSING_TARGET_OBJECT_ON_REPLACE: Replace creates path if missing
EnumSet<CompatibilityFlags> replaceFlags = EnumSet.of(CompatibilityFlags.ALLOW_MISSING_TARGET_OBJECT_ON_REPLACE);
JsonNode emptySource = mapper.readTree("{}");
JsonNode replacePatch = mapper.readTree("[{"op": "replace", "path": "/config/debug", "value": true}]");
// Without flag: throws exception (path /config doesn't exist)
// With flag: behaves like add operation

// FORBID_REMOVE_MISSING_OBJECT: Strict mode - fail if removing non-existent path
EnumSet<CompatibilityFlags> strictFlags = EnumSet.of(CompatibilityFlags.FORBID_REMOVE_MISSING_OBJECT);
// Use this for strict RFC 6902 compliance

// Combine multiple flags
EnumSet<CompatibilityFlags> combinedFlags = EnumSet.of(
    CompatibilityFlags.MISSING_VALUES_AS_NULLS,
    CompatibilityFlags.REMOVE_NONE_EXISTING_ARRAY_ELEMENT
);

```

--------------------------------

### JsonPatch.apply - Apply Patch to Create New Document

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Applies an RFC 6902 JSON patch to a source document and returns a new document with the changes applied. The source document remains unmodified.

```APIDOC
## JsonPatch.apply - Apply Patch to Create New Document (Jackson 2.x)

### Description
Applies an RFC 6902 JSON patch to a source document and returns a new document with the changes applied. The source document remains unmodified, making this method safe for immutable workflows.

### Method
`POST` (Conceptual - This is a library function, not a REST endpoint)

### Endpoint
`N/A`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This method operates on `JsonNode` objects representing the patch and the source document.

### Request Example
```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.flipkart.zjsonpatch.JsonPatch;
import com.flipkart.zjsonpatch.JsonPatchApplicationException;

ObjectMapper mapper = new ObjectMapper();

// Source document
JsonNode source = mapper.readTree("{\"name\": \"John\", \"items\": [1, 2, 3]}");

// Patch with multiple operations
JsonNode patch = mapper.readTree("[" +
    "{\"op\": \"replace\", \"path\": \"/name\", \"value\": \"Jane\"},"
    "{\"op\": \"add\", \"path\": \"/items/-\", \"value\": 4},"
    "{\"op\": \"add\", \"path\": \"/email\", \"value\": \"jane@example.com\"}"
"]");

// Apply patch - source remains unchanged
JsonNode result = JsonPatch.apply(patch, source);
System.out.println(result);
// Output: {"name":"Jane","items":[1,2,3,4],"email":"jane@example.com"}
System.out.println(source.get("name"));
// Output: "John" (unchanged)

// Array manipulation example
JsonNode arraySource = mapper.readTree("{\"data\": [1, 2, 3, 4]}");
JsonNode arrayPatch = mapper.readTree("[" +
    "{\"op\": \"remove\", \"path\": \"/data/1\"}," +  // Remove index 1 (value 2)
    "{\"op\": \"add\", \"path\": \"/data/0\", \"value\": 0}" +  // Insert at beginning
"]");
JsonNode arrayResult = JsonPatch.apply(arrayPatch, arraySource);
System.out.println(arrayResult);
// Output: {"data":[0,1,3,4]}

// Error handling
try {
    JsonNode badPatch = mapper.readTree("[{\"op\": \"remove\", \"path\": \"/nonexistent\"}]");
    JsonPatch.apply(badPatch, source);
} catch (JsonPatchApplicationException e) {
    System.out.println("Patch failed: " + e.getMessage());
    System.out.println("Operation: " + e.getOperation());
    System.out.println("Path: " + e.getPath());
}
```

### Response
#### Success Response (200)
Returns a new `JsonNode` representing the modified document.

#### Response Example
```json
{
  "name": "Jane",
  "items": [
    1,
    2,
    3,
    4
  ],
  "email": "jane@example.com"
}
```
```

--------------------------------

### JsonDiff.asJson with DiffFlags - Control Patch Generation Behavior

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Allows customization of how JSON patches are generated using DiffFlags. This enables fine-grained control over operations like move, copy, and the inclusion of original values.

```APIDOC
## JsonDiff.asJson with DiffFlags - Control Patch Generation Behavior

### Description
Allows customization of how patches are generated using DiffFlags. Options include omitting move/copy operations, including original values on replace operations, emitting test operations for validation, and splitting replace into remove+add pairs.

### Method
POST (conceptual, as this is a library function)

### Endpoint
N/A (Library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.flipkart.zjsonpatch.JsonDiff;
import com.flipkart.zjsonpatch.DiffFlags;
import java.util.EnumSet;

ObjectMapper mapper = new ObjectMapper();
JsonNode source = mapper.readTree("{\"age\": 10}");
JsonNode target = mapper.readTree("{\"height\": 10}");

// Disable MOVE and COPY operations - only ADD, REMOVE, REPLACE
EnumSet<DiffFlags> flags = DiffFlags.dontNormalizeOpIntoMoveAndCopy();
JsonNode patch = JsonDiff.asJson(source, target, flags);
System.out.println(patch);
// Output: [{"op":"remove","path":"/age"},{"op":"add","path":"/height","value":10}]
// Note: Without this flag, a MOVE operation would be generated

// Include original value on REPLACE operations (non-standard extension)
EnumSet<DiffFlags> replaceFlags = EnumSet.of(DiffFlags.ADD_ORIGINAL_VALUE_ON_REPLACE);
JsonNode src = mapper.readTree("{\"status\": \"pending\"}");
JsonNode tgt = mapper.readTree("{\"status\": \"complete\"}");
JsonNode diffWithOriginal = JsonDiff.asJson(src, tgt, replaceFlags);
System.out.println(diffWithOriginal);
// Output: [{"op":"replace","path":"/status","value":"complete","fromValue":"pending"}]

// Emit TEST operations for validation before each mutation
EnumSet<DiffFlags> testFlags = EnumSet.of(DiffFlags.EMIT_TEST_OPERATIONS);
JsonNode testPatch = JsonDiff.asJson(src, tgt, testFlags);
System.out.println(testPatch);
// Output includes: {"op":"test","path":"/status","value":"pending"} before replace
```

### Response
#### Success Response (200)
- **patch** (JsonNode) - An array of JSON Patch operations (RFC 6902) with custom behaviors applied based on the provided DiffFlags.

#### Response Example
```json
[
  {
    "op": "remove",
    "path": "/age"
  },
  {
    "op": "add",
    "path": "/height",
    "value": 10
  }
]
```
```

--------------------------------

### Maven Dependency for Jackson 3.x

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Add this configuration to your pom.xml for Jackson 3.x compatibility.

```xml
<dependencies>
    <dependency>
        <groupId>io.github.vishwakarma</groupId>
        <artifactId>zjsonpatch</artifactId>
        <version>0.6.0</version>
    </dependency>
    <dependency>
        <groupId>tools.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>3.0.0</version>
    </dependency>
</dependencies>
```

--------------------------------

### Maven Dependency for Jackson 2.x

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Add this configuration to your pom.xml for Jackson 2.x compatibility.

```xml
<dependencies>
    <dependency>
        <groupId>io.github.vishwakarma</groupId>
        <artifactId>zjsonpatch</artifactId>
        <version>0.6.0</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.18.2</version>
    </dependency>
</dependencies>
```

--------------------------------

### JsonPatch.applyInPlace - Apply Patch Mutating Source Document

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Applies a patch directly to the source document, modifying it in place. This is more memory efficient but has limitations: operations targeting the root path are not supported.

```APIDOC
## JsonPatch.applyInPlace - Apply Patch Mutating Source Document

### Description
Applies a patch directly to the source document, modifying it in place. This is more memory efficient than creating a new document but has limitations: operations targeting the root path are not supported.

### Method
`POST` (Conceptual - This is a library function, not a REST endpoint)

### Endpoint
`N/A`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This method operates on `JsonNode` objects representing the patch and the source document. The source document is mutated.

### Request Example
```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.flipkart.zjsonpatch.JsonPatch;

ObjectMapper mapper = new ObjectMapper();

// Create mutable source document
ObjectNode source = (ObjectNode) mapper.readTree("{\"count\": 0, \"items\": []}");

// Patch to apply
JsonNode patch = mapper.readTree("[" +
    "{\"op\": \"replace\", \"path\": \"/count\", \"value\": 1},"
    "{\"op\": \"add\", \"path\": \"/items/-\", \"value\": \"item1\"}"
"]");

// Apply in-place - source is mutated
JsonPatch.applyInPlace(patch, source);
System.out.println(source);
// Output: {"count":1,"items":["item1"]}

// Continue modifying the same document
JsonNode incrementPatch = mapper.readTree("[" +
    "{\"op\": \"replace\", \"path\": \"/count\", \"value\": 2},"
    "{\"op\": \"add\", \"path\": \"/items/-\", \"value\": \"item2\"}"
"]");
JsonPatch.applyInPlace(incrementPatch, source);
System.out.println(source);
// Output: {"count":2,"items":["item1","item2"]}

// Note: Root-level operations are NOT supported with applyInPlace
// These will throw exceptions:
// - {"op": "remove", "path": ""}
// - {"op": "replace", "path": ""}
// - {"op": "add", "path": ""}
```

### Response
#### Success Response (200)
This method modifies the source document in place and returns `void`.

#### Response Example
N/A (The source `JsonNode` is mutated directly.)
```

--------------------------------

### RFC 6902 Patch Operations Reference

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Reference for all supported RFC 6902 JSON Patch operations, including ADD, REMOVE, REPLACE, MOVE, COPY, and TEST. Details required fields and behavior for each operation.

```APIDOC
## RFC 6902 Patch Operations Reference

### Description
All supported RFC 6902 operations with their required fields and behavior. These operations work identically with both Jackson 2.x and Jackson 3.x APIs.

### Operations

#### ADD
- **Description**: Insert value at path (or replace if path exists in object).
- **Required fields**: `op`, `path`, `value`.
- **Examples**: `{"op": "add", "path": "/newField", "value": "hello"}`, `{"op": "add", "path": "/items/1", "value": "inserted"}`, `{"op": "add", "path": "/items/-", "value": "appended"}`.

#### REMOVE
- **Description**: Delete value at path.
- **Required fields**: `op`, `path`.
- **Example**: `{"op": "remove", "path": "/fieldToDelete"}`.

#### REPLACE
- **Description**: Replace value at path (path must exist).
- **Required fields**: `op`, `path`, `value`.
- **Example**: `{"op": "replace", "path": "/status", "value": "updated"}`.

#### MOVE
- **Description**: Move value from one path to another.
- **Required fields**: `op`, `from`, `path`.
- **Example**: `{"op": "move", "from": "/oldLocation", "path": "/newLocation"}`.

#### COPY
- **Description**: Copy value from one path to another.
- **Required fields**: `op`, `from`, `path`.
- **Example**: `{"op": "copy", "from": "/source", "path": "/duplicate"}`.

#### TEST
- **Description**: Verify value at path equals expected value (fails patch if not).
- **Required fields**: `op`, `path`, `value`.
- **Example**: `{"op": "test", "path": "/version", "value": 1}`.

### Request Example (Atomic Update)
```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.flipkart.zjsonpatch.JsonPatch;

ObjectMapper mapper = new ObjectMapper();

JsonNode source = mapper.readTree("{\"version\": 1, \"data\": \"original\"}");
JsonNode atomicPatch = mapper.readTree("[" +
    "{\"op\": \"test\", \"path\": \"/version\", \"value\": 1},"
 +
    "{\"op\": \"replace\", \"path\": \"/version\", \"value\": 2},"
 +
    "{\"op\": \"replace\", \"path\": \"/data\", \"value\": \"modified\"}"
 +"]");

try {
    JsonNode result = JsonPatch.apply(atomicPatch, source);
    System.out.println(result);
} catch (Exception e) {
    System.out.println("Patch failed - version mismatch");
}
```

### Response
#### Success Response (200)
- `result` (JsonNode) - The JSON document after applying the patch.

#### Response Example
```json
{
  "version": 2,
  "data": "modified"
}
```
```

--------------------------------

### Apply JSON Patch In-Place (Jackson 2.x)

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Applies a JSON patch directly to the source document, modifying it in place for memory efficiency. Root-level operations are not supported and will throw exceptions.

```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.flipkart.zjsonpatch.JsonPatch;

ObjectMapper mapper = new ObjectMapper();

// Create mutable source document
ObjectNode source = (ObjectNode) mapper.readTree("{\"count\": 0, \"items\": []}");

// Patch to apply
JsonNode patch = mapper.readTree("[" +
    "{\"op\": \"replace\", \"path\": \"/count\", \"value\": 1},"
    "{\"op\": \"add\", \"path\": \"/items/-\", \"value\": \"item1\"}"
 +"]");

// Apply in-place - source is mutated
JsonPatch.applyInPlace(patch, source);
System.out.println(source);
// Output: {"count":1,"items":["item1"]}

// Continue modifying the same document
JsonNode incrementPatch = mapper.readTree("[" +
    "{\"op\": \"replace\", \"path\": \"/count\", \"value\": 2},"
    "{\"op\": \"add\", \"path\": \"/items/-\", \"value\": \"item2\"}"
 +"]");
JsonPatch.applyInPlace(incrementPatch, source);
System.out.println(source);
// Output: {"count":2,"items":["item1","item2"]}

// Note: Root-level operations are NOT supported with applyInPlace
// These will throw exceptions:
// - {"op": "remove", "path": ""}
// - {"op": "replace", "path": ""}
// - {"op": "add", "path": ""}
```

--------------------------------

### Parse and Evaluate JSON Pointers (RFC 6901)

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Use JsonPointer.parse() to create pointers from strings and evaluate() to retrieve values from a JSON document. Supports standard and extended array referencing, and escape sequences for special characters.

```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.flipkart.zjsonpatch.JsonPointer;
import com.flipkart.zjsonpatch.JsonPointerEvaluationException;

ObjectMapper mapper = new ObjectMapper();

// Parse and use JSON pointers
JsonPointer root = JsonPointer.ROOT;  // Empty pointer - references whole document
JsonPointer fieldPtr = JsonPointer.parse("/user/name");
JsonPointer arrayPtr = JsonPointer.parse("/items/0");
JsonPointer nestedPtr = JsonPointer.parse("/data/users/0/profile/email");

// Evaluate pointers against a document
JsonNode doc = mapper.readTree("{\"user\": {\"name\": \"Alice\", \"age\": 30},\"items\": [\"a\", \"b\", \"c\"],\"scores\": {\"math\": 95, \"science\": 88}");

JsonNode name = JsonPointer.parse("/user/name").evaluate(doc);
System.out.println(name.textValue());  // Output: Alice

JsonNode firstItem = JsonPointer.parse("/items/0").evaluate(doc);
System.out.println(firstItem.textValue());  // Output: a

JsonNode lastItem = JsonPointer.parse("/items/-").evaluate(doc);  // "-" means last element
// Note: "-" is for appending in patches, evaluation may differ

// Escape sequences: ~0 = ~, ~1 = /, ~2 = =
JsonNode docWithSpecial = mapper.readTree("{\"a/b\": 1, \"c~d\": 2, \"e=f\": 3}");
JsonNode slashField = JsonPointer.parse("/a~1b").evaluate(docWithSpecial);  // a/b
JsonNode tildeField = JsonPointer.parse("/c~0d").evaluate(docWithSpecial);  // c~d
JsonNode equalsField = JsonPointer.parse("/e~2f").evaluate(docWithSpecial); // e=f (extension)
System.out.println(slashField.intValue());  // Output: 1

// Extended: Key-based array element reference
JsonNode users = mapper.readTree("{\"users\": [
    {\"id\": \"u1\", \"name\": \"Alice\"},
    {\"id\": \"u2\", \"name\": \"Bob\"},
    {\"id\": \"u3\", \"name\": \"Charlie\"}
]");

JsonNode bob = JsonPointer.parse("/users/id=u2").evaluate(users);
System.out.println(bob);  // Output: {"id":"u2","name":"Bob"}

JsonNode bobName = JsonPointer.parse("/users/id=u2/name").evaluate(users);
System.out.println(bobName.textValue());  // Output: Bob

// Error handling
try {
    JsonPointer.parse("/nonexistent/path").evaluate(doc);
} catch (JsonPointerEvaluationException e) {
    System.out.println("Path not found: " + e.getMessage());
}
```

--------------------------------

### JsonPointer.parse - Evaluate JSON Pointers

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Parses RFC 6901 JSON Pointer strings and evaluates them against JSON documents, including support for extended key-based array element referencing.

```APIDOC
## JsonPointer.parse

### Description
Parses a JSON Pointer string and evaluates it against a provided JsonNode document. Supports standard object/array access, escape sequences (~0, ~1, ~2), and key-based array element referencing.

### Parameters
#### Path Parameters
- **pointer** (String) - Required - The RFC 6901 JSON Pointer string.

### Response
#### Success Response (200)
- **JsonNode** (Object) - The node resulting from the evaluation of the pointer against the document.

### Error Handling
- Throws **JsonPointerEvaluationException** if the path does not exist in the document.
```

--------------------------------

### Apply JSON patch

Source: https://github.com/flipkart-incubator/zjsonpatch/blob/master/README.md

Apply a patch to a source JSON node to produce a new target node without modifying the original.

```java
JsonNode target = JsonPatch.apply(JsonNode patch, JsonNode source);
```

```java
JsonNode target = Jackson3JsonPatch.apply(JsonNode patch, JsonNode source);
```

--------------------------------

### Compute JSON diff as patch

Source: https://github.com/flipkart-incubator/zjsonpatch/blob/master/README.md

Generate a JSON patch representing the difference between source and target nodes.

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

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

--------------------------------

### JsonDiff.asJson - Compute JSON Patch Between Two Documents (Jackson 2.x)

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Computes the difference between two JSON documents and returns an array of RFC 6902 patch operations. This operation is useful for generating patches that can transform a source document into a target document.

```APIDOC
## JsonDiff.asJson - Compute JSON Patch Between Two Documents (Jackson 2.x)

### Description
Computes the difference between a source and target JSON document and returns an array of RFC 6902 patch operations. The resulting patch, when applied to the source document, will produce the target document. The algorithm generates optimized operations including move and copy when possible.

### Method
POST (conceptual, as this is a library function)

### Endpoint
N/A (Library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.flipkart.zjsonpatch.JsonDiff;
import com.flipkart.zjsonpatch.JsonPatch;

ObjectMapper mapper = new ObjectMapper();

// Source document
JsonNode source = mapper.readTree("{\"a\": 0, \"b\": [1, 2]}");

// Target document
JsonNode target = mapper.readTree("{\"b\": [1, 2, 0]}");

// Compute the diff - returns array of patch operations
JsonNode patch = JsonDiff.asJson(source, target);
System.out.println(patch);
// Output: [{"op":"move","from":"/a","path":"/b/2"}]

// Verify the patch produces the target when applied
JsonNode result = JsonPatch.apply(patch, source);
assert result.equals(target);

// Example with nested objects
JsonNode src = mapper.readTree("{\"user\": {\"name\": \"Alice\", \"age\": 30}}");
JsonNode tgt = mapper.readTree("{\"user\": {\"name\": \"Alice\", \"age\": 31, \"city\": \"NYC\"}}");
JsonNode diff = JsonDiff.asJson(src, tgt);
System.out.println(diff);
// Output: [{"op":"add","path":"/user/city","value":"NYC"},{"op":"replace","path":"/user/age","value":31}]
```

### Response
#### Success Response (200)
- **patch** (JsonNode) - An array of JSON Patch operations (RFC 6902) representing the differences between the source and target documents.

#### Response Example
```json
[
  {
    "op": "move",
    "from": "/a",
    "path": "/b/2"
  }
]
```
```

--------------------------------

### Apply JSON patch in-place

Source: https://github.com/flipkart-incubator/zjsonpatch/blob/master/README.md

Mutate the source JSON node directly by applying the patch.

```java
JsonPatch.applyInPlace(JsonNode patch, JsonNode source);
```

```java
Jackson3JsonPatch.applyInPlace(JsonNode patch, JsonNode source);
```

--------------------------------

### Disable move and copy operations

Source: https://github.com/flipkart-incubator/zjsonpatch/blob/master/README.md

Configure diff flags to prevent the normalization of operations into move and copy.

```java
EnumSet<DiffFlags> flags = DiffFlags.dontNormalizeOpIntoMoveAndCopy().clone();
JsonNode patch = JsonDiff.asJson(JsonNode source, JsonNode target, flags);
```

```java
EnumSet<DiffFlags> flags = DiffFlags.dontNormalizeOpIntoMoveAndCopy().clone();
JsonNode patch = Jackson3JsonDiff.asJson(JsonNode source, JsonNode target, flags);
```

--------------------------------

### Apply JSON Patch

Source: https://github.com/flipkart-incubator/zjsonpatch/blob/master/README.md

Applies a JSON patch to a source JSON node to produce a new target node or mutate the source in-place.

```APIDOC
## Apply JSON Patch

### Description
Applies a patch to a source JSON node. The standard apply method returns a new instance, while applyInPlace mutates the source node.

### Parameters
#### Request Body
- **patch** (JsonNode) - Required - The JSON patch to apply.
- **source** (JsonNode) - Required - The source JSON document.

### Response
#### Success Response (200)
- **target** (JsonNode) - The resulting JSON document after applying the patch.
```

--------------------------------

### Add Jackson dependency to pom.xml

Source: https://github.com/flipkart-incubator/zjsonpatch/blob/master/README.md

Explicitly include Jackson databind in your project dependencies as it is now an optional dependency in zjsonpatch 0.6.0.

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

--------------------------------

### Compute JSON Diff

Source: https://github.com/flipkart-incubator/zjsonpatch/blob/master/README.md

Computes a JSON patch representing the differences between a source and target JSON node.

```APIDOC
## Compute JSON Diff

### Description
Computes and returns a JSON patch from source to target. If the resultant patch is applied to the source, it will yield the target.

### Parameters
#### Request Body
- **source** (JsonNode) - Required - The original JSON document.
- **target** (JsonNode) - Required - The desired JSON document.

### Response
#### Success Response (200)
- **patch** (JsonNode) - A JSON array containing RFC 6902 operations (add, remove, replace, move, copy).
```

--------------------------------

### JsonPatch.validate

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Validates that a patch document has correct structure and valid operations according to RFC 6902 without actually applying it.

```APIDOC
## JsonPatch.validate

### Description
Validates that a patch document has correct structure and valid operations according to RFC 6902 without actually applying it. Throws InvalidJsonPatchException if the patch is malformed.

### Request Body
- **patch** (JsonNode) - Required - The JSON Patch document to validate.

### Response
- **void** - Returns nothing if valid, throws InvalidJsonPatchException if invalid.
```

--------------------------------

### Compute JSON Patch (Jackson 3.x)

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Use Jackson3JsonDiff.asJson to compute a JSON Patch between two JSON documents using Jackson 3.x types. Supports DiffFlags for customizing the diffing process.

```java
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.ObjectMapper;
import com.flipkart.zjsonpatch.Jackson3JsonDiff;
import com.flipkart.zjsonpatch.Jackson3JsonPatch;
import com.flipkart.zjsonpatch.DiffFlags;
import java.util.EnumSet;

ObjectMapper mapper = new ObjectMapper();

// Compute diff with Jackson 3.x types
JsonNode source = mapper.readTree("{\"version\": 1, \"data\": [1, 2, 3]}");
JsonNode target = mapper.readTree("{\"version\": 2, \"data\": [1, 2, 3, 4], \"new\": true}");

JsonNode patch = Jackson3JsonDiff.asJson(source, target);
System.out.println(patch);
// Output: [{"op":"add","path":"/data/-","value":4},{"op":"add","path":"/new","value":true},{"op":"replace","path":"/version","value":2}]

// With DiffFlags (same flags work for both Jackson versions)
EnumSet<DiffFlags> flags = DiffFlags.dontNormalizeOpIntoMoveAndCopy();
JsonNode patchNoMove = Jackson3JsonDiff.asJson(source, target, flags);

// Apply the patch
JsonNode result = Jackson3JsonPatch.apply(patch, source);
assert result.equals(target);
```

--------------------------------

### Customize Patch Generation with DiffFlags

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Modifies patch generation behavior, such as disabling move/copy operations or including original values, using EnumSet flags.

```java
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.flipkart.zjsonpatch.JsonDiff;
import com.flipkart.zjsonpatch.DiffFlags;
import java.util.EnumSet;

ObjectMapper mapper = new ObjectMapper();
JsonNode source = mapper.readTree("{\"age\": 10}");
JsonNode target = mapper.readTree("{\"height\": 10}");

// Disable MOVE and COPY operations - only ADD, REMOVE, REPLACE
EnumSet<DiffFlags> flags = DiffFlags.dontNormalizeOpIntoMoveAndCopy();
JsonNode patch = JsonDiff.asJson(source, target, flags);
System.out.println(patch);
// Output: [{"op":"remove","path":"/age"},{"op":"add","path":"/height","value":10}]
// Note: Without this flag, a MOVE operation would be generated

// Include original value on REPLACE operations (non-standard extension)
EnumSet<DiffFlags> replaceFlags = EnumSet.of(DiffFlags.ADD_ORIGINAL_VALUE_ON_REPLACE);
JsonNode src = mapper.readTree("{\"status\": \"pending\"}");
JsonNode tgt = mapper.readTree("{\"status\": \"complete\"}");
JsonNode diffWithOriginal = JsonDiff.asJson(src, tgt, replaceFlags);
System.out.println(diffWithOriginal);
// Output: [{"op":"replace","path":"/status","value":"complete","fromValue":"pending"}]

// Emit TEST operations for validation before each mutation
EnumSet<DiffFlags> testFlags = EnumSet.of(DiffFlags.EMIT_TEST_OPERATIONS);
JsonNode testPatch = JsonDiff.asJson(src, tgt, testFlags);
System.out.println(testPatch);
// Output includes: {"op":"test","path":"/status","value":"pending"} before replace
```

--------------------------------

### Jackson3JsonDiff.asJson - Compute JSON Patch

Source: https://context7.com/flipkart-incubator/zjsonpatch/llms.txt

Computes a JSON Patch representing the difference between two JSON documents using Jackson 3.x types.

```APIDOC
## Jackson3JsonDiff.asJson

### Description
Generates a JSON Patch (RFC 6902) by comparing a source JsonNode and a target JsonNode. This method is specifically designed for Jackson 3.x environments.

### Parameters
#### Request Body
- **source** (JsonNode) - Required - The original JSON document.
- **target** (JsonNode) - Required - The modified JSON document.
- **flags** (EnumSet<DiffFlags>) - Optional - Configuration flags to control diff behavior (e.g., normalization).

### Response
#### Success Response (200)
- **JsonNode** (Array) - A JSON array containing the patch operations (add, remove, replace, etc.).
```