feat: breaking schema change detection with governance webhooks by boyney123 · Pull Request #2371 · event-catalog/eventcatalog

boyney123 · 2026-03-23T16:03:28Z

Summary

New @eventcatalog/breaking-changes package that detects breaking JSON Schema changes (added/removed required fields, type changes, required status changes) per compatibility strategy (BACKWARD, FORWARD, FULL, NONE)
New schema_breaking_change governance trigger — fires when a schema change is detected as breaking per the configured strategy
Users configure their compatibility strategy globally in governance.yaml via a new compatibility.strategy field
CloudEvents-compliant webhook payload includes detailed breaking change info (field, change type, human-readable message), impacted consumers/producers, and schema hashes

Example `governance.yaml`:

compatibility:
  strategy: BACKWARD

rules:
  - name: notify-on-breaking-schema
    when: [schema_breaking_change]
    resources:
      - type: event
        id: "*"
    actions:
      - type: webhook
        url: https://example.com/breaking-changes

Test plan

40 tests for @eventcatalog/breaking-changes package (differ + rules + integration)
104 governance tests in CLI package (all existing + 8 new for breaking change detection)
Package builds successfully with tsup
Manual test with a real catalog and governance.yaml

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…Change Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…velope Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

changeset-bot · 2026-03-23T16:03:34Z

🦋 Changeset detected

Latest commit: cb74d30

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@eventcatalog/breaking-changes	Minor
@eventcatalog/cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-03-23T16:03:42Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
eventcatalog-playground	Ignored		Mar 23, 2026 4:03pm

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f81bff4f48

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

packages/breaking-changes/src/json-schema/differ.ts

…bjects - Detect root-level type changes (e.g., object → array) - Recurse into nested schemas that have properties/required but no explicit type Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ea7e4b0fa0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

packages/cli/src/cli/governance/rules.ts

- Validate strategy against BACKWARD/FORWARD/FULL/NONE on config load - Narrow try/catch to only JSON.parse so detectBreakingChanges errors propagate Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 03fb605ebf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

packages/breaking-changes/src/json-schema/differ.ts

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cb74d30a7b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-23T16:56:38Z

packages/cli/src/cli/governance/rules.ts

  }

-  return { rules };
+  if (parsed?.compatibility?.strategy) {


Reject empty compatibility strategy values

The compatibility strategy validation only runs when parsed?.compatibility?.strategy is truthy, so malformed configs like compatibility: { strategy: "" } (or other falsy non-enum values) bypass validation and are returned as-is. Downstream, evaluateBreakingSchemaChangeRules treats this as “no strategy,” so schema_breaking_change rules silently never fire and fail/webhook enforcement can be skipped by an invalid config instead of producing a clear error.

Useful? React with 👍 / 👎.

boyney123 and others added 12 commits March 23, 2026 15:13

docs: add breaking schema change detection implementation plan

de25722

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore: add .worktrees/ to .gitignore

6c30e06

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat(breaking-changes): scaffold package

2e6acf8

feat(breaking-changes): json schema differ with tests

0fb2dd7

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(breaking-changes): breaking change rules per strategy with tests

1afc1e1

feat(breaking-changes): integration tests for public API

6e7d371

feat(cli): add schema_breaking_change trigger type and BreakingSchema…

c1f5844

…Change Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(cli): parse compatibility strategy from governance.yaml

2df4196

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(cli): evaluate schema_breaking_change governance rules

8ac0399

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(cli): enrich breaking schema changes with actual diff results

bf27cd3

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(cli): schema_breaking_change webhook payload with CloudEvents en…

0f14ec1

…velope Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: format code

f81bff4

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector bot reviewed Mar 23, 2026

View reviewed changes

packages/breaking-changes/src/json-schema/differ.ts Show resolved Hide resolved

packages/breaking-changes/src/json-schema/differ.ts Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Mar 23, 2026

View reviewed changes

packages/cli/src/cli/governance/rules.ts Outdated Show resolved Hide resolved

packages/cli/src/cli/governance/rules.ts Show resolved Hide resolved

boyney123 and others added 2 commits March 23, 2026 16:28

fix(cli): validate compatibility strategy and narrow catch scope

5e3de8a

- Validate strategy against BACKWARD/FORWARD/FULL/NONE on config load - Narrow try/catch to only JSON.parse so detectBreakingChanges errors propagate Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore: remove implementation plan from repo

03fb605

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector bot reviewed Mar 23, 2026

View reviewed changes

packages/breaking-changes/src/json-schema/differ.ts Show resolved Hide resolved

chore: add changeset for breaking schema change detection

cb74d30

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector bot reviewed Mar 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: breaking schema change detection with governance webhooks#2371

feat: breaking schema change detection with governance webhooks#2371
boyney123 wants to merge 16 commits intomainfrom
feature/breaking-schema-changes

boyney123 commented Mar 23, 2026

Uh oh!

changeset-bot bot commented Mar 23, 2026 •

edited

Loading

Uh oh!

vercel bot commented Mar 23, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

boyney123 commented Mar 23, 2026

Summary

Example governance.yaml:

Test plan

Uh oh!

changeset-bot bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Mar 23, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Example `governance.yaml`:

changeset-bot bot commented Mar 23, 2026 •

edited

Loading