Language Reference

1apiVersion: xema.dev/workflow/v1alpha1

1kind: Workflow

1metadata:
2  name: my-workflow              # Unique name
3  version: 1.0.0                 # Semantic versioning
4  description: Optional description

1metadata:
2  name: workflow-name                    # Required: unique identifier
3  version: 1.0.0                         # Required: semantic version
4  description: Human-readable description # Optional

1on:
2  workflow_dispatch:
3    inputs:
4      project_name:
5        type: string
6        required: true
7        description: Project name
8      budget:
9        type: number
10        required: false
11        defaultValue: 100000
12      include_testing:
13        type: boolean
14        required: false
15        defaultValue: true

1interface InputDescriptor {
2  type: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array'
3  required: boolean
4  description?: string
5  defaultValue?: unknown
6  enum?: string[]                    // For closed sets
7  format?: 'multiline'               // For string type
8  itemType?: string                  // For array type
9}

1on:
2  schedule:
3    - cron: "0 9 * * MON"           # Monday 9 AM
4      inputs:
5        report_type: weekly
6    - cron: "0 0 1 * *"             # 1st of month
7      inputs:
8        report_type: monthly

1on:
2  webhook:
3    - event: scm.push
4      filters:
5        projectId: proj_123
6        branch: main
7    - event: tracker.issue
8      filters:
9        type: feature
10        priority: high

1on:
2  workflow_call:
3    inputs:
4      scope:
5        type: string
6        required: true
7    outputs:
8      summary:
9        value: ${{ needs.final.outputs.summary }}

1concurrency:
2  group: requirements-${{ inputs.project_id }}
3  mode: queue

1defaults:
2  retry:
3    maxAttempts: 3
4    backoffCoefficient: 2.0
5    initialInterval: 1s
6    maxInterval: 60s
7  timeout: "2h"

1interface RetryPolicy {
2  maxAttempts: number              // Max attempts (1-10)
3  backoffCoefficient: number       // Multiplier per retry (1.0-10.0)
4  initialInterval: string          // Starting wait (e.g., "1s")
5  maxInterval: string              // Max wait (e.g., "60s")
6}

1permissions:
2  repos: read                      # SCM access
3  kb: limited                      # Knowledge base
4  backlog: write                   # Issue tracking
5  artifacts: read                  # Artifact store
6  integrations: read               # Integrations

1vars:
2  organization: "Acme Corp"
3  max_retries: 3
4  review_template: "enterprise"

1jobs:
2  job-key:
3    title: Optional title
4    needs: [job1, job2]              # Dependencies
5    if: ${{ condition }}             # Conditional
6    strategy:                        # Matrix/dynamic
7      matrix:
8        os: [ubuntu, windows]
9    uses: namespace/action@version   # Action ref
10    with:                            # Inputs
11      param: value
12    outputs:                         # Extract outputs
13      key: ${{ result.field }}
14    timeout: "1h"                    # Job timeout
15    retry:                           # Job retry policy
16      maxAttempts: 5

1needs: [job1, job2]   # canonical array form
2needs: job1           # shorthand — exactly equivalent to needs: [job1]

1if: ${{ inputs.deploy == true }}
2if: ${{ contains(needs.previous.outputs.errors, 'critical') }}
3if: ${{ always() }}

1cleanup:
2  needs: [build, test]
3  if: ${{ always() }}                    # runs after success, failure, skip or cancel
4notify:
5  needs: [build]
6  if: ${{ failure() }}                   # runs only when something upstream failed
7join:
8  needs: [fast-path, slow-path]          # one of them is skipped by its own `if:`
9  if: ${{ !failure() && !cancelled() }}  # run unless something failed or the run was cancelled

1if: ${{ needs.build.outcome == 'failed' }}

1strategy:
2  matrix:
3    os: [ubuntu, windows, macos]
4    version: [20, 21, 22]
5    architecture: [x86_64, arm64]
6  maxParallel: 6                     # Optional: limit concurrency
7  include:                           # Optional: add extra combinations
8    - os: ubuntu
9      version: 23

1strategy:
2  dynamic:
3    from: ${{ needs.previous.outputs.items }}
4    as: item
5    maxEntries: 100                  # Prevent runaway expansion

1with:
2  task: "Analyze requirements"
3  org: ${{ vars.organization }}
4  scope: ${{ inputs.project_scope }}
5  previous_result: ${{ needs.analyze.outputs.summary }}

1outputs:
2  summary: ${{ result.summary }}
3  risks: ${{ result.risks }}
4  artifact_id: ${{ result.artifact_id }}

1timeout: "30m"

1retry:
2  maxAttempts: 5
3  backoffCoefficient: 1.5

1${{ 'string' }}
2${{ 42 }}
3${{ 3.14 }}
4${{ true }}
5${{ false }}
6${{ null }}

1${{ inputs.project_name }}
2${{ vars.organization }}
3${{ needs.job1.outputs.summary }}
4${{ matrix.os }}
5${{ dynamic.service }}
6${{ trigger.provider }}

1==, !=, <, >, <=, >=

1&&, ||, !

1+              # Concatenation

1success()      # Run not cancelled and every upstream job succeeded
2failure()      # Some upstream job failed
3cancelled()    # The run was cancelled
4always()       # Always true

1contains(str, substr)      # Check substring
2startsWith(str, prefix)    # Check prefix
3endsWith(str, suffix)      # Check suffix

1length(arr)    # Array length
2first(arr)     # First element
3last(arr)      # Last element

1toNumber(str)  # Convert to number
2toString(val)  # Convert to string
3toJSON(val)    # Convert to JSON

1${{ obj.property }}
2${{ obj['property-with-hyphen'] }}

1${{ arr[0] }}           # First element
2${{ arr[-1] }}          # Last element
3${{ arr[*] }}           # All elements (for matrix)

1mounts:
2  - path: /artifacts
3    source:
4      kind: artifact-store-collection
5      collectionId: coll_123
6  - path: /code
7    source:
8      kind: scm-repo
9      repoRef: github.com/acme/myrepo
10      ref: main
11  - path: /specs
12    source:
13      kind: deliverable-specs
14      contractKey: enterprise-saas