Xema Workflow DSL

Complete specification for the Xema Workflow Domain-Specific Language (DSL).

What is the DSL?

The Xema Workflow DSL is a YAML-based declarative language for defining automated software delivery processes. It enables:

• Non-programmers to define complex workflows
• Version control through YAML files
• Type-safe validation at compile time
• Reproducible execution with deterministic hashing

Quick Start

Create a file workflow.yaml:

1apiVersion: xema.dev/workflow/v1alpha1
2kind: Workflow
3metadata:
4  name: my-first-workflow
5  version: 1.0.0
6
7on:
8  workflow_dispatch:
9    inputs:
10      project_name:
11        type: string
12        required: true
13
14jobs:
15  hello:
16    uses: xema/agent
17    with:
18      task: "Say hello to ${{ inputs.project_name }}"

Table of Contents

• Language Reference — Complete syntax guide
• Examples — Common workflow patterns
• Best Practices — Tips and conventions
• Troubleshooting — Debug workflow issues
• Decision Gate — xema/decision-gate reference (humans / agents / endpoints, M-of-N policy)
• Review — xema/review reference (subject + reviewers, optional redraft loop, terminal reviews, approval gates)
• Agent Step — xema/agent reference (model override, sub-agent bindings, workspace manifest, inputs)
• Dispatch Workflow — xema/dispatch-workflow reference (start another run; fire-and-forget vs await-completion modes)
• Back to Workflows — Main workflows documentation

Core Concepts

Structure

Every workflow has this basic structure:

1apiVersion:    Specifies v1alpha1
2kind:          Always "Workflow"
3metadata:      Name, version, description
4on:            Trigger definitions
5concurrency:   Concurrency control
6defaults:      Default settings
7permissions:   Resource access
8vars:          Static variables
9jobs:          Workflow jobs

Triggers

Define when workflows execute:

• workflow_dispatch — Manual trigger with inputs
• schedule — Cron-based scheduling
• webhook — External event (GitHub, Jira, etc.)
• workflow_call — Called by other workflows

Jobs

Jobs are units of work:

• Run in parallel (default) or sequential (with needs)
• Execute actions like agents, reviews, webhooks
• Produce outputs for downstream jobs
• Support conditional execution (if)
• Support parallelization (strategy.matrix)

Data Flow

1Inputs → Variables → Jobs → Outputs → Downstream Jobs
2         ↓
3      Expressions (dynamic values)

Key Features

1. Deterministic Execution

Enables:

• Reproducibility
• Auditability
• Replay ability

2. Type Safety

All inputs, outputs, and parameters are typed:

1inputs:
2  budget:
3    type: number           # Enforced type
4    required: true         # Must be provided
5    defaultValue: 100000   # Fallback

3. Expressions

Dynamic values using template syntax:

1${{ inputs.project_name }}
2${{ vars.organization }}
3${{ needs.previous.outputs.summary }}

4. Matrix Expansion

Run jobs multiple times with different inputs:

1strategy:
2  matrix:
3    version: [20, 21, 22]

5. Conditional Execution

1if: ${{ inputs.deploy == true }}   # runs only when upstream succeeded; use always() / failure() for cleanup

Validation

The DSL is validated at:

1. Parse time — YAML syntax
2. Compile time — Schema validation, action refs, types
3. Runtime — Inputs, permissions, resources

Invalid workflows are rejected with clear errors. No silent failures.

Next Steps

1. Language Reference — Learn complete syntax
2. Examples — See real-world patterns
3. Best Practices — Follow conventions

FAQ

Q: Can I use variables in trigger inputs?
A: No. Trigger inputs must be static. Use workflow variables for dynamic content.

Q: How long can a workflow run?
A: Months or years. The Xema Workflow Runtime supports long-running workflows.

Q: Can I call external APIs?
A: Yes, use xema/http or xema/webhook actions.

Q: How do I handle errors?
A: Use retry policies and conditional execution (if: ${{ failure() }}).

Version: 1.0 — April 2026