GSoC 2026: JSON Schema Compatibility Checker - Detect Breaking Changes Between Schema Versions

[vtushar06]

Project title
JSON Schema Compatibility Checker — Detect Breaking Changes Between Schema Versions

Brief Description

JSON Schema is great at validating data, but it has no way to answer a critical question: "Will this schema change break existing data?"

When teams evolve their schemas in production — adding a required field, tightening a constraint, or removing an enum value — they often discover problems only after deployment. Existing data that was valid suddenly fails validation. APIs break. Incidents happen.

Other schema ecosystems solved this years ago:

• Protobuf has buf breaking with 53 compatibility rules
• Avro has Schema Registry with built-in backward/forward compatibility checking

JSON Schema has no official tool for this. The closest alternatives (getsentry/json-schema-diff, json-schema-diff on npm) are self-described as "work-in-progress" with incomplete keyword coverage.

This project would create a focused compatibility checker — a CLI tool and library that performs a semantic comparison of two schema versions and reports exactly what changed and whether it's safe and whether it breaks backward or forward compatibility.

Output formats: Human-readable (CLI), machine-readable JSON (API)

Relationship to #969:
This proposal complements @jagpreetrahi's SchemaShift (#969). While #969 focuses on generating migration code, this project focuses purely on detection. As @jviotti noted in #969, combining both detection and migration "might be too much" for a single project. A focused detection tool can serve as the foundation that migration tools build upon.

In short:

• GSOC-26 : Automated JSON Schema Evolution and Data Migration CLI #969 focuses on migration (fixing the data).
• This Project focuses on detection (identifying the break). By separating concerns, we ensure the detection engine is lightweight, reliable, and can be used by other tools (including SchemaShift) as a dependency.

Expected Outcomes

• A TypeScript/JavaScript library that compares two JSON Schema versions and returns a structured compatibility report (breaking changes, warnings, safe changes)

• A CLI tool with human-readable output showing exactly what changed, where, and why it matters

• 20+ semantic compatibility rules mapped from industry standards (buf breaking, Confluent):

  • Type changes (widening/narrowing)
  • Required field additions/removals
  • Enum value additions/removals
  • Constraint changes (minLength, maxLength, minimum, maximum, pattern)
  • Composition keyword changes (allOf, anyOf, oneOf)
  • $ref resolution and circular reference handling

• Documentation with compatibility matrix

• npm package published to @json-schema-org scope

Stretch Goals (if time permits)

• GitHub Action for automated PR compatibility checks
• Extended draft support (2019-09, Draft-06, Draft-04)
• Performance benchmarks and optimization for large schema sets

---

Skills Required

• JavaScript/TypeScript proficiency
• Understanding of JSON Schema keywords across drafts (draft-07, 2019-09, 2020-12)
• Familiarity with tree traversal and comparison algorithms
• Experience writing CLI tools and test suites
• Ability to read and interpret specifications (JSON Schema spec, relevant RFCs)

---

Mentors

• @thclark - as Mentor
• @jviotti - as Co-mentor

And Open to additional TSC members or experienced contributors.

Expected Difficulty
Medium. I think as of.

Expected Time Commitment

90 hours (Small project)

Why This Matters

1. Real production need — Teams choose Protobuf over JSON Schema partly because of missing compatibility tooling

2. Existing tools are incomplete — getsentry/json-schema-diff says "use as best-effort only"

3. Addresses TSC-identified gap: As noted in GSOC-26 : Automated JSON Schema Evolution and Data Migration CLI #969 discussion, a focused detection tool is the missing foundation for schema evolution workflows

4. Benefits the whole ecosystem — Every validator user, every CI pipeline, every team maintaining schemas

---

References

• Buf breaking change detection: https://buf.build/docs/breaking/
• Confluent Schema Registry compatibility: https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html
• Existing incomplete tools:
  • https://github.com/getsentry/json-schema-diff
  • https://www.npmjs.com/package/json-schema-diff
• Related proposal: GSOC-26 : Automated JSON Schema Evolution and Data Migration CLI #969 (SchemaShift — complementary migration tool)
• JSON Schema canonicalization concepts: GSoC 2025: Investigating Schema Normalization #857 (GSoC 2025, closed)

[thclark]

@vtushar06 I sponsored this work last year and am currently hosting it free for use on Strands (a non-profit jsonschema repository).

The UI/UX of the checker could do with some work - it's nowhere near the standard of our other views in Strands. But it's feature complete and based on @jviotti 's tools!!

Try it here: https://strands.octue.com/compare

Github Actions are here (although are tied to the Strands publishing workflow): https://github.com/octue/publish-strand-version

[vtushar06]

@thclark thank you for sharing this. I've looked at Strands and it's excellent work — having a hosted platform for schema registry with comparison features is incredibly valuable.

This proposal (developer tooling):

• Open-source CLI tool for local/CI use
• npm library that other tools can build on
• GitHub Action for automated PR checks
• Standalone tool that doesn't require hosted service

There is a Use case differences:
Strands is excellent for teams wanting a hosted platform, but there's a gap for developers who need:

• Local/offline tooling - not everyone can/wants to use a hosted service
• CI/CD integration - GitHub Actions, GitLab CI, etc. need standalone tools
• Library for embedding - tools like SchemaShift (GSOC-26 : Automated JSON Schema Evolution and Data Migration CLI #969) need a library dependency, not a web API
• Open-source community ownership - the ecosystem benefits from MIT/Apache licensed tools that anyone can fork/extend
• Similar to how git CLI exists alongside GitHub - different tools for different workflows.

Potential collaboration:

If this proposal is accepted, the resulting open-source library could potentially power Strands' comparison engine, making it more maintainable and community-driven. I'd be very interested in your feedback on what compatibility rules matter most from your experience sponsoring this work last year.
Does this differentiation make sense, or do you see significant overlap I'm missing? I'm open to adjusting the proposal scope if needed.

[thclark]

@vtushar06 Yep, couldn't agree more with those things. I propose a potential collaboration, but the other way around - there's no point you re-doing all the work (hint: it took @jviotti about 250 hours IIRC to build mine and he already had extremely deep knowledge of his underlying CLI (blaze) tooling which was heavily used as a basis. Plus he's ridiculously smart.).

It's built in C++ and already bound to python (for use on the API) and IIRC also compiled for WASM. So it shouldn't be hard to bind that up into an NPM module and add a basic CLI.

I've submitted the following project proposal. If it gets picked up, the open-sourcing and management of the compatibility checker could be passed over into this project.

[vtushar06]

@thclark Thanks for all the context and for submitting #987,

I see how these could work together really well like #987 will focus on Platform migration (Django, React, infrastructure)
and #984 mainly focuses on Developer tooling (npm package, CLI, GitHub Action)
Here's what I'm thinking ,If #987 gets accepted and version-cruzer is open-sourced, I'd pivot my proposal to focus on creating npm bindings and a CLI wrapper for it.
That way we able to leverage the 250 hours of battle-tested compatibility logic you and @jviotti already built,and I can deliver the same outcomes (npm package, CLI, GitHub Action) but faster and better and If #987 doesn't get accepted, my original plan stays and lets discuss with TSC about this.

Either way, I'm committed to getting quality compatibility checking tools into developers' hands. Whether we build from scratch or wrap proven code, I'm flexible on the approach.

@jviotti @jdesrosiers - would love your take on this.

[jviotti]

and a CLI wrapper for it.

The GSoC project could be around exposing it in https://github.com/sourcemeta/jsonschema!

[Honyii]

@vtushar06 kindly edit this issue to have @thclark as mentor and @jviotti as a co-mentor.

[rohan-019]

Hi @thclark @jviotti @vtushar06 ,

I’m very interested in contributing to #984 — the JSON Schema Compatibility Checker. This project addresses a clear ecosystem gap: while JSON Schema excels at validation, it lacks a standardized way to detect breaking changes between schema versions, something that other ecosystems (like Protobuf and Avro) handle well.

I’m particularly interested in designing a draft-aware semantic comparison engine with structured compatibility modes (backward, forward, full), exposed via a TypeScript library and CLI for local and CI usage.

Before moving forward, I’d appreciate some clarity on direction: since a compatibility engine has already been developed previously, is the goal here to build a new engine from scratch, or to formalize and expose an existing implementation (for example via sourcemeta/jsonschema with JS/CLI bindings) as the official community-supported solution?

I want to ensure the effort aligns with prior work and maximizes ecosystem impact without duplicating existing foundations.

Looking forward to your guidance and feedback.

[jviotti]

@rohan-019 We would be building it on top of the existing project that @thclark will open source. The project is in C++, and will be likely exposed through https://github.com/sourcemeta/jsonschema, a C++ CLI. I don't think there will be any TypeScript involved!

[rohan-019]

Hey @jviotti, Thanks for the clarification — that makes sense. I’m happy to align with integrating the compatibility engine directly into sourcemeta/jsonschema as a C++ CLI feature.

[rohan-019]

since the compatibility engine will be open-sourced and then exposed through sourcemeta/jsonschema, would you recommend waiting until that repository is available before working on CLI integration?

I’ve been reviewing the CLI structure locally and thinking about how a compatibility command might integrate, but I want to make sure the timing and structure align with the intended rollout.

Happy to prepare groundwork meanwhile if helpful.