YAML Pane

The YAML pane is a live, bidirectional text editor that stays in sync with the visual canvas. Every change you make on the canvas is immediately reflected in the YAML, and any valid YAML you type is instantly applied back to the canvas.

Opening the YAML pane

Click the YAML tab in the top-right toolbar of the workflow editor. The pane opens alongside the canvas. You can resize the split.

How sync works

The pane and the canvas share a single AST (Abstract Syntax Tree) as their source of truth. The sync flow is:

Canvas AST
    │
    ▼
astToYaml(ast) ──────────▶  YAML textarea
                                  │
    ▲                    user types YAML
    │                         │
    └──── yamlToAst(raw) ◀─── debounce ~300ms

When you edit YAML, the pane waits ~300ms after you stop typing, parses the YAML, and if it is valid, dispatches a replace-ast mutation to the editor. The canvas re-renders immediately.

When the canvas changes (e.g., you drag a new node), the YAML textarea updates to reflect the new AST - unless the pane has keyboard focus (see YAML lock below).

YAML lock

While the YAML textarea has keyboard focus, incoming canvas changes do not overwrite your in-progress text. A small lock indicator appears in the top-right corner of the pane to signal that the YAML is locked.

When you click away (blur), the pane reconciles:

If the canvas did not change while you were typing: your edits were already applied to the AST on each keystroke. No conflict.
If the canvas changed while you were typing (e.g., another user or an auto-arrange): a conflict banner appears:

"Canvas changed - discard YAML edits or Apply"

Choose Apply to push your YAML edits (overwriting the canvas change) or Discard to snap back to the current canvas YAML.

The "last write wins" policy means the pane never silently discards work. The conflict banner always gives you an explicit choice.

Parse errors

If your YAML is invalid (syntax error or schema violation), the pane shows an inline error banner below the textarea with the error message. The AST is left unchanged - the canvas keeps running the last valid state. The invalid text stays in the textarea so you can fix it.

Example error:

YamlCodecError: Unexpected token at line 12, column 5: expected mapping value

Errors do not propagate to the canvas. You will never corrupt a workflow by typing invalid YAML.

Round-trip stability

The YAML codec (astToYaml / yamlToAst) is designed to be round-trip stable:

{{ }} expression strings are double-quoted on export to prevent the YAML parser from misinterpreting curly braces as YAML mappings.
Node IDs, edge source/target references, and group scope paths are preserved verbatim.
Exporting to YAML and re-importing produces the same AST (verified by the export test suite).

YAML format

The workflow YAML follows the platform's definition schema v2. A minimal example:

version: "2"
metadata:
  name: My Workflow
  projectScope: []
spec:
  trigger:
    kind: event
    nodeId: trigger-1
  steps:
    - id: trigger-1
      type: trigger
      providerId: linear
      definitionId: linear.issue.assigned
      config: {}
    - id: action-1
      type: action
      providerId: linear
      definitionId: linear.issue.update
      config:
        issueId: "{{ nodes.trigger-1.issue.id }}"
        status: In Progress
  edges:
    - source: trigger-1
      target: action-1

Key YAML fields:

Field	Description
`version`	Schema version - always `"2"` for current workflows
`metadata.name`	Workflow display name
`metadata.projectScope`	List of project slugs this workflow belongs to
`spec.trigger`	Trigger configuration (kind, nodeId)
`spec.steps[]`	All nodes (trigger, action, condition, gate, group, loop, annotation, etc.)
`spec.steps[].id`	Unique node ID (used in edge source/target and `{{ nodes.<id> }}` expressions)
`spec.steps[].type`	Node category (`trigger`, `action`, `condition`, `gate`, `parallel-group`, `loop`, `annotation`)
`spec.steps[].providerId`	Provider owning this node (e.g., `linear`, `github`, `donmai`)
`spec.steps[].definitionId`	Node type ID (e.g., `linear.issue.assigned`)
`spec.steps[].config`	Node-specific configuration (provider-defined shape)
`spec.edges[]`	Connections between nodes
`spec.edges[].label`	Optional edge label (e.g., `"true"`, `"false"`, `"approved"`, `"timeout"`)

Importing and exporting YAML

You can work with YAML files directly:

Export - from the workflow controls menu, choose Export → YAML to download the current definition as a .yaml file.
Import - from the controls menu, choose Import to paste or upload a YAML (or JSON) file. The editor validates and replaces the current canvas.
Import sub-flow - imports an existing workflow as a group into the current canvas at the scope level you are viewing.

Editing tips

Use the YAML pane to make bulk edits quickly - for example, updating all nodes with a common config field, or renaming a step ID across multiple edges at once.
{{ }} expressions must be quoted in YAML. The exporter does this automatically; if you type them manually, wrap in double quotes: "{{ nodes.myNode.value }}".
Gate handle edges (e.g., approved, rejected, timeout) must use a matching label on the edge AND the node must be serialized via canvasToDefinitionV2 with step.branches. If you see a gate with wired handles that are not routing, verify the branches field is present under the gate step in the YAML.
Group step bodies appear as nested steps: and edges: under the group step in the YAML, not as a flat list.

No syntax highlighting

The YAML pane is a plain textarea - it does not ship Monaco or CodeMirror. Syntax highlighting is intentionally out of scope to keep the bundle lean. For complex edits, export the YAML, edit in your local editor, and import back.

Canvas - visual editing and the AST model
Node Config Panels - field-level configuration
Expressions - {{ }} interpolation syntax
Versioning - snapshots, diff, and rollback
Validation - canvas-to-definition validation and known edge cases
Groups - how groups appear in the YAML schema

On this page