​
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