Docs

Workflow YAML

The technical shape of Gondo workflow definitions, including version, run display, variables, nodes, edges, and schema rules.

Workflow YAML is the technical format Gondo uses to describe a workflow graph.

You do not need to write YAML to use Gondo, but it is useful for inspecting or precisely editing workflows.

What belongs in workflow YAML

The normalized graph definition focuses on:

Key	Meaning
`version`	The persisted workflow definition version. Gondo manages this when editing and publishing.
`runDisplay`	How each run should be named in Activity.
`variables`	Optional string values available as `ctx.vars.<name>`.
`nodes`	The workflow steps, keyed by node ID.
`edges`	Directed connections between nodes.

The workflow title shown in lists is workflow metadata, not part of the normalized graph definition. Edit the title through workflow settings, not by treating name as a graph key.

YAML parser rules

Workflow YAML must be simple and explicit.

It must contain exactly one YAML document.
YAML anchors are not supported.
YAML aliases are not supported.
YAML tags are not supported.
Unknown keys are rejected.

This keeps workflow definitions predictable for both people and agents.

Minimal structure

version: 1
runDisplay:
  title: 'Run {{ ctx.run.id }}'
variables:
  destinationSheetId:
    label: Destination sheet
    description: Where approved rows are written.
    value: 1abc...
nodes:
  command_start:
    id: command_start
    type: trigger
    title: Run
    config:
      kind: command
      name: review-invoices
      dataSchema:
        type: object
        properties: {}
        required: []
    ui:
      x: 0
      y: 0
edges: []

In this example, config.name belongs to the command trigger. It is not a workflow-level name.

`runDisplay`

runDisplay.title controls how each run appears in Activity.

Templates can read:

ctx.run.id
ctx.run.status
ctx.run.startedAt
ctx.vars.<name>
ctx.data.<nodeId>.<field> when that data exists

Prefer stable early data, such as trigger fields or variables.

runDisplay:
  title: 'Invoice {{ ctx.data.command_start.invoiceNumber }}'

Variables

Variables are strings available as ctx.vars.<name>.

Use variables for stable workflow values that are not secrets, such as a destination sheet ID, folder ID, project key, or default reviewer email.

Do not store API keys, tokens, passwords, or secrets in variables.

variables:
  reviewerEmail:
    label: Reviewer email
    value: finance@example.com

Nodes

Nodes are stored under nodes, keyed by stable node ID.

Each node must include:

id
type
title
config
ui

Optional fields include:

goal
integrations

The id must match the node key.

nodes:
  classify_invoice:
    id: classify_invoice
    type: task
    title: Classify invoice
    goal: Decide whether the invoice needs review.
    integrations:
      - finance_gmail
    config:
      instruction: |-
        Read the invoice details from ctx.data.command_start.
        Return whether it needs human review.
      dataSchema:
        type: object
        required: [needsReview]
        properties:
          needsReview:
            type: boolean
    ui:
      x: 420
      y: 0

Edges

Edges connect nodes.

Each edge includes:

id
source
target

Optional fields:

label
condition

Conditions are JavaScript strings that return a boolean. They can read upstream outputs from ctx.data.

edges:
  - id: invoice_needs_review
    source: classify_invoice
    target: approve_invoice
    label: Needs review
    condition: return ctx.data.classify_invoice.needsReview === true

JSON Schema rules

Node outputs and trigger inputs use JSON Schema.

At the root, schemas should be objects.

dataSchema:
  type: object
  required: [supplierName, amount]
  properties:
    supplierName:
      type: string
    amount:
      type: number

When a root schema is an object and additionalProperties is omitted, Gondo treats additional properties as false.

This makes downstream references more reliable.

Build Your First Workflow

Node Types