diagram.yaml reference

Every key a diagram accepts. Unknown keys are errors. For explanations and examples see the format guide and scenarios. A JSON Schema with the same fields, for editors, is written by pnpm idocs schema.

Enumerations

Name	Values
status	built (default), planned, legacy, optional
family	blue, amber, violet, green, teal, red, slate
step kind	request (default), response, error, lookup, event
direction	AUTO (default), RIGHT, DOWN, LEFT, UP
node kind	client, user, ui, external, service, gateway, worker, container, function, database, cache, storage, queue, agent, network, vm, auth, monitor, entity, or your own
edge kind	http (default), channel, tunnel, queue, ws, data, or your own

Ids (the keys of nodes, groups, views, scenarios, kinds and edgeKinds, and edge ids) may contain letters, digits, _, . and -.

Top level

Key	Type	Required	Description
$schema	string	no	The path to the JSON Schema, for editors.
title	string	yes	The diagram’s name.
description	Markdown	no	Shown above the first view with showDescription.
nodes	map of node	yes	The boxes. A bare string is a title.
groups	map of group	no	Zones and frames. A bare string is a label.
edges	list of edge	no	The arrows.
views	map of view	no	Slices of the model.
scenarios	map of scenario	no	Stories that play over a view.
defaults	defaults	no	How the diagram opens.
kinds	map of kind	no	Your own node kinds.
edgeKinds	map of edge kind	no	Your own edge kinds.

Node

Field	Type	Default	Description
title	string	the id	The display name.
sub	string		One monospace line under the title.
pill	string		A short label in the card header, like TABLE.
lines	list of strings		Short body lines inside the card.
fields	list of fields		Makes the card an entity. Each item is name, name: type or name: { type?, key?, ref?, note? }. See entities.
icon	string	the kind’s icon	postgresql, logos:redis, simple-icons:keycloak, lucide:server or ./path.svg.
kind	string		A node kind. Gives a default icon and family.
family	family	the kind’s	The accent colour.
in	id		The group the node belongs to.
status	status	built
badge	string or number		A marker on the card’s corner.
uses	list of strings		Tags drawn as uses: a · b. Entries matching a node id become links.
chips	list of string or { label, sub? }		Small boxes inside the card.
w	integer	178 (280 with fields)	The card width in pixels.
description	Markdown		Shown in the drawer.
doc	path	nodes/<id>.md if present	A Markdown file for the drawer, relative to the diagram folder.
links	list of { label, url }		Shown in the drawer.
refs	list of strings		Source files or URLs the node is based on. Stale paths produce a warning.
tags	list of strings		Free-form tags.
diagram	string, or { name, view?, scenario?, mode?, expanded? }		Another diagram that shows the inside of this node. The card gets Expand and Open; mode limits it to one (expand or open) and expanded: true starts it expanded. See nested diagrams.

Group

Field	Type	Default	Description
label	string	required	Shown in capitals in the corner.
caption	string		Muted text after the label.
in	id		The parent group. A group with in is drawn as a dashed frame.
layout	flow, row, grid	flow	row and grid pack members tightly.
columns	integer		The column count of a grid, or where a row wraps.
rows	list of lists of ids		Explicit rows of direct members, top to bottom.
direction	AUTO, RIGHT, DOWN	AUTO	The flow direction inside a top-level group.
family	family
status	status	built
icon	string

Edge

Write an edge as a -> b: label, a <-> b, a -> b: { ... } or with from and to.

Field	Type	Default	Description
id	id	its position	Must be unique.
from, to	id	required	The two nodes.
label	string		Short text on the line.
kind	edge kind	http	The line style.
both	boolean	false	An arrow at both ends.
hidden	boolean	false	Not drawn, but scenarios can use it.
status	status	built
key	string	assigned	The letter on the edge and in the interfaces table.
auth	string		Interfaces table column.
payload	string		Interfaces table column: what travels.
transport	string		Kept with the edge. Not shown by the built-in renderer yet.
note	Markdown		Kept with the edge. Not shown by the built-in renderer yet.

View

Field	Type	Default	Description
title	string	the id	The tab’s label.
summary	Markdown		Shown above the diagram.
include	all or list of ids	all	Node and group ids. A group includes its members.
exclude	list of ids		Removed after include.
direction	direction	AUTO	The main reading direction.
keys	boolean	false	Put letters on edges.
interfaces	boolean	false	Offer the interfaces table under the diagram. It starts folded; the reader opens it.

Defaults

How the diagram opens. A page’s own props win. See defaults.

Field	Type	Default	Description
view	view id	the view of scenario, else the first	The view shown first.
scenario	scenario id	none	The scenario selected first. It plays on view when both are given.
mode	flow, sequence or story	flow	How a scenario with no mode of its own is drawn.
sidebar	boolean	auto	Whether the panel starts open. Auto is open when there is another view to choose. A narrow widget starts folded either way.
subtitles	boolean	true	The step’s title and description on the bar while the scenario plays.
autoplay	boolean	false	Play scenario as soon as the diagram is on screen. Needs scenario.

Scenario

A scenario needs title and at least one step in steps or phases.

Field	Type	Default	Description
title	string	required
summary	Markdown		The story in a sentence or two.
mode	flow, sequence, story	flow	How it opens.
view	id	the first view	The view it plays on.
lanes	list of lane	a lane per node	The story view’s columns.
phases	list of phase		Steps grouped under titles.
steps	list of step		A flat list of steps.

Lane

Field	Type	Description
title	string	Required.
sub	string	Under the title. Defaults to the node’s sub, or the node titles joined.
nodes	list of ids	Required. At least one. A node can be in one lane.

Phase

Field	Type	Description
title	string	Required.
caption	string	Shown after the title.
steps	list of steps	Required. At least one.

Step

Write a step as a -> b: label, at a: label, par: [ ... ], or with the long keys.

Form	Fields
flow	from, to (required), label, via (list of ids)
self	at (required), label
par	steps: a list of flow or self steps. At least one.

Flow and self steps also accept:

Field	Type	Description
title	string	The box heading in the story view. Defaults to the label.
detail	string	One to three short lines in the story view. Defaults to from → to.
kind	step kind	request (default), response, error, lookup or event.
note	Markdown	Shown in the timeline.
status	status	planned draws the step dashed.
hold	number	Extra seconds to pause.

Kinds and edgeKinds

kinds:
  ledger: { icon: lucide:book-open, family: amber }

edgeKinds:
  grpc: { label: gRPC, color: accent, width: 2, dash: "6 4" }

kinds field	Description
icon	The default icon for nodes of this kind.
family	The default colour family.

edgeKinds field	Description
label	Required. Shown in the legend.
color	A theme token (ink, accent, tunnel, muted, ok, warn, bad) or any CSS colour.
width	Line width in pixels.
dash	An SVG dash pattern, such as "6 4".

Tip

Run pnpm idocs schema and add # yaml-language-server: $schema=../diagram.schema.json to a diagram, and your editor shows these descriptions as you type.