A legend is a colored, named box you place on the canvas to group or annotate a region of your ERD. Legends are how you add meaning that is not part of the database structure itself - labels like “Auth”, “Billing”, or “Owned by the payments team”.
What is a legend for?
The schema says what the tables are; a legend says how to read them. Drop a legend behind a cluster of related entities and give it a name and color, and a reviewer instantly sees the grouping without you changing a single column.
How do I create, move, and delete a legend?
- Create a legend from the control bar, then set its Name and Color.
- Move and resize it to frame the entities it describes.
- Delete it when it is no longer needed.
Can I attach a longer description to a legend or an entity?
Yes. Legends and entities both support a description written in markdown. When the description is not empty, a file icon appears at the bottom right of the legend (or entity) on the canvas; clicking it opens a modal that renders the markdown-formatted description.
This is where the knowledge that does not fit in a name goes - why a grouping exists, which team owns it, links to runbooks or ADRs, caveats a reviewer should know. The diagram stays clean, and the detail is one click away instead of living in a wiki page nobody opens next to the ERD.
Descriptions are stored in the workspace’s JSON files, not as database comments - editing one never touches the database, so a documentation change never requires a SQL migration, and it works the same on engines without comment support.
Are legends shared between context views?
Like layout and waypoints, legends are part of a view’s presentation, not the shared schema. A legend you add on the main diagram is independent of your context views, and each context view keeps its own legends. This lets you annotate every view for its own audience without cluttering the others.
Can I annotate the same schema differently in each view?
Because legends, positions, and routing are all per-view, you can present the same entities very differently in different places - a high-level “Auth” grouping in one view, a detailed checkout walkthrough in another - while the underlying entities stay a single source of truth.
Next
Tie it together with the Single source of truth workflow.