Skip to content

Advanced YAML Format

Vivek Sarin edited this page Nov 20, 2026 · 2 revisions

Advanced: YAML format

Use event YAML when you need explicit dependencies, branching, waiting, or process durations. Layout is automatic; YAML does not expose per-node coordinates. For narrated scenes and per-scene visibility or colors, use a storyboard.

This page is an introduction. The authoring reference is the complete keyword catalog for people and AI tools. The cookbook provides a complete fork/join/branch example.

Example

diagram: { direction: TB, edgeLabels: true } # show payloads on connectors
groups:
  - { id: platform, label: Platform }
  - { id: data, label: Data tier, parent: platform }
nodes:
  - { id: api, group: platform, shape: round, style: { fill: "#e6efff", stroke: "#2f6fed" } }
  - { id: db, group: data, shape: cylinder }
flows:
  - { id: f, from: api, to: db, payload: query, line: dotted, head: circle }

Node shapes

rect, round, stadium, diamond, circle, cylinder, hexagon, subroutine, parallelogram, start, end, bar, and class.

Lines and arrowheads

  • line: solid, dotted, or thick.
  • head and tail: none, arrow, circle, cross, triangle, diamond, or diamond-filled.

Events

By default, every node runs once, and every arrow carries one packet, in the order of the graph. Add events only when you need to control the order.

Event Used on Purpose
transfer Arrow Moves a packet along the arrow
process Node Works on the input for a while
emit Node Sends output
complete Node Finishes the node
wait Node Waits until all the events listed in until: have finished
join Sync point Waits for all live inputs; continues if at least one path was taken
fork Sync point Dependency marker for parallel child events
branch Node Takes the events listed in select:. The others are skipped
  • Use after to declare that one step depends on another.
  • Use fail: true to end a process in an error state.
  • Events without dependencies run concurrently; list order does not serialize them.
  • An omitted or empty events list enables automatic graph animation.

Layout and connectors

Set these in the diagram: block, or on a single flow:

  • diagram.direction: the direction of the layout. Use LR (left to right, the default), RL, TB (top to bottom), or BT.
  • diagram.edgeLabels: true shows each flow's payload as a label on its arrow. The default is false.
  • curve: true draws a flow as a curve. Curves can help when arrows overlap.
  • headLabel and tailLabel: a short note at the target or source end of a flow, such as 1 or 0..*. Up to 20 characters.
  • style: a set of colours and widths. The keys are fill, stroke, color, and strokeWidth (0 to 12). You can use style on a node or a flow.

Groups

Use groups to draw a labelled box around nodes. A group can sit inside another group. Set parent to the id of the outer group.

groups:
  - { id: platform, label: Platform }
  - { id: data, label: Data tier, parent: platform }
nodes:
  - { id: db, group: data, shape: cylinder }

Animation settings

Use the animation: block to set how the diagram plays:

animation: { autoplay: true, loop: true, speed: 1 }
  • autoplay: true (the default) starts the diagram when it appears.
  • loop: true (the default) repeats the animation.
  • speed: the speed multiplier, from 0.1 to 10. The default is 1.

Events for sync points

  • wait (on a node) waits until every event listed in until: has finished.
  • fork is a dependency marker. Its dependent events can start together; it does not create packets by itself. join waits for live predecessor events.
  • branch (on a node) takes the events listed in select:. The other events are skipped.

Use after: to show that a step must wait for another event, and duration: to set how long a step takes, in milliseconds (up to 60000).

A branch takes only the events it lists in select:. Each of those events must list the branch in its after::

nodes:
  - { id: a, label: A }
  - { id: b, label: B }
flows:
  - { id: f, from: a, to: b }
events:
  - { id: br, type: branch, node: a, select: [p1] }
  - { id: p1, type: process, node: a, duration: 500, after: br }
  - { id: w1, type: wait, node: b, until: [p1] }
  - { id: t1, type: transfer, flow: f, after: w1 }

Limits

  • There is no loop event. Feedback loops are written as separate events.
  • A branch chooses its path from the list you write. FlowMotion does not calculate the choice from data.

Related pages

Clone this wiki locally