JsonifyTools
    Schema Toolkit · 100% Local · Browser Only

    Schema Diff

    Compare schema versions and highlight added fields, removed fields, changed types, and breaking API contract changes.

    Browser only Valid Schema / Data
    Schema A
    23 lines
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    Schema B
    23 lines
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    Schema Difference
    +1 Added
    -1 Removed
    ~0 Modified
    11 Unchanged
    •$object
    -$.activeboolean
    •$.createdAtstring
    •$.emailstring
    •$.idinteger
    •$.namestring
    •$.profileobject
    •$.profile.companystring
    •$.profile.countrystring
    •$.profile.phonestring
    •$.rolesarray
    •$.roles[]string
    +$.statusstring

    Schema Metrics

    Fields
    12
    Objects
    2
    Arrays
    1
    Constraints
    4

    Field Hierarchy Tree

    ❖Root(object)
    └─id*(integer)
    └─name*(string)
    └─email*(string)
    email
    └─active(boolean)
    └─createdAt(string)
    date-time
    └─profile(object)
    └─phone(string)
    └─country(string)
    └─company(string)
    └─roles(array)
    └─items[](string)

    Schema Constraints

    $.name(1 rule)
    minLength:1
    $.email(1 rule)
    format:email
    $.createdAt(1 rule)
    format:date-time
    $.roles[](1 rule)
    enum:["admin","developer","member"]
    API Breaking Change & Schema Diff Engine
    100% Client-Side Engine

    Online Schema Diff & Breaking API Change Detector

    Compare two JSON Schema or OpenAPI versions to detect breaking API changes, removed fields, data type mutations, added required keys, and structural updates before deploying code to production. Ideal for microservice API governance, Semantic Versioning (SemVer) audits, and CI/CD contract testing with 100% browser-only privacy.

    Breaking DetectorSemVer Rules Engine
    Diff GranularityProperty-Path Level
    Spec CompatibilityJSON Schema & OpenAPI
    Privacy100% Client-Side

    Interactive Schema Diff & Breaking Change Scenarios

    Select a schema comparison scenario to inspect V1 vs V2 structural changes and severity verdicts:

    Breaking Change
    HIGH BREAKING CHANGE

    1. Property Data Type Mutation

    Breaking Change — Requires API Major Version Bump (v1 -> v2)

    Schema V1 (Old)
    {
  "type": "object",
  "properties": {
    "userId": { "type": "integer" }
  }
}
    Schema V2 (New)
    {
  "type": "object",
  "properties": {
    "userId": { "type": "string" }
  }
}
    Computed Diff Verdict & Analysis
    ⚠️ BREAKING CHANGE DETECTED:
- /properties/userId: Data type mutated from "integer" to "string".
Impact: Existing API clients sending integer numbers will fail backend validation.
    SemVer Audit Rules

    Breaking vs Backward-Compatible Schema Rules Matrix

    Audit guide detailing how schema modifications impact API client backward compatibility:

    Schema ModificationClassificationProduction API Impact
    Property RemovedBreaking ChangeFrontend / SDK code breaks when referencing removed key
    Type Changed (e.g. int -> string)Breaking ChangeExisting payloads fail validator type check
    Key Added to required arrayBreaking ChangeLegacy requests without the new key fail HTTP 400
    additionalProperties set to falseBreaking ChangeClients sending extra metadata keys get rejected
    Bounds Constrained (min 10 -> 20)Breaking ChangePayloads valid under old bounds now fail validation
    Optional Property AddedBackward CompatibleExisting clients ignore unknown new optional keys
    Key Removed from required arrayBackward CompatiblePayloads without the key are now accepted
    Type Relaxed (string -> string|null)Backward CompatibleAccepts additional null payload values safely

    Why, When, & How to Use Schema Diff

    Why Run Schema Diffs?

    Running schema diffs prevents accidental breaking changes from breaking mobile apps, partner integrations, and frontend clients during continuous API deployments.

    When to Run Schema Diffs?

    Execute schema diff audits during GitHub Pull Request reviews, pre-release Semantic Versioning checks, microservice API gateway updates, and database migration reviews.

    How Does the Engine Work?

    Paste Schema V1 and Schema V2. The diff engine recursively walks object trees, compares data types, checks required arrays, and outputs line-by-line breaking verdicts.

    Programmatic CI/CD Pipeline Automation

    Automate schema diff checks in your CI/CD pipelines to block breaking PRs:

    # Linux / macOS Terminal - Compare 2 JSON Schemas via CLI
# 1. Install json-schema-diff-cli
npm install -g json-schema-diff-cli

# 2. Compare Schema V1 vs Schema V2
json-schema-diff ./schemas/v1.json ./schemas/v2.json --check-breaking
    Under the Hood

    How the Schema Diff Engine Shows Differences

    Our JSON schema diff tool uses a recursive tree-walk algorithm that traverses every node of both schemas simultaneously. Here is the step-by-step pipeline that powers the comparison:

    Step 1

    Parse & Normalize

    Both Schema V1 (old) and Schema V2 (new) are parsed from raw JSON/YAML text into normalized Abstract Syntax Trees (AST). Invalid JSON is caught here with line-level syntax error reporting.

    Step 2

    Recursive Tree Walk

    The engine walks both trees node-by-node using depth-first traversal. At each property path (e.g. /properties/user/address/zipcode), it records the V1 value and the V2 value for comparison.

    Step 3

    Delta Classification

    Every detected change is classified into one of four categories: Added (new key in V2), Removed (key deleted from V1), Type Changed (data type mutation), or Value Changed (constraint modification like minimum, maxLength).

    Step 4

    Breaking Change Verdict

    Each delta is scored against SemVer rules: removing required properties, narrowing types, or deleting enum values are flagged as Breaking Changes. Adding optional fields or widening types are marked Backward Compatible.

    Diff Output Visualization Modes

    Side-by-Side View

    Schema V1 and V2 are displayed in adjacent panels with color-coded highlights: red lines for removed keys, green lines for added keys, and amber lines for modified values.

    Unified Diff View

    A single merged view showing all changes inline with +/- prefixes, similar to git diff output — ideal for copying into Pull Request reviews and code comments.

    Summary Verdict Report

    A structured report listing every JSON Pointer path that changed, its old value vs new value, and a BREAKING / COMPATIBLE classification badge.

    Professional Guide

    Best Practices for JSON Schema Diffing & API Versioning

    Follow these industry best practices to prevent accidental breaking changes, maintain backward compatibility, and keep your API consumers happy:

    1. Follow Semantic Versioning (SemVer)

    Always bump the MAJOR version (v1.x.x -> v2.0.0) whenever a breaking diff is detected (e.g. removing a property or changing data types).

    2. Implement Deprecation Windows

    Before removing a schema field, mark it with `"deprecated": true` in JSON Schema for at least 1-2 release cycles so API clients can migrate.

    3. Use Caution with additionalProperties: false

    Setting `additionalProperties: false` causes any new field added by upstream producers to break downstream consumers; use open schemas during transition periods.

    4. Automate PR Schema Gates in CI/CD

    Incorporate schema diff CLI checks into GitHub Actions or GitLab CI to fail builds automatically if a Pull Request introduces unapproved breaking API changes.

    Pin Schema Drafts

    Always declare $schema (Draft-07, 2020-12) so validators and diff tools know which specification rules to apply.

    Use $ref for Shared Types

    Extract reusable definitions into $defs and reference them with $ref. This makes diffs smaller and easier to review.

    Test Schemas in CI

    Add schema validation and diff checks to your GitHub Actions or GitLab CI pipeline so breaking changes are caught before merging.

    Document Every Change

    Maintain a CHANGELOG.md next to your schema files listing what changed, when, and why — this is essential for API consumers.

    Full Schema Studio Suite

    Schema Studio Features — 7 Tools in One Platform

    Beyond schema diffing, our Schema Studio platform includes a complete suite of JSON Schema tools. Explore each feature below with live examples:

    1. Schema Diff & Breaking Change Checker

    Compare two JSON Schema versions (V1 vs V2) and automatically highlight added fields, removed keys, data type mutations, and breaking changes.

    Input Example
    // Schema V1 (Old)
{
  "properties": {
    "userId": { "type": "integer" }
  }
}

// Schema V2 (New)
{
  "properties": {
    "userId": { "type": "string" }
  }
}
    Output Result
    ⚠️ BREAKING API CHANGE DETECTED:
- /properties/userId: Type changed from 'integer' to 'string' (Breaking Change)
    Side-by-side tree traversal and diff visualization
    Classifies modifications into Breaking vs Backward Compatible
    Supports JSON Schema Draft-07, Draft-06, 2020-12 & OpenAPI specs
    100% client-side calculation with zero server uploads
    Enterprise & Governance

    Schema Registry Governance & Contract-First API Design

    In enterprise environments, schema diff tools are the backbone of contract-first API development, event-driven architectures, and microservice governance. Here is how teams use schema diffing at scale:

    Contract-First API Development

    • Define JSON Schema or OpenAPI spec BEFORE writing application code
    • Use schema diff in PR reviews to ensure implementation matches the contract
    • Generate client SDKs (TypeScript, Python, Go) automatically from validated schemas
    • Maintain a single source of truth for all API shapes across frontend, backend, and mobile

    Event-Driven Architecture (Kafka / RabbitMQ)

    • Register Avro, Protobuf, or JSON Schema in Confluent Schema Registry or AWS Glue
    • Schema diff prevents producers from publishing events that break downstream consumers
    • Enforce forward & backward compatibility modes for Kafka topic schemas
    • Auto-detect breaking changes before deploying new event schema versions

    Microservice API Gateway Governance

    • Centralized schema registry for all internal and partner-facing API contracts
    • API gateway enforces schema validation at ingress — rejecting non-conformant payloads
    • Schema diff reports are attached to every release ticket for compliance audits
    • Versioned schemas enable blue-green and canary deployments without breaking clients

    Frequently Asked Questions (FAQs)

    Related Developer Tools

    Explore more free developer tools to speed up debugging, testing, and development.

    Related Articles