State
A state diagram represents a system's lifecycle as a set of named states and directed transitions between them.
Scope
state is a named lifecycle for prose — the diagram that explains how an order, a ticket, or a
deployment moves through its stages in a report or design document. It is not an executable state
machine notation:
- No guards, entry/exit actions, or internal transitions —
triggeris a display label only. - No nested (composite), parallel (orthogonal), or history states.
- Transitions connect only declared states; layout is chosen by the engine.
If a diagram needs any of the above, use an engineering tool such as Mermaid, D2, or PlantUML.
Fields
| Field | Required | Type | Description |
|---|---|---|---|
kind | yes | "state" | Must be exactly "state" |
title | no | string | Rendered above the diagram |
states | yes | array of State | At least 2 states required |
transitions | no | array of Transition | May be empty (unconnected states) |
State fields
| Field | Required | Type | Description |
|---|---|---|---|
label | yes | string | Display text. Must be unique unless id is set. |
id | no | string | Stable identifier for from/to references. Falls back to label if omitted. |
role | no | string | "initial" or "terminal". At most one "initial"; multiple "terminal" allowed. |
Transition fields
| Field | Required | Type | Description |
|---|---|---|---|
from | yes | string | id (preferred) or label of source state |
to | yes | string | id (preferred) or label of target state |
trigger | no | string | Event or condition causing this transition |
type | no | string | "normal" (default) or "exception" — semantic type |
Self-loop transitions (from = to) are valid. Transition without trigger is valid (unconditional).
Cross-reference resolution
If a state has an id, use id in from/to. If it has no id, use label.
Unknown references → validation error. Duplicate labels without id → validation error.
Example
Label capacity
How long a label can be before the engine sets it smaller, wraps it, or cuts it short with "…". Each number is measured by rendering a small reference declaration with a growing label and reading the diagnostics render_detailed returns, so the table always agrees with them. Lengths are in characters written without spaces: Hangul syllables are one em wide, Latin lowercase letters about half that. unchanged is the longest label shown at the usual size on one line; whole is the longest shown without "…". A slot's width depends on its siblings, so read a number as a guide for the reference declaration named in the second column and use declart validate --strict for the declaration itself.
A dash means the engine reports nothing for the slot up to 120 characters. That is not a promise that any length fits: a slot the engine does not fit at all draws a long label past the picture without a warning.
| Slot | Measured in | Hangul (unchanged / whole) | Latin (unchanged / whole) |
|---|---|---|---|
states[].label | 3 states | 7 / 30 | 14 / 55 |
transitions[].trigger | 3 states | — / — | — / — |
Schema
What a declaration of this kind may contain, as declart schema and schema() report it. The value lists and counts are the ones the parser checks, and a test holds every field, count and rule to the parser in both directions, so a declaration written to this page parses. The prose above is the explanation; this is the reference.
Fields
| Field | Type | Required | Values / meaning |
|---|---|---|---|
kind | enum | yes | state |
title | string | no |
states — 2 or more elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
label | string | yes | |
id | string | no | a short name to refer to the state by |
role | enum | no | initial, terminal |
transitions — any number of elements
| Field | Type | Required | Values / meaning |
|---|---|---|---|
from | reference | yes | a state's id or label |
to | reference | yes | a state's id or label |
trigger | string | no | |
type | enum | no | normal, exception |
Rules
- state labels are unique
- state ids are unique
- at most one state has the role
initial fromandtoname an existing state's id or label