Documentation

Why Declarative YAML?

BotMatrix treats pipelines as versioned code artifacts, not ephemeral UI states. By defining your bot logic in YAML, you gain reproducibility, auditability, and the ability to version control your automation just like your application code.

The schema is strict and typed. Every field serves a purpose, and the platform enforces constraints at parse time. This ensures that what you deploy in staging is exactly what runs in production, eliminating the "it works on my machine" class of bugs.

The schema is split into three logical layers: Configuration (metadata, env, secrets), Triggers (how the pipeline starts), and Steps (the execution graph).

Architecture

Schema Overview

The root object defines the pipeline's identity and execution context. It branches into triggers and a linear sequence of steps.

Below is the structural hierarchy of the BotMatrix YAML schema.

BotMatrix YAML Schema Hierarchy Diagram showing Root -> Version, Triggers, Steps, Env, Secrets

Figure 1: The hierarchical structure of a valid BotMatrix pipeline definition.

Reference

Field-by-Field Reference

Root Properties

name
A unique identifier for the pipeline. Must be lowercase alphanumeric with hyphens. Used in CLI commands and logging.
version
Semantic versioning string (e.g., 1.0.0). Pipelines are immutable once deployed; changing this creates a new revision.
description
Optional human-readable summary of the pipeline's purpose.

Execution Context

env
A map of environment variables available to all steps. Values are resolved at runtime from the deployment context.
secrets
A list of secret references (e.g., aws_access_key). These are injected into the execution environment securely.
timeout
Maximum execution duration in seconds. Defaults to 300s. If exceeded, the pipeline is terminated.

Orchestration

retries
Number of automatic retries for failed steps. Defaults to 0. Exponential backoff is applied.
concurrency
Maximum concurrent executions of this pipeline. Useful for rate limiting or resource management.
Examples

Annotated Example: Conditional Onboarding

This pipeline handles a new user signup. It validates the email, checks creditworthiness in parallel, and sends a welcome email only if credit is approved. 

name: user-onboarding
version: 1.2.0
description: Onboard new users with credit check

triggers:
  webhook:
    path: /signup
    method: POST

steps:
  validate-email:
    type: http
    url: https://api.bm.internal/validate
    method: GET
    output: email_valid

  check-credit:
    type: parallel
    steps:
      check-score:
        type: http
        url: https://api.bm.internal/credit-score
        output: score
      check-limit:
        type: http
        url: https://api.bm.internal/limit
        output: limit

  send-welcome:
    type: http
    url: https://api.bm.internal/welcome
    condition: check-credit.check-score.score > 700
    input:
      email: {{ trigger.body.email }}
      plan: premium

  send-fallback:
    type: http
    url: https://api.bm.internal/manual-review
    condition: check-credit.check-score.score <= 700
    input:
      email: {{ trigger.body.email }}
Patterns

Advanced Patterns

Fan-Out & Fan-In

Use the parallel step type to fan out tasks. Use the join step type to aggregate results from multiple parallel branches. 

steps:
  fan-out:
    type: parallel
    steps:
      - task-a: ...
      - task-b: ...
      - task-c: ...

  fan-in:
    type: join
    inputs: fan-out
    output: aggregated_results

Error Handling Hooks

Define on_error steps to handle failures gracefully. These steps run if a previous step fails or times out. 

steps:
  process-data:
    type: http
    url: https://api.bm.internal/process
    on_error:
      type: http
      url: https://api.bm.internal/alert
      input:
        error: {{ error.message }}
Validation

Validate Before Deploy

Always run botmatrix validate locally before committing. This checks syntax, resolves dependencies, and ensures your secrets are referenced correctly. 

$ botmatrix validate pipelines/onboarding.yaml
# Validating pipeline 'user-onboarding' (v1.2.0)...
# Checking triggers...
  ✓ Webhook trigger found at /signup
# Checking steps...
  ✓ Step 'validate-email' is valid
  ✓ Step 'check-credit' is valid
  ✓ Step 'send-welcome' is valid
  ✓ Step 'send-fallback' is valid
# Checking secrets...
  ✓ All secrets resolved
Pipeline is valid and ready to deploy.
Developer Tools

For full IDE autocompletion and real-time linting, download the official JSON Schema definition. It is compatible with VS Code, JetBrains IDEs, and most YAML editors.

Download botmatrix-schema.json