jsondiff

Warnings

• breaking 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.
  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.
• breaking 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.
  Fix: Upgrade your Python environment to version 3.8 or newer. Alternatively, pin your `jsondiff` dependency to `<2.1.2`.
• gotcha 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.
  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`.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Upgrade to `jsondiff` version 2.2.1 or newer to ensure correct symbol comparison behavior.

Install

• pip install jsondiff Install stable version

Imports

• diff

  from jsondiff import diff

  The primary function for comparing JSON objects.
• symbols

  from jsondiff import symbols

  Used to access special symbols for diff output (e.g., 'insert', 'delete', 'update') when using explicit syntax.

Quickstart

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.

from jsondiff import diff, symbols

json1 = {
    "name": "Alice",
    "age": 25,
    "city": "New York",
    "hobbies": ["reading", "hiking", "coding"]
}

json2 = {
    "name": "Bob",
    "age": 30,
    "city": "London",
    "occupation": "Engineer",
    "hobbies": ["reading", "running", "coding"]
}

# Basic diff (compact syntax by default)
compact_diff = diff(json1, json2)
print("Compact Diff:", compact_diff)

# Explicit diff (more detailed output with symbols)
explicit_diff = diff(json1, json2, syntax='explicit')
print("\nExplicit Diff:", explicit_diff)

# Accessing specific changes using symbols
if symbols.insert in explicit_diff:
    print("  Inserted keys:", explicit_diff[symbols.insert])
if symbols.delete in explicit_diff:
    print("  Deleted keys:", explicit_diff[symbols.delete])
if symbols.update in explicit_diff:
    print("  Updated keys:", explicit_diff[symbols.update])