Registry / serialization / json-merge-patch

json-merge-patch

JSON →
library0.3.0pypypi✓ verified 24d ago

This library provides functions to merge JSON documents in accordance with RFC 7386, the JSON Merge Patch standard. It offers a simpler alternative to JSON Patch for updating JSON resources, especially for object-based modifications. The current version is 0.3.0, with a focus on implementing the standard without external dependencies beyond the standard library.

pip install json-merge-patch
INSTALL
IMPORT
SIG · JSON-MERGE-PATCH
J
json-merge-patch
serializationpythonv0.3.0
Install
1.6s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

json_merge_patch
import json_merge_patch
merge
import json_merge_patch json_merge_patch.merge(document, patch)
create_patch
import json_merge_patch json_merge_patch.create_patch(original, target)

This example demonstrates how to apply a JSON merge patch to a document and how to generate a patch document by comparing an original and a target document. Note that the library expects and returns Python dictionaries; JSON serialization/deserialization is the user's responsibility.

import json import json_merge_patch document = {"a": 1, "b": 2, "c": {"d": 4}} patch = {"a": 2, "c": {"e": 5}, "f": None} # Applying a merge patch # 'f': None in patch implies deletion of 'f' if it existed, otherwise ignored # 'c': {'e': 5} replaces the entire 'c' object result = json_merge_patch.merge(document, patch) print(f"Merged result: {json.dumps(result, indent=2)}") # Expected output: {'a': 2, 'b': 2, 'c': {'e': 5}} original = {"name": "Alice", "details": {"age": 30, "city": "NY"}, "tags": ["A", "B"]} target = {"name": "Bob", "details": {"age": 31}, "email": "bob@example.com", "tags": ["C"]} # Creating a merge patch # 'name': 'Bob' replaces 'Alice' # 'details': {'age': 31} replaces the entire 'details' object (city is removed) # 'email': 'bob@example.com' is added # 'tags': ['C'] replaces the entire 'tags' array patch_doc = json_merge_patch.create_patch(original, target) print(f"Generated patch: {json.dumps(patch_doc, indent=2)}") # Expected output: {'name': 'Bob', 'details': {'age': 31}, 'email': 'bob@example.com', 'tags': ['C']}
Debug
Known issues
gotchaJSON Merge Patch (RFC 7386) does not support granular modification of array elements. To change an array, you must provide the complete new array in the patch, replacing the entire original array. Individual elements cannot be added, removed, or modified directly within the array without sending the whole new array.
fix
If granular array operations are needed, consider using JSON Patch (RFC 6902) instead, which provides 'add', 'remove', and 'replace' operations for array elements.
affects: All versions
gotchaSetting a key's value to `null` in the patch document signifies deletion of that key from the target document. It is not possible to use a JSON Merge Patch to *set* a key's value *to* `null` (unless the key did not exist, in which case it would be added and then immediately deleted).
fix
Ensure that `null` values in your patch explicitly mean deletion. If you need to set a value to `null`, JSON Merge Patch is not the appropriate mechanism, and you should use JSON Patch (RFC 6902) or a full document replacement.
affects: All versions
gotchaThe `json-merge-patch` library operates on Python dictionary objects. It does not handle JSON string loading (`json.loads`) or dumping (`json.dumps`); this responsibility lies with the user.
fix
Always parse incoming JSON strings into Python dictionaries using `json.loads()` before passing them to `json_merge_patch` functions, and convert the resulting dictionaries back to JSON strings using `json.dumps()` if needed for output or storage.
affects: All versions
breakingVersion 0.3.0 and later require Python 3.9 or higher. Earlier versions (e.g., 0.2.0 from 2017) supported older Python 3 versions (and potentially Python 2.7).
fix
Upgrade your Python environment to 3.9 or newer before updating to `json-merge-patch` version 0.3.0 or later.
affects: 0.3.0+
gotchaIf preserving key order is critical for merge operations (e.g., when using the `position` argument), inputs to the `merge` function must be `collections.OrderedDict` instances. Passing standard dictionaries will not guarantee order and may result in an error if order-dependent arguments are used.
fix
Use `collections.OrderedDict` for your input documents if key order is a requirement for your merge operation.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jsonmerge'
This error often occurs when developers intend to use the `json-merge-patch` library but either haven't installed it, or have installed it but are attempting to import a different, similarly named library (`jsonmerge`) or using an incorrect import statement for `json_merge_patch`.
fix
Ensure the correct library is installed via `pip install json-merge-patch` and imported using `import json_merge_patch` or `from json_merge_patch import merge`.
TypeError: 'str' object is not a dictionary
The `json_merge_patch.merge()` and `json_merge_patch.create_patch()` functions expect dictionary objects as their arguments (base and patch documents). Passing non-dictionary types, such as strings, integers, or lists, will result in a TypeError.
fix
Ensure that the arguments passed to `json_merge_patch.merge()` or `json_merge_patch.create_patch()` are valid Python dictionaries. If your JSON data is in string format, use `json.loads()` to parse it into a dictionary first.
json.decoder.JSONDecodeError: Expecting value: line X column Y (char Z)
This error indicates that the string being passed to `json.loads()` (a prerequisite for using `json-merge-patch` if your data starts as a string) is not a valid JSON document. Common issues include malformed syntax, missing quotes, extra commas, or other structural problems in the JSON string.
fix
Before passing JSON data to `json_merge_patch` functions, validate the JSON string to ensure it is well-formed. Use a JSON linter or validator, or carefully check for common syntax errors. Ensure that `json.loads()` successfully converts the string into a Python dictionary.
Upgrade
Version history
0.3.0latest on PyPI · released Mar 25, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
Resources
json-merge-patch — pip install json-merge-patch · libregistry