Flow graph schema

Each flow is a JSON document at .fetchcatch/flows/{slug}.json.

Top-level shape

{
  "schemaVersion": 1,
  "id": "00000000-0000-0000-0000-000000000001",
  "slug": "approve-expense",
  "name": "Approve expense",
  "description": "Optional human description",
  "graph": { ... },
  "publish": false
}

Field	Required	Description
`schemaVersion`	yes	Must be `1` for this doc version
`id`	yes	Stable GUID; do not change after first apply
`slug`	yes	URL-safe identifier; matches filename
`name`	yes	Display name
`description`	no	Free text
`graph`	yes	Flow graph (see below)
`publish`	no	Legacy. If `true`, `fcc apply` also publishes (back-compat only). Leave `false` or omit in git; ship with `fcc publish` instead — see sync-and-ci.md.

Graph object

{
  "start": "start_1",
  "nodes": [ ... ],
  "edges": [ ... ],
  "viewport": { "x": 0, "y": 0, "zoom": 1 }
}

Field	Required	Description
`start`	yes	Node `id` of the start node
`nodes`	yes	Array of node objects
`edges`	yes	Array of edge objects
`viewport`	no	Designer canvas state (cosmetic)

Node object (common fields)

{
  "id": "http_1",
  "type": "http",
  "label": "Fetch user",
  "description": "Loads user profile from CRM",
  "position": { "x": 120, "y": 80 }
}

Field	Description
`id`	Unique within graph; must match `^[A-Za-z_][A-Za-z0-9_]*$`
`type`	One of: `start`, `http`, `condition`, `transform`, `wait_for_event`, `decision`, `end`
`label`, `description`	UI-only; safe for agents to add for clarity
`position`	UI-only coordinates

See flow-nodes.md for type-specific fields.

Edge object

{
  "from": "condition_1",
  "to": "http_2",
  "when": "true"
}

Field	Required	Description
`from`	yes	Source node id
`to`	yes	Target node id
`when`	condition only	`"true"` or `"false"` for branches leaving a condition node

Non-condition nodes typically omit when.

Validation rules (summary)

Exactly one start node; graph.start must reference it.
Node ids must be unique and match the identifier regex.
http nodes need apiSourceId + operationId.
condition nodes need expression.
wait_for_event nodes need eventName.
Graph must be reachable from start; terminal nodes are typically end.
decision nodes should have an outgoing edge to end (legacy terminal decisions still run but are discouraged).

Editing guidance for AI agents

Preserve id, schemaVersion, and existing node ids unless explicitly renaming.
Do not invent apiSourceId values — they must exist in the tenant (configure in console or pull first).
Prefer small, focused edits to expressions, edges, or responseValues.
Run fcc status after edits; invalid graphs fail on apply with server-side validation errors.
Use description on nodes to document intent for future agents.
Do not set "publish": true in CI repos — run fcc apply then fcc publish (or publish from the console).