Annotations

The keys Schematlas adds to diagrams, and how each format stores them.

An annotation is a small set of keys attached to a diagram, a node or an edge. The keys are the same in every format; only where they are stored differs.

Keys

KeyValueExample
titleTexttitle="Checkout"
kindA word: service, store, queue, actor…kind=service
codeA code reference; repeat for severalcode=src/api.rs:12-80
noteMarkdown textnote="Validates carts"
tagsComma-separated wordstags=http,core
colorAccent color of the cardcolor=#7fa98d
commitCommit the node was last reviewed againstcommit=3f2c9e1

Any other key is kept as it is, so a file written by a newer version of Schematlas survives an older one. Keys are written in a stable order — title, kind, code, note, tags, then the others alphabetically — so diffs stay small.

Code references

FormMeans
src/api.rsThe whole file
src/api.rs:12One line
src/api.rs:12-80A range of lines
src/api.rs#L12-L80The same range, Markdown-link style

Paths are relative to the repository root. Absolute paths, .., backslashes and drive letters are refused. References are always written back as path:start-end.

Where each format stores them

FormatStorageExample
Mermaid%% comment lines%% @schematlas node api code=src/api.rs:12-80
DBML// comment lines// @schematlas node public.orders note="Orders"
draw.ioCell propertiesschematlas-code="src/api.rs:12-80"

Details: Mermaid, DBML, draw.io.

Line syntax

Mermaid and DBML share one grammar:

text
@schematlas diagram ...
@schematlas node <id> ...
@schematlas edge <from> <to> [n] ...

Values are single words or double-quoted strings with \", \\ and \n escapes. Lists repeat the key (code=), except tags, which is comma-separated. A key without a value is kept as empty.

Edit this page