{"id":4065,"library":"jsonmerge","title":"JSON Merge (Python)","description":"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).","status":"active","version":"1.9.2","language":"en","source_language":"en","source_url":"https://github.com/avian2/jsonmerge","tags":["json","merge","schema","configuration","data processing"],"install":[{"cmd":"pip install jsonmerge","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for schema validation and processing merge strategies.","package":"jsonschema","optional":false}],"imports":[{"symbol":"merge","correct":"from jsonmerge import merge"},{"symbol":"Merger","correct":"from jsonmerge import Merger"}],"quickstart":{"code":"import json\nfrom jsonmerge import merge, Merger\n\n# Basic merge without a schema (uses default objectMerge and overwrite strategies)\nbase = {\"name\": \"John\", \"details\": {\"age\": 30, \"city\": \"New York\"}, \"tags\": [\"active\", \"premium\"]}\nhead = {\"details\": {\"age\": 31, \"country\": \"USA\"}, \"occupation\": \"Engineer\", \"tags\": [\"vip\"]}\n\nresult_basic = merge(base, head)\nprint(f\"Basic merge: {json.dumps(result_basic, indent=2)}\")\n\n# Merge with a schema to define specific strategies, e.g., 'append' for arrays\nschema = {\n    \"properties\": {\n        \"tags\": {\n            \"mergeStrategy\": \"append\"\n        }\n    }\n}\n\nmerger = Merger(schema)\nresult_schema = merger.merge(base, head)\nprint(f\"\\nSchema-driven merge (append tags): {json.dumps(result_schema, indent=2)}\")","lang":"python","description":"Demonstrates both the simple `merge` function for default behavior and the `Merger` class for schema-driven merging, specifically using the 'append' strategy for arrays."},"warnings":[{"fix":"For schemas based on newer drafts, initialize `Merger` with `Merger(schema, validatorclass=jsonschema.Draft7Validator)` (or the appropriate validator class for your draft version).","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your project runs on Python 3.5 or a more recent version.","message":"Support 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.","severity":"breaking","affected_versions":">=1.9.2"},{"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.","message":"If 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the latest documentation for alternatives or updated usage if you rely on adding metadata with the `version` strategy.","message":"The `meta` argument for the `version` merge strategy (used to supply document metadata for each version of a field) has been deprecated.","severity":"deprecated","affected_versions":"<1.9.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}