# Legends & Annotations

> Use legends in Schemity to group and annotate regions of your ERD with colored, named boxes - a presentation layer that lives per context view, not in the schema.

Source: https://schemity.com/doc/legends-and-annotations/

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](https://schemity.com/doc/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 offers **Get SQL** and **Get DBML** for all entities the legend contains. To do this for every legend at once, use **Sync from legends** in the Context Views drawer.

## Are legends shared between context views?

Like layout and [waypoints](https://schemity.com/doc/custom-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](https://schemity.com/doc/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](https://schemity.com/doc/single-source-of-truth/).