🔍 JSON Schema Diff

A powerful, intelligent library for comparing JSON schemas with beautiful formatted output, smart parameter combination, and contextual information.

⭐ Star us on GitHub | 📚 Read the Docs | 🐛 Report Bug

✨ Features

• 🎯 Intelligent Comparison - Detects and categorizes all types of schema changes
• 🎨 Beautiful Output - Colored, formatted differences with clear symbols
• 🔗 Smart Combination - Combines related parameters (e.g., minimum + maximum = range)
• 📍 Context Aware - Shows related fields for better understanding (e.g., type + format)
• 🔄 Semantic Array Diff - Ignores pure reorder noise and reports only real adds/removes/changes
• ⚡ High Performance - Efficient algorithms for large schemas
• 🛠️ CLI & Python API & Sphinx Extension - Use programmatically or from command line or in .rst
• 🔧 Highly Configurable - Customize behavior for your needs

Installation

# Standard installation
pip install jsonschema-diff

30-Second Example

from jsonschema_diff import JsonSchemaDiff, ConfigMaker
from jsonschema_diff.color import HighlighterPipeline
from jsonschema_diff.color.stages import (
    MonoLinesHighlighter, ReplaceGenericHighlighter, PathHighlighter
)

prop = JsonSchemaDiff(
    config=ConfigMaker.make(),
    colorize_pipeline=HighlighterPipeline([
        MonoLinesHighlighter(),
        ReplaceGenericHighlighter(),
        PathHighlighter(),
    ])
)

prop.compare(
    old_schema="context.old.schema.json",
    new_schema="context.new.schema.json"
)

prop.print(with_legend=True)

Output:

Why It Beats Line-Based Diffs For Schemas

For array-like schema parts, this library performs a semantic diff:

• Pure reorder does not create noisy changes
• dict elements are matched by structure (not by position)
• Scalar elements are matched by value multiplicity (multiset logic)

Example:

[1, 2, 3] -> [3, 1, 2, 1]

A line-based diff typically reports multiple moved lines. jsonschema-diff reports just one meaningful change: + 1.

CLI Usage

# Compare schema files
jsonschema-diff schema_v1.json schema_v2.json

# No colors (for logs/CI) and with exit-code
jsonschema-diff --no-color --exit-code schema_v1.json schema_v2.json

# Compare JSON strings
jsonschema-diff "{\"type\":\"string\"}" "{\"type\":\"number\"}"

Sphinx Extension

Use the extension in your build:

extensions += ["jsonschema_diff.sphinx"]

You must also configure the extension. Add the following variable to your conf.py:

from jsonschema_diff import ConfigMaker, JsonSchemaDiff
from jsonschema_diff.color import HighlighterPipeline
from jsonschema_diff.color.stages import (
    MonoLinesHighlighter, PathHighlighter, ReplaceGenericHighlighter,
)

jsonschema_diff = JsonSchemaDiff(
    config=ConfigMaker.make(),
    colorize_pipeline=HighlighterPipeline(
        [MonoLinesHighlighter(), ReplaceGenericHighlighter(), PathHighlighter()],
    ),
)

After that, you can use it in your .rst files:

.. jsonschemadiff:: path/to/file.old.schema.json path/to/file.new.schema.json # from folder `source`
    :name: filename.svg # optional
    :title: Title in virtual terminal # optional
    :no-legend: # optional

Modern 6-stage pipeline for clean, testable code:

┌─────────────┐    ┌───────────────┐    ┌──────────────────┐
│ DiffFinder  │───▶│ CompareFinder │───▶│ CombineProcessor │
└─────────────┘    └───────────────┘    └──────────────────┘
                                                  ▼
┌─────────────┐    ┌───────────────┐      ┌───────────────┐
│  Formatter  │◀───│RenderProcessor│◀─────│ DiffProcessor │
└─────────────┘    └───────────────┘      └───────────────┘

1. DiffFinder: Finds raw differences
2. CompareProcessor: Find class-processors
3. Combiner: Combines related parameters
4. RenderProcessor: Adds context information and render
5. Formatter: Beautiful colored output

Setup

git clone https://github.com/Miskler/jsonschema-diff.git
cd jsonschema-diff
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
make build
make install-dev

Commands

# Checks
make test          # Run tests with coverage
make lint          # Lint code
make type-check    # Type checking  
# Action
make format        # Format code
make docs          # Build documentation

• 📖 Full Documentation
• 🚀 Quick Start Guide
• 🔧 API Reference

# Fork the repo, then:
git clone https://github.com/your-username/jsonschema-diff.git
cd jsonschema-diff
# Install
make build
make install-dev
# Ensure everything works
make test
make lint
make type-check