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.
How do I find a legend on a big diagram?
The same search that finds entities and fields finds legends. Type any fragment of the legend’s name and the matching row appears prefixed with [L]; choosing it selects the legend and centres the viewport on it, so a grouping you drew months ago on a far corner of the canvas is one search away. Because legends belong to a view, search follows the view you are in: a context view finds its own legends, the main diagram finds the main ones. See The ERD Canvas for the full search behavior.
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 small triangle appears in the top-right corner 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.
Can I turn a legend into a context view?
Yes - and it is the natural next step once a legend has proven itself as a domain boundary. Right-click the legend and choose Import to context views: every entity inside the legend is brought into the context view you pick, in one step, instead of being added one by one. The same right-click menu also lets you export the SQL of all entities the legend contains.
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.