jsonschema-changelog

Detect, document, and manage changes between JSON Schema versions.

Part of the Búho Zurdo ecosystem 🦉

Overview

jsonschema-changelog provides deterministic semantic comparison, classification, and changelog generation for JSON Schema specifications.

• Detect differences between schema revisions (properties, types, constraints, enums, conditional subschemas if/then/else, dependentRequired, and dynamic keywords like unevaluatedProperties).
• Classify changes by operational impact (breaking, non-breaking, deprecations).
• Generate human-readable and machine-parseable changelogs (Markdown, JSON, HTML).
• Validate backward and forward schema compatibility in CI/CD pipelines.
• Generate deterministic data migration scripts.

Designed for data governance in schema-driven architectures, APIs, and clinical/laboratory management systems (LIMS).

Installation

pip install jsonschema-changelog

For development:

git clone https://github.com/buhozurdo/jsonschema-changelog.git
cd jsonschema-changelog
pip install -e ".[dev]"

Quick Start

Python API

from jsonschema_changelog import SchemaDiff, ChangeClassifier, ChangelogGenerator

old_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "status": {"type": "string", "enum": ["active", "inactive"]}
    },
    "required": ["name"]
}

new_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "status": {"type": "string", "enum": ["active", "inactive", "pending"]},
        "email": {"type": "string", "format": "email"}
    },
    "required": ["name"]
}

# 1. Detect differences
differ = SchemaDiff(old_version="1.0.0", new_version="2.0.0")
diff_result = differ.compare(old_schema, new_schema)

# 2. Classify impact
classifier = ChangeClassifier()
classification = classifier.classify(diff_result)

print(f"Breaking: {len(classification.breaking_changes)}")
print(f"Non-breaking: {len(classification.non_breaking_changes)}")
print(f"Compatible: {classification.is_compatible}")

# 3. Generate changelog
generator = ChangelogGenerator(title="API Schema Changelog")
changelog = generator.generate(classification)
markdown = generator.to_markdown(changelog)
print(markdown)

Command Line Interface

# Compare schemas
jsonschema-changelog diff old.json new.json

# Generate changelog
jsonschema-changelog changelog old.json new.json --format markdown -o CHANGELOG.md

# Validate compatibility (fails with exit code 1 on breaking changes)
jsonschema-changelog validate old.json new.json --fail-on-breaking

# Generate data migration script
jsonschema-changelog migrate old.json new.json --language python -o migrate.py

# Inspect schema details
jsonschema-changelog info schema.json

Change Classification Matrix

CI/CD Integration

GitHub Actions (Fail PR on Breaking Changes)

name: Schema Compatibility Check

on:
  pull_request:
    paths:
      - 'schemas/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - run: pip install jsonschema-changelog

      - name: Validate schema compatibility
        run: |
          jsonschema-changelog validate \
            schemas/current.json \
            schemas/proposed.json \
            --fail-on-breaking

      - name: Generate changelog
        if: always()
        run: |
          jsonschema-changelog changelog \
            schemas/current.json \
            schemas/proposed.json \
            --format markdown \
            -o SCHEMA_CHANGELOG.md

      - uses: actions/upload-artifact@v4
        with:
          name: schema-changelog
          path: SCHEMA_CHANGELOG.md

Pre-commit Hook

repos:
  - repo: local
    hooks:
      - id: schema-compatibility
        name: Validate Schema Compatibility
        entry: jsonschema-changelog validate
        language: python
        files: \.json$
        args: ['schemas/current.json', 'schemas/proposed.json', '--fail-on-breaking']

Known Limitations

• Recursive Schemas: Self-referential $ref definitions beyond 10 levels of nesting are truncated to avoid recursion exhaustion.
• Draft 2020-12 & OpenAPI 3.1 Support: The library provides broad support for modern JSON Schema keywords (including unevaluatedProperties, unevaluatedItems, dependentRequired, and if/then/else). However, highly complex dynamic cross-references or niche schema compositions might still fall back to structural diffs.

Testing

# Run test suite
pytest

# Run tests with coverage
pytest --cov=src/jsonschema_changelog --cov-report=term-missing

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and adhere to Búho Zurdo Engineering Standards.

1. Fork repository.
2. Create feature branch (git checkout -b feat/schema-feature).
3. Add tests and verify formatting.
4. Open Pull Request.

License

MIT License. See LICENSE for details.