You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Proposal: add schema diff and breaking-change detection #177
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.
Activity
jayqi commentedon Oct 19, 2026
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 (
Optionaltype) as being not required and therefore not breaking. Should type widening like adding additionalUniontypes 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.mathpernias commentedon Oct 25, 2026
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!