Context views and legends only pay off if you treat the diagram as the ERD single source of truth. This page describes the workflow that makes that real.

One schema, many views

In Schemity, each connection holds one schema - the main diagram - plus any number of context views and legends layered on top. The crucial split:

  • Schema (entities, fields, keys, constraints, relationships) is shared. Edit it once and every view reflects the change.
  • Presentation (which entities a view shows, their positions, connector routing, legends) is per view.

Because the structure is shared, no view can ever disagree with another about what the schema is. You never copy entities to build a second diagram.

Keep it in the repo

Keep one workspace per service or bounded context, stored as JSON inside that service’s Git repository, so the diagram moves with the code. See Version Control in Git.

Change it like code

When the schema changes:

  1. Edit the model in Schemity.
  2. Review the JSON diff in a pull request, alongside the migration that implements it.
  3. Merge both together.

Now the diagram is updated in the same change that updates the database. This is how you stop ERDs from rotting into fiction.

The payoff

  • New engineers read an accurate map instead of a stale one.
  • Reviewers see schema changes as readable diffs.
  • The diagram is trusted, because it is maintained the same way as the code.

Next

Learn the storage format that makes this possible in JSON Storage Format.