​
JSON Schema

https://compozy.dev/schemas/tasks.json
{
  "type": "object",
  "required": ["tasks"],
  "properties": {
    "tasks": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "type"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the task"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name for the task"
          },
          "type": {
            "type": "string",
            "enum": ["basic", "parallel", "decision", "collection", "wait", "map", "composite"],
            "description": "Task type identifier"
          },
          "use": {
            "oneOf": [
              { "type": "string" },
              {
                "type": "object",
                "required": ["repo", "package"],
                "properties": {
                  "repo": { "type": "string" },
                  "package": { "type": "string" },
                  "version": { "type": "string" }
                }
              }
            ],
            "description": "Task implementation reference"
          },
          "import": {
            "type": "string",
            "description": "Path to external task definition file"
          },
          "schema": {
            "type": "object",
            "properties": {
              "input": { "type": "object" }
            },
            "description": "Schema definition for task input validation"
          },
          "config": {
            "oneOf": [
              { "$ref": "https://compozy.dev/schemas/task-basic.json" },
              { "$ref": "https://compozy.dev/schemas/task-parallel.json" },
              { "$ref": "https://compozy.dev/schemas/task-decision.json" },
              { "$ref": "https://compozy.dev/schemas/task-collection.json" },
              { "$ref": "https://compozy.dev/schemas/task-wait.json" },
              { "$ref": "https://compozy.dev/schemas/task-map.json" },
              { "$ref": "https://compozy.dev/schemas/task-composite.json" }
            ],
            "description": "Task type-specific configuration"
          },
          "retry": {
            "type": "object",
            "required": ["attempts", "backoff", "interval"],
            "properties": {
              "attempts": { "type": "number" },
              "backoff": {
                "type": "string",
                "enum": ["fixed", "exponential", "linear"]
              },
              "interval": { "type": "string" },
              "max_interval": { "type": "string" },
              "jitter": { "type": "boolean" }
            }
          },
          "on_start": {
            "type": "object",
            "properties": {
              "next": { "type": "string" },
              "with": { "type": "object" }
            }
          },
          "on_success": {
            "type": "object",
            "properties": {
              "next": { "type": "string" },
              "with": { "type": "object" }
            }
          },
          "on_error": {
            "type": "object",
            "properties": {
              "next": { "type": "string" },
              "with": { "type": "object" },
              "condition": { "type": "string" },
              "routes": { "type": "object" },
              "retry": { "type": "boolean" }
            }
          },
          "on_complete": {
            "type": "object",
            "properties": {
              "next": { "type": "string" },
              "with": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

​
Task Configuration

​
Properties

​
id
string
required
Unique identifier for the task within the workflow
​
name
string
Human-readable name for the task
​
type
string
required
Task type identifier. One of: basic, parallel, decision, collection, wait, map, composite. See Task Types for detailed information about each type.
​
use
string | object
Task implementation reference. Can be specified in three formats:
  • "repo/package" (e.g., "compozy/tasks:web-search")
  • "repo:package@version" (e.g., "compozy/tasks:web-search@1.0.0")
  • Object with repo and package fields
tasks:
  - id: web_search
    type: basic
    use: compozy/tasks:web-search
​
import
string
Path to external task definition file. Can be a local file path or a package reference.
​
schema
object
Schema definition for task input validation
​
config
object
Task type-specific configuration
​
retry
object
Retry configuration for failed tasks

​
Event Handlers

​
on_start
object
Handler called when task starts
​
on_success
object
Handler called when task succeeds
​
on_error
object
Handler called when task fails
​
on_complete
object
Handler called after task completes (success or error)

​
Type-specific Event Handlers

​
collection
object
Collection task specific handlers
​
parallel
object
Parallel task specific handlers
​
decision
object
Decision task specific handlers
​
wait
object
Wait task specific handlers
​
map
object
Map task specific handlers
​
composite
object
Composite task specific handlers

​
State Information

​
status
string
Current task status: running, success, or error
​
duration
number
Task execution duration in milliseconds
​
start_time
string
ISO timestamp of when task started
​
end_time
string
ISO timestamp of when task completed
​
retry_count
number
Number of retry attempts made
​
error
object
Error information if task failed
​
output
any
Task output data

​
Expression Context

​
id
string
Current task ID
​
type
string
Task type
​
status
string
Task status
​
input
any
Task input data
​
output
any
Task output data
​
error
any
Error information
​
tasks
object
Access to other task data
​
now()
function
Returns current timestamp
​
env
object
Environment variables

​
Type-specific Context

​
item
any
Current item in collection task
​
index
number
Current index in collection task
​
batch_index
number
Current batch index in collection task
​
operation_id
string
Current operation ID in parallel task