JSON Schema Diff & Breaking Change Detector

A JSON Schema Diff is a specialized semantic comparison tool that evaluates two versions of a JSON Schema contract (such as an existing production release vs. a proposed draft) to detect additions, deletions, type shifts, constraint alterations, and backward-incompatible breaking changes.

Unlike a conventional JSON diff—which merely checks whether static data values differ—a JSON Schema diff evaluates the rules of validation. It asks: "Will existing JSON payloads that were valid under Schema Version 1 still pass validation under Schema Version 2?"

Compatibility is not universal—it depends on whether you are analyzing the schema from the perspective of an API Consumer, an API Producer, an Event Consumer, or a Configuration Consumer.

When a property's type keyword changes, the engine inspects primitive compatibility:

• Incompatible Mutations: integer → string, string → integer, object → array are classified as BREAKING.
• Nullable Widening: string → [string, null] expands the valid set to allow nulls (NON-BREAKING for consumers).
• Nullable Narrowing: [string, null] → string removes null support (BREAKING).

The required array defines mandatory properties for valid JSON objects:

The enum keyword specifies an exhaustive list of acceptable literal values:

• Enum Value Removed: Removing a literal (e.g. "cancelled") is BREAKING because any database record or consumer payload using that value will fail validation.
• Enum Value Added: Adding a literal is NON-BREAKING for consumers, but flagged as POTENTIALLY BREAKING for producers if downstream clients employ strict switch statements.

The diff engine resolves local reference pointers (#/$defs/... and #/definitions/...) with cycle detection to evaluate real schema inheritance:

• oneOf Variant Removed: Removing an allowed union schema variant is BREAKING.
• anyOf Variant Added: Adding an alternative branch is NON-BREAKING.
• allOf Branch Added: Adding an intersecting constraint is POTENTIALLY BREAKING.

ToolMono computes a deterministic 0–100 Compatibility Score:

Based on detected changes and current version numbers, the engine recommends:

• MAJOR bump (e.g. 2.0.0): When 1 or more breaking changes exist.
• MINOR bump (e.g. 1.5.0): When only backward-compatible additions exist.
• PATCH bump (e.g. 1.4.1): When only metadata or documentation attributes changed.

With one click, export automated documentation:

Comparing an API order schema transition:

{
  "type": "object",
  "required": ["id"],
  "properties": {
    "id": { "type": "integer" }
  }
}

{
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "string" },
    "email": { "type": "string" }
  }
}

Findings generated:

• $.properties.id.type: Type changed from integer to string (BREAKING).
• $.required: Property 'email' is now required (BREAKING).
• Recommendation: Increment MAJOR version to v2.0.0.