jsonmerge

jsonmerge is a Python library for merging a series of JSON documents into a single combined document. It solves the common problem of reconciling contributions from multiple authors or successive versions of a document, where different fields are updated over time and simple dict updates lose information.

By default it unions object fields and replaces scalar values, but its real power is a set of merge strategies expressed as extensions to JSON Schema: you annotate your schema with keywords like arrayMergeById, append, or version to control exactly how each part of the document is combined, and it can even generate a schema describing the merged result.

What You Get

• A one-call merge(base, head, schema) function for quick document merging
• A Merger class driven by JSON Schema for fine-grained, per-field control
• Built-in merge strategies: overwrite, discard, append, arrayMergeById, arrayMergeByIndex, objectMerge, and version
• The ability to record and retain version history of merged values
• Schema generation that produces a JSON Schema describing the merged output

Common Use Cases

• Combining partial documents filled in by different authors into one complete record
• Merging successive versions of a configuration or profile while controlling which fields win
• Deep-merging arrays of objects by an id field instead of blindly replacing them
• Keeping an auditable version history of how values changed across merges

Under The Hood

Architecture - The core is the Merger class in jsonmerge/__init__.py, which walks a base and head document in parallel guided by a JSON Schema. A Walk/WalkInstance/WalkSchema traversal pairs each schema node with the corresponding data and dispatches to a named strategy from strategies.py (overwrite, append, arrayMergeById, objectMerge, version, etc.). descenders.py handles schema references ($ref, oneOf) during traversal, jsonvalue.py wraps values with their schema context, and resolver.py resolves schema URIs. A module-level merge() convenience wraps a default Merger.

Tech Stack - Pure Python built on jsonschema for JSON Schema handling and validation, packaged with setuptools and tested across environments via tox.

Code Quality - The project has a substantial test suite (test_jsonmerge.py, test_jsonvalue.py, and test_readme.py which executes the README’s doctests), a maintained ChangeLog, and clean separation between traversal, strategies, and schema resolution. It is a long-lived, stable module.

API Design - Two clear tiers: merge(base, head) for the trivial case, and a Merger(schema) object whose behavior you shape declaratively by adding merge keywords to your existing JSON Schema rather than writing imperative merge code. Strategy names are descriptive and the schema-extension approach reuses concepts users already know.