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 — trigger is 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

FieldRequiredTypeDescription
kindyes"state"Must be exactly "state"
titlenostringRendered above the diagram
statesyesarray of StateAt least 2 states required
transitionsnoarray of TransitionMay be empty (unconnected states)

State fields

FieldRequiredTypeDescription
labelyesstringDisplay text. Must be unique unless id is set.
idnostringStable identifier for from/to references. Falls back to label if omitted.
rolenostring"initial" or "terminal". At most one "initial"; multiple "terminal" allowed.

Transition fields

FieldRequiredTypeDescription
fromyesstringid (preferred) or label of source state
toyesstringid (preferred) or label of target state
triggernostringEvent or condition causing this transition
typenostring"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

Order Lifecycle States: Pending (initial), Processing, Completed (final), Cancelled (final). Transitions: Pending → Processing on Order Received; Processing → Completed on Payment OK; Processing → Cancelled on Payment Failed (exception). Order Lifecycle Pending Processing Completed Cancelled Order Received Payment OK Payment Failed

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.

SlotMeasured inHangul (unchanged / whole)Latin (unchanged / whole)
states[].label3 states7 / 3014 / 55
transitions[].trigger3 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

FieldTypeRequiredValues / meaning
kindenumyesstate
titlestringno

states — 2 or more elements

FieldTypeRequiredValues / meaning
labelstringyes
idstringnoa short name to refer to the state by
roleenumnoinitial, terminal

transitions — any number of elements

FieldTypeRequiredValues / meaning
fromreferenceyesa state's id or label
toreferenceyesa state's id or label
triggerstringno
typeenumnonormal, exception

Rules

  • state labels are unique
  • state ids are unique
  • at most one state has the role initial
  • from and to name an existing state's id or label