JSON Merge Patch

JSON Merge Patch (RFC 7396)

The JSON Merge Patch tool applies RFC 7396 merge patches to update JSON documents using a simple, declarative format. Unlike JSON Patch (RFC 6902), which uses a list of operations, JSON Merge Patch uses a partial JSON object to describe changes. This makes it easy to update only the fields you need without sending the full document. It is commonly used in APIs for partial updates and configuration overrides.

With JSON Merge Patch, keys in the patch object overwrite or remove keys in the target JSON. A value of null indicates that a key should be removed. If the patch includes nested objects, the merge applies recursively, which allows for targeted changes deep inside a JSON structure. This tool helps you test patches, validate your results, and avoid mistakes before pushing updates into production systems.

How JSON Merge Patch works

• If a key in the patch has a non-null value, it replaces the target value.
• If a key in the patch is null, the target key is removed.
• If a key in the patch is an object, it merges recursively with the target object.
• Keys not present in the patch remain unchanged in the target.

How to use the merge patch tool

1. Paste the base JSON in the left editor.
2. Paste the merge patch JSON in the right editor.
3. Click Apply Patch to see the merged output.
4. Copy or download the result.

Example: simple merge patch

Base JSON:

{
  "id": 7,
  "name": "Avi",
  "status": "active",
  "meta": { "role": "admin", "team": "core" }
}

Merge Patch:

{
  "status": "inactive",
  "meta": { "team": "platform" }
}

Result:

{
  "id": 7,
  "name": "Avi",
  "status": "inactive",
  "meta": { "role": "admin", "team": "platform" }
}

Example: removing a field with null

Patch:

{
  "meta": { "team": null }
}

Result removes meta.team but keeps the rest of the object.

Merge Patch vs JSON Patch

JSON Merge Patch is simpler and more compact: you send a partial object describing changes. JSON Patch uses a list of operations and is more expressive (it can move, copy, and test). Use Merge Patch for straightforward updates and JSON Patch when you need precise control.

HTTP usage and content type

Many APIs accept merge patches in HTTP PATCH requests with the content type application/merge-patch+json. When sending patches, include only the fields you intend to update. This reduces payload size and avoids unintended changes.

Common errors and fixes

• Invalid JSON: Both base and patch must be valid JSON. Use JSON Validator to fix syntax.
• Unexpected deletions: A value of null deletes a key. Use explicit values if you want to keep a key with a null value.
• Wrong structure: If the patch structure does not match the target object, you may overwrite whole sections. Ensure nested objects align.
• Arrays replaced: Merge Patch replaces arrays entirely; it does not merge items by index.
• Empty output confusion: A patch that removes all keys may result in an empty object. Confirm the patch intent.

Best practices for merge patches

• Keep patches minimal and focused on changed fields.
• Use explicit values instead of nulls unless you intend deletion.
• Validate patch output before applying it in production.
• Document patch formats for API consumers.
• Use JSON Compare to review differences visually.

Merge Patch checklist

1. Validate both the base JSON and patch JSON.
2. Confirm which keys should be removed vs updated.
3. Apply the patch and compare outputs.
4. Validate the result against your schema if required.
5. Store the patch for auditing or rollback.

Behavior with arrays

Merge Patch replaces arrays entirely. If your base JSON has items and your patch includes a new items array, the entire array is replaced. This is different from JSON Patch, which can add or remove array elements by index. Use JSON Patch when you need array-level updates.

Example: removing keys safely

Base JSON:

{
  "config": { "mode": "auto", "debug": true },
  "limits": { "max": 100 }
}

Patch to remove config.debug:

{
  "config": { "debug": null }
}

Result keeps config.mode but removes debug.

Common pitfalls

• Deleting by mistake: Setting a value to null removes the key. Use explicit values when you want to keep the key with null semantics.
• Overwriting objects: A patch with a non-object value will replace the entire object at that key.
• Inconsistent data types: If the patch type differs from the base type, you may lose structure.
• Partial updates in arrays: Merge Patch cannot update a single array item; it replaces the array.

Use cases

API updates: Update only a few fields without resending the entire payload.

Configuration overrides: Apply partial overrides to configuration files.

UI settings: Save only changed preferences from a settings form.

Sync systems: Exchange small patches to keep records aligned.

FAQs

Does Merge Patch work with arrays?
Arrays are replaced as a whole. If you need array-level operations, use JSON Patch.

How do I delete a key?
Set the key to null in the patch object.

Is this the same as JSON Merge?
No. JSON Merge is a general merge strategy. JSON Merge Patch is a specific RFC format.

Is my data uploaded?
No. All processing happens locally in your browser.

Can I apply multiple patches?
Yes. Apply one patch, then use the output as the new base.

What happens to missing keys?
Missing keys in the patch remain unchanged in the base document.

Does null mean remove or set to null?
In Merge Patch, null means remove.

Can I validate the result?
Yes. Use JSON Schema Validator to validate against a schema.

Can I use Merge Patch in HTTP PATCH requests?
Yes. Many APIs accept application/merge-patch+json payloads.

Does order matter in patches?
No. Merge Patch is a single JSON object; order does not affect the outcome.

What if my patch is empty?
An empty patch returns the original document unchanged.

Do I need to send the full object?
No. Merge Patch is designed for partial updates.

Can I use Merge Patch for config files?
Yes. It is a simple way to override nested settings.