Skip to content

Proposal: add schema diff and breaking-change detection #177

Closed

Description

@mathpernias

Proposal

I would like to propose adding a schema comparison mode to erdantic.

Example CLI:

erdantic diff old_models.py new_models.py --format markdown
erdantic diff old_models.py new_models.py --format json
erdantic diff old_models.py new_models.py --format mermaid
erdantic diff old_models.py new_models.py --fail-on-breaking

The comparison would detect:

  • added and removed models;
  • added, removed, and renamed fields;
  • field type changes;
  • required/optional changes;
  • relationship changes;
  • cardinality changes.

The --fail-on-breaking option would return a non-zero exit code when breaking changes are detected, making the feature suitable for CI pipelines.

I also prepared a Mermaid visualization with three columns:

Image
  • Before;
  • Changes;
  • After.

Breaking changes are highlighted in red, while non-breaking changes are shown in blue.

The attached example shows a required field addition (User.age) and an optional field addition (User.nickname).

Would this direction be useful and aligned with the project's goals? I would appreciate feedback before finalizing the pull request.

Activity

  1. jayqi commented on Oct 19, 2026

    @jayqi
    Member

    Hi @mathpernias,

    Thanks for using erdantic and for opening up this discussion about your proposed feature.

    I don't think this functionality as you've described it is a great fit for erdantic. It's not clear to me that erdantic's data model matches the breaking change concepts you're trying to capture.

    There are multiple notions of “breaking change”: how changes affect use of the Python API, and how changes affect serialization/deserialization of data. For the Python API, a change can affect code that constructs instances or code that reads them. Serialization also has notions of forward and backwards compatibility. It's not clear to me what the right scope of support here is, and supporting all of these is a lot of complexity.

    For instance, in your example, you treat nullability (Optional type) as being not required and therefore not breaking. Should type widening like adding additional Union types also be non-breaking? But actually, for someone constructing a model instance, it's not nullability but whether the field has a default value that makes something breaking, and erdantic doesn't even capture and store default values currently.

    Additionally, erdantic works by importing data model classes and inspecting them at runtime. This means that we'd need to have both the before and after versions imported at the same time. Your proposed usage suggests that a user would have copies of both modules on disk together, but generally most projects I've seen would not have two versions of the same source code simultaneously. Also, erdantic identifies models using their dotted paths, and these would likely collide if they're truly the two versions of the same model. The workaround you use in #176 breaks for multi-module code and forward references.

    Instead of building this functionality into erdantic, would it be enough for your use case to just diff the JSON representations of the diagrams? Since erdantic's data model uses Pydantic, you can use EntityRelationshipDiagram.model_dump_json (e.g., erd.create(MyModel).model_dump_json(indent=2)) to export the diagram as JSON, and then do a text diff on that. The output is deterministically ordered, although string representations of type annotations may not be stable across erdantic versions, typenames versions, or Python versions.

  2. mathpernias commented on Oct 25, 2026

    @mathpernias
    Author

    Hi Jay,

    Thanks for the detailed feedback. I agree that schema diffing is outside erdantic’s current scope, and that comparing exported JSON is a better fit.

    I’ll close this proposal and consider improving the documentation around JSON comparison maybe.

    You can also review my Mermaid export PR if you got time: #175.

    Thanks again!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions