jsonmerge

library1.9.2pypypi✓ verified 23d ago

jsonmerge is a Python library designed for merging a series of JSON documents into a single document. It is particularly useful for consolidating contributions from different authors to a common document or managing consecutive versions where fields are updated over time. The library leverages JSON Schema to define and apply various merge strategies for different parts of the document. The current version is 1.9.2, with an infrequent release cadence (e.g., updates in 2017 and 2023).

serialization data

pip install jsonmerge

package ↗

INSTALL

IMPORT

SIG · JSONMERGE

jsonmerge

serializationpythonv1.9.2

Install

2.4s avg

Import

271ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.9.2 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.280s · 21.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.4s · import 0.262s · 22MB

20MB installed

● package 20MB

Code

Verified usage

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

merge

✓ from jsonmerge import merge

Merger

✓ from jsonmerge import Merger

Demonstrates both the simple `merge` function for default behavior and the `Merger` class for schema-driven merging, specifically using the 'append' strategy for arrays.

import json from jsonmerge import merge, Merger # Basic merge without a schema (uses default objectMerge and overwrite strategies) base = {"name": "John", "details": {"age": 30, "city": "New York"}, "tags": ["active", "premium"]} head = {"details": {"age": 31, "country": "USA"}, "occupation": "Engineer", "tags": ["vip"]} result_basic = merge(base, head) print(f"Basic merge: {json.dumps(result_basic, indent=2)}") # Merge with a schema to define specific strategies, e.g., 'append' for arrays schema = { "properties": { "tags": { "mergeStrategy": "append" } } } merger = Merger(schema) result_schema = merger.merge(base, head) print(f"\nSchema-driven merge (append tags): {json.dumps(result_schema, indent=2)}")

Debug

Known issues

gotchaThe library primarily uses JSON Schema Draft 4 by default for defining merge strategies. Newer JSON Schema drafts might introduce different behaviors or keywords. If you are using schemas based on a different draft, you might need to specify a compatible `jsonschema.Validator` subclass via the `validatorclass` argument in the `Merger` constructor.

fix

For schemas based on newer drafts, initialize `Merger` with `Merger(schema, validatorclass=jsonschema.Draft7Validator)` (or the appropriate validator class for your draft version).

affects: All versions

gotchaWhen using schema-driven merging, `jsonmerge` does not inherently validate input documents against the schema. It only uses the schema to determine merge strategies. Malformed input JSON or documents not conforming to the schema can lead to unexpected merge results or errors if not pre-validated.

fix

Always validate your `base` and `head` JSON documents against your merge schema using `jsonschema.validate()` *before* performing the merge operation if strict validation is required.

affects: All versions

breakingSupport for Python 2.6 has been removed. While older documentation might mention Python 2.7 support, current versions (1.9.2 and later) explicitly require Python 3.5 or newer.

fix

Ensure your project runs on Python 3.5 or a more recent version.

affects: >=1.9.2

gotchaIf your merge schema includes `allOf`, `anyOf`, or `oneOf` keywords without an explicitly defined `mergeStrategy` at that level, `jsonmerge` will raise an error (for `allOf`/`anyOf`) or attempt to find a single valid branch (for `oneOf`), raising an error if none or multiple validate.

fix

Define an explicit `mergeStrategy` keyword for schema elements that use `allOf`, `anyOf`, or `oneOf` to guide the merger's behavior in complex schema structures.

affects: All versions

deprecatedThe `meta` argument for the `version` merge strategy (used to supply document metadata for each version of a field) has been deprecated.

fix

Refer to the latest documentation for alternatives or updated usage if you rely on adding metadata with the `version` strategy.

affects: <1.9.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'jsonmerge'

The `jsonmerge` Python package is not installed in the environment where the code is being executed, or the virtual environment is not activated.

fix

Install the `jsonmerge` library using pip: `pip install jsonmerge`

Unexpected merge results / Merge strategy not applied as expected

This is a common class of problems where the output of `jsonmerge` is not what was intended. It often occurs because the provided JSON Schema is incorrect, incomplete, or the `base` and `head` documents do not strictly conform to the schema. `jsonmerge` uses the schema to determine merge strategies but does not validate the input documents against it. This can lead to default strategies being applied where custom ones were expected, or errors if complex schema keywords like `allOf` or `anyOf` are present without an explicit `mergeStrategy`.

fix

Thoroughly review your JSON schema, ensuring all relevant parts of your document have appropriate `mergeStrategy` keywords defined. For complex schema keywords like `allOf`, `anyOf`, and `oneOf`, explicitly define a merge strategy. Crucially, validate your `base` and `head` JSON documents against your schema using a dedicated validation library like `jsonschema` *before* calling `jsonmerge.merge()` to catch structural or type mismatches early.

TypeError: ('<value type>' object is not iterable, or similar type error)

This error typically arises when `jsonmerge` attempts to apply a merge strategy to data types that are incompatible with that strategy. For example, if an `objectMerge` strategy is implicitly or explicitly applied to a field where the `base` document contains a non-object type (like a string or number), and the `head` document attempts to merge an object into it, `jsonmerge` will often raise a `TypeError` because it cannot reconcile merging an object with a primitive type under that strategy.

fix

Inspect the types of data in your `base` and `head` documents at the location where the error occurs. Ensure that the merge strategy defined (or implied by default) in your schema is appropriate for the data types being merged. If merging different types is a requirement (e.g., replacing a string with an object), you may need to define a custom merge strategy or pre-process your data to ensure type compatibility before merging.

Upgrade

Version history

1.9.2latest on PyPI · released Jul 19, 2023

Audit

Dependencies

jsonschemarequiredRequired for schema validation and processing merge strategies.

Agent activity

5 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/jsonmerge/ ↗