StepFlow DSL Specification

The StepFlow DSL (Domain Specific Language) defines workflows as JSON documents with declarative state machines.

Workflow Structure

{
  "description": "Optional workflow description",
  "version": "1.0",
  "entry": "FirstStep",
  "timeoutSeconds": 3600,
  "steps": {
    "FirstStep": { ... },
    "SecondStep": { ... }
  }
}

Top-Level Fields

Field	Type	Required	Description
`entry`	string	Yes	Name of the first step to execute
`steps`	object	Yes	Map of step name → step definition
`description`	string	No	Human-readable description
`version`	string	No	Workflow version identifier
`timeoutSeconds`	integer	No	Maximum execution time

Step Common Fields

All step types share these fields:

Field	Type	Description
`type`	string	Step type: `task`, `set`, `wait`, `router`, `parallel`, `map`, `succeed`, `fail`
`description`	string	Optional step description
`next`	string	Next step name (mutually exclusive with `end`)
`end`	boolean	Marks workflow termination
`set`	object	Variables to set after execution
`output`	object	Output mapping for next step's input

Execution Flow

┌─────────┐    ┌─────────┐    ┌─────────┐
│  Entry  │───▶│  Step   │───▶│  Step   │───▶ End
│  Step   │    │  (next) │    │  (end)  │
└─────────┘    └─────────┘    └─────────┘

Execution starts at entry step
Each step processes, then transitions via next
Execution ends when a step has end: true

State Types Overview

Type	Purpose	Key Fields
task	Execute an action	`action`, `parameters`, `mode`
set	Set variables without action	`set`, `output`
wait	Pause execution	`seconds` or `timestamp`
router	Conditional branching	`routes`, `default`
parallel	Concurrent branches	`branches`, `maxConcurrency`
map	Iterate over array	`items`, `itemProcessor`
succeed	Successful termination	`output`
fail	Failure termination	`error`, `cause`

Next Steps

See State Types for detailed documentation of each type
See Data Mapping for expression syntax
See JSON Schema for full schema reference

Overview State Types