Model reference

Every field of a compiled diagram, and every way the compiler can reject one. Source of truth: packages/core/src/types.ts, packages/core/src/validate/, and each notation's validate.ts under packages/core/src/notations/ (activity's under packages/core/src/activity/).

For why the model is shaped like this, see What is in a model.

DiagramModel

Style preset ids: clean (default), sketch, hand-drawn, pencil, blueprint, marker.

DiagramNode

Asset refs (image, shape)

Two forms are accepted, and nothing else:

• ^[a-z0-9]+\.(png|jpe?g|svg|webp|gif)$ — a content-hashed file in .diagrams/src/assets/.
• ^/library/[a-z0-9-]+/[a-z0-9-]+\.(png|jpe?g|svg|webp|gif)$ — a bundled library asset. Exactly one directory level, lowercase kebab-case only.

Column

ContainmentEdge

A node may appear as child in several edges — containment is a DAG. Cycles are rejected per plane.

Because an absent plane resolves to whichever plane was declared first, plane declaration order is semantically significant in a multi-plane model. A plane using containmentOf borrows only the edges tagged for the plane it names.

DiagramRelation

RelationStyle

EdgeLabel

DiagramLayer

DiagramPlane

DiagramLegend

Present only if the diagram declares one. See Add a legend.

Derived rows come from two different places, and the difference is visible:

• kinds and types come from the compiled view — the arrows and boxes actually drawn. They follow the active plane, the active layers and what is currently unfolded; a kind whose only arrows are behind a switched-off layer has no row. Order within the section is the built-in registry's, then alphabetical for ids it does not know.

• layers comes from the model, per plane — every declared layer that something the active plane could draw carries, whether it is switched on or off, in declaration order. Folding changes nothing here: a layer row is the switch that reveals its overlay, so it has to stay put while the overlay is hidden. When the plane borrows another's containment (containmentOf), relevance is resolved against the donor plane, the same way the view is; when you have drilled into a node, it is resolved against that node's interior.

• marks comes from the compiled view as well — a threat badge per state on screen (open, all handled), counted the way the canvas counts it: a node's own threats, and every relation a drawn arrow stands for. A drawn table's pk and fk columns add the 🔑 and FK rows.

A types row is captioned with the type's subtitle, or its id. The activity and threat-model shapes and the fk, activity and data-flow kinds carry a caption in words instead (Start, Process, Foreign key: many to one); those are the rows a legend with no show lists under Elements, and one of them — or a mark — drawn on a diagram with no legend at all is what puts the ▤ button on its canvas, the panel hidden until asked for. Such a legend is never exported.

Inactive layer rows are listed greyed wherever the host can toggle them (the studio). Where nothing can — a published page, an exported PNG — they are omitted instead of shown as a row no click can change.

A kinds swatch is the kind's registry style, line ends included, tinted when every drawn arrow of that kind shares one layer tint. A types swatch is the type's shape, in the accent every drawn node of that type shares. A per-relation style.color describes one arrow rather than the kind, so it is never lifted into a row.

LegendItem

An item naming a kind or type that already has a derived row recaptions that row in place, keeping its position and swatch, instead of appending a new one.

LayoutOverlay (<name>.layout.json)

settings, unfolded, edgeLabels and notes are keyed by the resolved containment plane (layoutPlaneKey), the same as planes and manual — so a plane that borrows containment with containmentOf shares the donor's entry rather than having its own.

LayoutSettings

export.collapsed lists node ids to keep FOLDED in the PNG only; the interactive page ignores it and opens the way unfolded says (fully folded when absent), so the reader unfolds what they want. The exporter otherwise unfolds every container, which turns a view with hundreds of leaves into an unreadable thumbnail. Folding rather than the plane's hides is the right tool when the edges matter: a folded box still ANCHORS its hidden children's edges, where a hidden node drops them. Ids that are not containers have no effect.

Drawings (<name>.drawings.json)

Freehand strokes drawn with the studio's pen. A third sidecar beside the layout file — also not part of the model, and kept out of the layout file so a box nudge and a scribble never share a hunk.

Stroke

Strokes are positional, not anchored: automatic layout can move boxes out from under them. They are shown at the top level only — a drilled-in container is laid out in its own coordinate frame. A file in which no plane holds a stroke is deleted on save rather than written empty.

{
  "version": 1,
  "planes": {
    "default": [{ "id": "k1", "points": [120, 80, 131, 84, 150, 97], "color": "#d9a520", "width": 4 }]
  }
}

Git graph conventions

A plane with notation: 'git-graph' reads ordinary nodes and relations as a branching diagram. Nothing new is stored.

A commit's column is one past every commit it follows, branches from or merges, plus its gap. The layout never fails: a cycle is cut, a commit outside every lane is parked beneath the lanes — and validation reports both (git-* codes below).

Activity diagram conventions

An activity-frame node containing activity-lane nodes reads as a UML swimlane diagram. Nothing new is stored — no notation, no plane; frames are ordinary containment, and several can share a canvas.

Node types

Relation kinds

A guard is a plain relation label (e.g. [order accepted]) — there is no dedicated guard field.

Second-order thinking conventions

A plane with notation: 'second-order' reads ordinary nodes and relations as a consequence tree. Nothing new is stored — valence is a node type, not a field.

Node types

Relation kind

A node's order (which band it draws in) is never stored — it is derived as the longest path from any decision, over every relation between two second-order nodes, not just leads-to ones. See Draw a second-order thinking diagram.

Fishbone conventions

A plane with notation: 'fishbone' reads ordinary nodes and relations as a fish. Nothing new is stored.

Relation kind cause-of, drawn from the cause to what it explains: category → effect, cause → category, sub-cause → cause. What hangs where is derived from the first relation between two fishbone nodes, whatever its kind, and never stored; three levels below the effect is the limit. See Draw a fishbone diagram.

Threat-model conventions

A plane with notation: 'threat-model' reads ordinary nodes and relations as a STRIDE data-flow diagram.

Relation kind data-flow — a plain solid arrow, drawn from the source of the data to its destination. Flows are one-way; a request and its response are two relations.

Trust boundaries are containers. A boundary surrounds its elements through ordinary containment, so which boundaries a flow crosses is derived from the active plane's containment and never authored: the nearest tm-boundary above each end, or outside where there is none, and a relation whose two ends land in different boundaries is a crossing. The derivation follows the first parent by declaration order where containment is a DAG, and ignores the relation's kind — a crossing is a fact about the drawing. Because a boundary is containment, a data-flow must join two elements; one wired to a boundary itself fails validation (tm-flow-boundary).

A boundary never folds under semantic zoom — it is a line around things, not a level you drill into — so its elements and their crossings are always on screen.

Threat

threats?: Threat[] sits on a node or a relation and is legal in any notation, like technology — an existing C4 or ER diagram can be threat-modelled where it stands, or gain a threat-model plane with its own boundary containment over the same nodes. The register is derived from these lists; there is no model-wide threat array.

Which categories apply to an element is guidance (STRIDE-per-element), not a rule — the studio offers them first and every other category behind them:

See Draw a threat model.

Comment

comments?: Comment[] sits on a node or a relation in any notation. The canvas shows a count at the element's bottom-right corner (a quarter of the way along an arrow); clicking it opens the element's bubble — the same bubble a threat register uses — with the comments listed.

Link

links?: Link[] sits on a node and lists resources — a ticket, a design doc — in the bubble under the comments. It is separate from link, the node's single navigation target behind the 🔗 badge.

Validation codes: invalid-comments, comment-id, comment-text, comment-at, invalid-links (see Validation codes).

Plan conventions

A plane with notation: 'plan' is a schedule: a calendar runs left to right and the plane's containment is what is scheduled inside what. The layout owns every x (it is a date); only a top-level zone takes its y from the layout overlay.

Relation kinds owns, executes, checks — drawn from the actor (a person or a team) to the zone, never as arrows: each becomes a chip on the zone (O·Alice, E·Bob, C·Chen; hover for the full name). Any other kind between zones (sync, …) draws as a dependency arrow.

Dates live in metadata (the git-graph from/to pattern) so a zone is an ordinary node everywhere else. The x origin is 1 January of the earliest year in the plan; the header extends a week either side of the dated range.

See Draw a plan.

Causal-loop conventions

A plane with notation: 'causal-loop' reads ordinary nodes and relations as variables and signed links. Nothing new is stored.

kind is not read — the loop arithmetic uses only each link's ends and its polarity. The examples write influence, which draws as a plain arrow.

Loops are derived, never stored. Every closed ring among the arrows actually drawn is a loop, so a layer switched off, or a plane that leaves a variable out, changes them. Links running the same direction between two variables count as one, unsigned if their polarities disagree. An even number of - links makes a loop R (reinforcing), an odd number B (balancing), and any unsigned link makes it ?. Up to 50 loops of at most 20 variables are badged, shortest first, each badge anchored just off the top-right corner of its loop's lowest-id variable, then nudged outward until it clears the boxes and the badges already placed.

invalid-polarity and invalid-delay are checked on every relation, whatever the notation. See Draw a causal-loop diagram.

ER conventions

There is no ER notation. A schema is nodes of one type joined by relations of one kind, so tables share a plane with anything else.

Each end of an fk is pinned to its column's row where the edge meets a left or right border; on a top or bottom border it floats to the middle like any other relation. With no toColumn, the renderer falls back to the target's first pk column — m.fk is stricter, and throws unless the target has exactly one.

A column's fk flag prints the FK marker and nothing else: what routes the edge is the relation's fromColumn. m.fk does not set the flag; the studio's row-to-table drag does.

A column with a layer is drawn only while that layer is active, and the table shrinks by its row while it is not. Its layer gets a legend row like any other, even when no node or relation uses it. An edge anchored to a hidden row floats to the table's middle, so put an fk relation on the same layer as its column. Deleting the layer deletes its rows and the relations anchored to them; merging it retags them.

duplicate-column and invalid-columns are checked on any node that has columns, and unknown-column on any relation naming a fromColumn or toColumn — whatever the node's type or the relation's kind. See Draw an ER diagram.

Validation codes

validate() returns issues; the compiler refuses to write an artifact if there are any, and the studio refuses to save. diagramWarnings() returns the codes marked warning below, in the same shape: they never block a compile or a save. The compiler prints them, and the notation's panel lists them.

Lint codes

Also returned by diagramWarnings(), so compile prints them and diagc lint fails on them. Each is a diagram that validates but probably does not say what was meant.

Registry defaults

Strings the renderer already knows. Anything else falls back to a plain box or a plain line.

Node types — system, platform (dashed boxes); service (box + icon); database, aws-rds, table (cylinders); db-table (ER table); queue (pill); infra (hexagon); person (pill); comment (speech bubble — an ordinary node for remarks, wired up with normal relations); and the 33 c4-* types listed in Library reference.

Relation kinds — sync, async (dashed), reads, writes (thick), hosted-on (dashed), flow (animated), mixed (thick, used for aggregates), fk (crow's foot to bar), network and influence (plain), plus each notation's kinds in its conventions above.

An aggregate edge (one arrow standing for several relations, after a fold) labels itself from its constituents: their distinct labels joined with / while that stays within 32 characters, or a single distinct label whatever its length, and otherwise N relations. Single-relation edges always carry their own label. Long labels are ellipsised at ~24 characters when drawn; the arrow's hover title carries the full text. See Views.

Shapes — box, cylinder, pill, hexagon, table, bubble (a rounded box with a tail at the bottom-left; the tail hangs outside the node's layout box, so spacing and edge attachment behave exactly as for a box).

Icons — database, postgres, table, user, cloud, mail, service, system, queue, server, kubernetes, infra, browser, spa, mobile, desktop, api, function, cli, blob, search, component, interface, class, node, instance, comment.

See also

• Builder API — the TypeScript way to produce this.
• What is in a model — the reasoning.
• Draw on a diagram — the pen that writes the drawings sidecar.