api-schema-diff
Detect breaking changes between API schemas (OpenAPI / JSON Schema) in a deterministic, CI-friendly way.
api-schema-diff is a CLI tool designed to answer one question reliably:
"Will this schema change break existing clients?"
Why this exists
API changes often break clients silently.
Common causes:
- Removing endpoints
- Removing fields
- Changing parameter requirements
- Changing request/response schemas
api-schema-diff catches these issues before they reach production.
Features
Supported inputs
- OpenAPI 3.x (JSON / YAML)
- JSON Schema (generic structure diff)
Breaking changes detected
- Removed paths or operations
- Removed query / path / header parameters
- Parameters becoming required
- Parameter schema type changes
- Request body removed
- Request body becoming required
- Request body schema breaking changes
- Removed response status codes
- Response schema breaking changes
- Removed properties in schemas
- Property type changes
- Optional → required fields
Non-breaking changes detected
- Added paths or operations
- Added optional parameters
- Added optional request bodies
- Added response status codes
- Added optional properties
Designed for CI
- Deterministic output
- Stable exit codes
- JSON output for automation
- Works offline (no cloud / no LLM dependency)
Installation
pip install api-schema-diff
Or install from source:
git clone https://github.com/teolzr/schema-diff.git
cd schema-diff
pip install -e .
Requirements:
- Python 3.10 or higher
typer>=0.12rich>=13.7
Docker
Run without installing Python:
# Pull the image
docker pull ghcr.io/teolzr/schema-diff:latest
# Run with local files
docker run --rm -v $(pwd):/workspace ghcr.io/teolzr/schema-diff:latest old.yaml new.yaml
# Check version
docker run --rm ghcr.io/teolzr/schema-diff:latest --version
# Use in CI/CD
docker run --rm \
-v $(pwd):/workspace \
ghcr.io/teolzr/schema-diff:latest \
schemas/v1.yaml schemas/v2.yaml \
--format json
Available tags:
latest- Latest stable releasev0.1.4- Specific versionmain- Latest from main branch
GitHub Action
Use in any GitHub workflow:
- uses: teolzr/schema-diff@v1
with:
old: api/schema-v1.yaml
new: api/schema-v2.yaml
Compare against main branch:
- run: git show origin/main:api/schema.yaml > /tmp/baseline.yaml
- uses: teolzr/schema-diff@v1
with:
old: /tmp/baseline.yaml
new: api/schema.yaml
JSON output:
- uses: teolzr/schema-diff@v1
with:
old: old.yaml
new: new.yaml
format: json
fail-on-breaking: false
Usage
Basic usage
api-schema-diff old.json new.json
Exit codes:
0→ No breaking changes found1→ Breaking changes detected
Output formats
Text output (default):
api-schema-diff old.json new.json
Output:
BREAKING CHANGES FOUND
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Type ┃ Path ┃ Old Type┃ New Type┃ Message ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ removed_field│ User.email │ │ │ │
│ type_change │ Order.amount│ <number>│ <string>│ │
└──────────────┴─────────────┴─────────┴─────────┴───────────────────────┘
JSON output:
api-schema-diff old.json new.json --format json
Output:
{
"breaking": [
{
"type": "removed_field",
"severity": "breaking",
"path": "User.email",
"old_type": null,
"new_type": null,
"message": null
},
{
"type": "type_change",
"severity": "breaking",
"path": "Order.amount",
"old_type": "<number>",
"new_type": "<string>",
"message": null
}
],
"non_breaking": []
}
CLI Options
api-schema-diff [OPTIONS] OLD_FILE NEW_FILE
Arguments:
OLD_FILE- Path to the old schema file (JSON or YAML)NEW_FILE- Path to the new schema file (JSON or YAML)
Options:
--format [text|json]- Output format (default:text)--fail-on-breaking / --no-fail-on-breaking- Exit with code 1 when breaking changes are found (default:true)--help- Show help message
Report-only mode
Use --no-fail-on-breaking to always exit with code 0 (useful for reporting without failing CI):
api-schema-diff old.json new.json --no-fail-on-breaking
Examples
Example 1: Generic JSON diff
old.json:
{
"User": {
"email": "a@b.com",
"age": 30
},
"Order": {
"amount": 12.5
}
}
new.json:
{
"User": {
"age": "30"
},
"Order": {
"amount": "12.5"
},
"NewThing": {}
}
api-schema-diff old.json new.json
Detected changes:
- Breaking:
User.emailfield removed - Breaking:
User.agetype changed from number to string - Breaking:
Order.amounttype changed from number to string - Non-breaking:
NewThingobject added
Example 2: OpenAPI diff
old-api.yaml:
openapi: 3.0.0
paths:
/users:
get:
parameters:
- name: limit
in: query
required: false
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
name:
type: string
email:
type: string
new-api.yaml:
openapi: 3.0.0
paths:
/users:
get:
parameters:
- name: limit
in: query
required: true # Now required!
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
name:
type: string
# email removed!
api-schema-diff old-api.yaml new-api.yaml
Detected changes:
- Breaking: Query parameter
limitbecame required - Breaking: Response property
emailremoved
CI/CD Integration
GitHub Actions
name: Schema Diff Check
on:
pull_request:
paths:
- 'api/schema.yaml'
jobs:
schema-diff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.10'
- name: Install api-schema-diff
run: pip install api-schema-diff
- name: Get old schema from main branch
run: git show origin/main:api/schema.yaml > old-schema.yaml
- name: Check for breaking changes
run: api-schema-diff old-schema.yaml api/schema.yaml
GitLab CI
api-schema-diff:
image: python:3.10
before_script:
- pip install api-schema-diff
script:
- git show origin/main:api/schema.yaml > old-schema.yaml
- api-schema-diff old-schema.yaml api/schema.yaml
only:
changes:
- api/schema.yaml
Pre-commit hook
Create .pre-commit-config.yaml:
repos:
- repo: local
hooks:
- id: api-schema-diff
name: Check API schema for breaking changes
entry: bash -c 'git show HEAD:api/schema.yaml > /tmp/old-schema.yaml && api-schema-diff /tmp/old-schema.yaml api/schema.yaml'
language: system
files: 'api/schema.yaml'
pass_filenames: false
Development
Setup
# Clone the repository
git clone https://github.com/teolzr/schema-diff.git
cd schema-diff
# Install in development mode
pip install -e .
# Install development dependencies
pip install pytest pytest-cov black ruff
Running tests
# Run all tests
pytest
# Run with coverage
pytest --cov=schema_diff --cov-report=html
# Run specific test file
pytest tests/test_openapi_diff.py
Note: The Python package is still named schema_diff internally, but the PyPI package and CLI command are api-schema-diff.
Code formatting
# Format code
black .
# Lint code
ruff check .
Project structure
schema-diff/
├── schema_diff/
│ ├── __init__.py
│ ├── cli.py # CLI entry point
│ ├── diff.py # Generic JSON diff logic
│ ├── loader.py # Schema file loading
│ ├── models.py # Data models
│ ├── rules.py # Breaking change rules
│ └── openapi/
│ ├── __init__.py
│ ├── diff.py # OpenAPI-specific diff
│ ├── json_schema_diff.py # JSON Schema diffing
│ ├── normalizer.py # Schema normalization
│ └── resolver.py # $ref resolution
├── tests/
├── pyproject.toml
└── README.md
How it works
- Schema loading: Automatically detects schema type (OpenAPI vs generic JSON/YAML)
- Normalization: Resolves
$refreferences and normalizes structure - Diffing: Compares schemas using rule-based detection
- Classification: Categorizes changes as breaking or non-breaking
- Reporting: Outputs results in human-readable or JSON format
Change detection logic
Breaking changes:
- Removing existing fields/paths → clients expect them
- Changing types → clients may send wrong data type
- Making optional fields required → clients may not send them
- Removing response fields → clients may depend on them
Non-breaking changes:
- Adding new fields/paths → clients can ignore them
- Making required fields optional → clients can still send them
- Adding new optional fields → backwards compatible
Roadmap
- Support for OpenAPI 2.0 (Swagger)
- GraphQL schema diffing
- Custom rule configuration
- HTML report generation
- API compatibility scoring
- Severity levels (error, warning, info)
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Add tests for new functionality
- Run tests and linting
- Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
MIT License - see LICENSE file for details
Credits
Built with:
Related Projects
- openapi-diff - OpenAPI comparison tool
- swagger-diff - Swagger API comparison
- json-schema-diff - JSON Schema comparison
Support
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
Note: Repository name is schema-diff, but PyPI package name is api-schema-diff
Metadata
Release files for api-schema-diff 1.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| api_schema_diff-1.0.4.tar.gz | 17.7 kB | With provenance | Details for api_schema_diff-1.0.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| api_schema_diff-1.0.4-py3-none-any.whl | Python 3 | none | any | Details for api_schema_diff-1.0.4-py3-none-any.whl |
Total release size: 35.1 kB
Release files / api_schema_diff-1.0.4.tar.gz
| Download URL | api_schema_diff-1.0.4.tar.gz |
|---|---|
| Size | 17.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
22dbfee814458ae570a66734cf21d140e5d3c8d8b44e12e42b862b4ba148d226
|
|
BLAKE2b-256 checksum How to use checksums |
9b55feb8d8a91461cdc86343a3e95ff30f05f582ebc14997a780e5006fc53d1a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 16, 2025.
Transparency logRelease files / api_schema_diff-1.0.4-py3-none-any.whl
| Download URL | api_schema_diff-1.0.4-py3-none-any.whl |
|---|---|
| Size | 17.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
89e72a3ea68508944227583ed7d6e59ff3ba9a2b253a476a96c48b3435667511
|
|
BLAKE2b-256 checksum How to use checksums |
bf8a4835b95e839220f33b5c75e0786dad8972bb8a7ea619a1554dcbc26b483b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 16, 2025.
Transparency logSecurity for api-schema-diff 1.0.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for api_schema_diff-1.0.4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 16, 2025.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.