{"library":"jsondiff","title":"jsondiff","description":"jsondiff is a Python library designed to compare JSON and JSON-like structures, providing a detailed difference report. It is actively maintained, with its latest version being 2.2.1, and has a consistent release cadence with recent updates addressing bug fixes and new features.","status":"active","version":"2.2.1","language":"en","source_language":"en","source_url":"https://github.com/xlwings/jsondiff","tags":["json","diff","comparison","data structures","utility"],"install":[{"cmd":"pip install jsondiff","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.8 or newer.","package":"python","optional":false}],"imports":[{"note":"The primary function for comparing JSON objects.","symbol":"diff","correct":"from jsondiff import diff"},{"note":"Used to access special symbols for diff output (e.g., 'insert', 'delete', 'update') when using explicit syntax.","symbol":"symbols","correct":"from jsondiff import symbols"}],"quickstart":{"code":"from jsondiff import diff, symbols\n\njson1 = {\n    \"name\": \"Alice\",\n    \"age\": 25,\n    \"city\": \"New York\",\n    \"hobbies\": [\"reading\", \"hiking\", \"coding\"]\n}\n\njson2 = {\n    \"name\": \"Bob\",\n    \"age\": 30,\n    \"city\": \"London\",\n    \"occupation\": \"Engineer\",\n    \"hobbies\": [\"reading\", \"running\", \"coding\"]\n}\n\n# Basic diff (compact syntax by default)\ncompact_diff = diff(json1, json2)\nprint(\"Compact Diff:\", compact_diff)\n\n# Explicit diff (more detailed output with symbols)\nexplicit_diff = diff(json1, json2, syntax='explicit')\nprint(\"\\nExplicit Diff:\", explicit_diff)\n\n# Accessing specific changes using symbols\nif symbols.insert in explicit_diff:\n    print(\"  Inserted keys:\", explicit_diff[symbols.insert])\nif symbols.delete in explicit_diff:\n    print(\"  Deleted keys:\", explicit_diff[symbols.delete])\nif symbols.update in explicit_diff:\n    print(\"  Updated keys:\", explicit_diff[symbols.update])\n","lang":"python","description":"This quickstart demonstrates how to use `jsondiff.diff` to compare two JSON objects. It shows both the default compact output and the more verbose 'explicit' syntax, which leverages `jsondiff.symbols` to clearly identify insertions, deletions, and updates within the JSON structures."},"warnings":[{"fix":"For CLI usage, install `jdiff` if available, or use the library programmatically. For example, `pip install jdiff` (note: `jdiff` is a separate package, ensure it matches your intended use) or integrate `from jsondiff import diff` into your Python scripts.","message":"The command-line interface (CLI) for `jsondiff` underwent breaking changes. The `jsondiff` command was deprecated in v1.2.0 in favor of `jdiff` and then entirely removed in v2.0.0. Users relying on the old CLI must switch to `jdiff` or implement programmatically.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Upgrade your Python environment to version 3.8 or newer. Alternatively, pin your `jsondiff` dependency to `<2.1.2`.","message":"Support for Python versions prior to 3.8 was officially dropped in version 2.1.2. Users on Python 3.7 or older will encounter installation or runtime errors.","severity":"breaking","affected_versions":">=2.1.2"},{"fix":"Always consider explicitly setting `syntax='explicit'` for a more detailed and unambiguous diff report, especially for complex objects. This allows direct access to `symbols.insert`, `symbols.delete`, and `symbols.update`.","message":"The `diff` function supports different output syntaxes: 'compact' (default), 'symmetric', and 'explicit'. The default 'compact' syntax may not always clearly distinguish between added/removed keys vs. changed values, which can be a source of confusion.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For versions 2.2.0 and later, use the `exclude_paths` argument in the `diff` function (e.g., `diff(json1, json2, exclude_paths=['root.timestamp'])`). For older versions, filter the diff result manually.","message":"Version 2.2.0 introduced the ability to exclude specific paths from the diff calculation using the `exclude_paths` argument. Prior to this, achieving similar functionality would require manual post-processing of the diff result.","severity":"gotcha","affected_versions":"<2.2.0"},{"fix":"Upgrade to `jsondiff` version 2.2.1 or newer to ensure correct symbol comparison behavior.","message":"An issue where `Symbol.__eq__` was not robustly protected by an instance check was fixed in version 2.2.1. This could potentially lead to unexpected behavior or errors when comparing `jsondiff.symbols.xxx` objects with other non-symbol types.","severity":"gotcha","affected_versions":"<2.2.1"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}