How to Use the Schema Compatibility Check Tool

This guide explains how to use schema-compat-check.py to validate schema evolution per SDS-019 §4.

Overview

The tool validates:

Usage

1
2
3
4
5
6
7
8
9
10

# Run self-tests
python tools/schema-compat-check.py --test

# Check a producer schema
python tools/schema-compat-check.py --producer schemas/events/governance/semantic-debt/v1.json

# Check with consumer contracts
python tools/schema-compat-check.py \
  --producer schemas/events/governance/semantic-debt/v1.json \
  --consumers apps/dashboard/contracts/

Output

1
2
3

✅ [PASS] Schema schemas/events/governance/semantic-debt/v1.json is valid
⚠️ [WARN] Consumer dashboard handles specific enums that might have changed
❌ [FAIL] Breaking: Required fields removed: {'id'}

CI Integration

Add to .github/workflows/ci.yml:

1
2
3
4
5

- name: Check Schema Compatibility
  run: |
    python tools/schema-compat-check.py \
      --producer ${{ matrix.schema }} \
      --consumers apps/${{ matrix.consumer }}/contracts/

Rules Enforced

Backward Compatibility

Change Type Allowed?
Add optional field ✅ Yes
Add required field ❌ No
Remove optional field ⚠️ Warning
Remove required field ❌ No
Change field type ❌ No

Forward Compatibility

Consumer Behavior Expected
Ignore unknown fields ✅ Required
Handle new enum values ⚠️ Warning if specific

Consumer Contract Format

1
2
3
4
5
6
7
8

# apps/dashboard/contracts/semantic-debt.contract.yaml
consumer: "governance-dashboard"
event: "sea.debt.created.v1"
expectations:
  - field: "payload.status"
    assertion: "must be one of [open, triaged, accepted]"
  - field: "specs.debtId"
    assertion: "present"

JSON Output

1

python tools/schema-compat-check.py --producer schema.json --json

1
2
3
4
5
6

{
  "status": "PASS",
  "results": [
    {"status": "PASS", "message": "Schema is valid", "consumer": null}
  ]
}