Skip to main content

Schema reference

This page provides the complete schema reference for workflow definitions.

Workflow​

Top-level workflow definition.

#Workflow: {
    // Unique identifier for this workflow (required, non-empty)
    // Forms part of the resource name: /workspaces/{workspace-id}/workflows/{id}
    id: string & !=""

    // Display name of the workflow (optional, non-unique)
    name?: string

    // Input parameters for the workflow (optional)
    // Referenced in expressions using ${{ .inputs.<name> }}
    inputs?: [string]: #Input

    // Concurrency control for workflow execution (optional)
    concurrency?: #Concurrency

    // Trigger configuration defining when the workflow runs (optional)
    trigger?: #Trigger

    // Environment variables at workflow level (optional)
    env?: [string]: string

    // Secrets from H2O Secure Store (optional)
    // Referenced in expressions using ${{ .secrets.<as> }}
    secrets?: [...#Secret]

    // Cancel all running jobs when any job fails (optional, defaults to true)
    cancel_on_failure?: bool

    // Map of jobs, keyed by job ID
    jobs: [string]: #Job
}

For more details, see Workflow structure.

Input​

Workflow input parameter definitions. There are three types of inputs, each with type-safe defaults.

StringInput​

#StringInput: {
    type: "string"
    required?: bool
    default?: string
    description?: string
    secret?: bool  // When true, value is masked in logs and UI
}

BoolInput​

#BoolInput: {
    type: "bool"
    required?: bool
    default?: bool
    description?: string
}

IntInput​

#IntInput: {
    type: "int"
    required?: bool
    default?: int
    description?: string
}

Usage:

inputs:
  model_name:
    type: string
    default: "xgboost"

  debug_mode:
    type: bool
    default: false

  max_epochs:
    type: int
    default: 100

For more details, see Inputs.

Trigger​

Events that trigger workflow execution.

#Trigger: {
    // List of schedule definitions (optional)
    schedule?: [...#Schedule]

    // Whether this workflow can be called by other workflows (optional, defaults to false)
    callable?: bool
}

For more details, see Triggers and Reusable workflows.

Schedule​

Scheduled trigger using cron syntax.

#Schedule: {
    // Cron expression defining when to run (for example, "0 0 * * *" for daily at midnight UTC)
    cron: string

    // Input values to provide when this schedule triggers (optional)
    inputs?: [string]: string
}

Secret​

Secret from H2O Secure Store.

#Secret: {
    // Resource path of the secret in H2O Secure Store (required, non-empty)
    // Format: workspaces/{workspace-id}/secrets/{secret-id} or
    //         workspaces/{workspace-id}/secrets/{secret-id}/versions/{version-id}
    name: string & !=""

    // Internal reference name for use in expressions (required, non-empty)
    as: string & !=""
}

Secrets are referenced in expressions using ${{ .secrets.<as> }}.

For more details, see Secrets.

Concurrency​

Concurrency control for workflow execution.

#Concurrency: {
    // Concurrency group identifier (required, non-empty)
    // Multiple workflows with same group cannot run concurrently
    group: string & !=""

    // Cancel running workflows when new one queued (optional, defaults to false)
    // true: Cancel in-progress runs and start new one immediately
    // false: Queue new runs, only one running + one pending (newer replaces pending)
    cancel_in_progress?: bool
}

For more details, see Concurrency.

Matrix​

Matrix configuration for job-level parallelization.

#Matrix: {
    // Matrix variables defining dimension values
    // Each variable must have at least one non-empty string value
    // Creates cartesian product of all variable combinations
    [string]: [...string] & [...string & !=""] & [_, ...]
}

Example:

matrix:
  os: [ubuntu, macos, windows]
  python: ["3.9", "3.10", "3.11"]
  # Creates 9 job instances (3 × 3)

Matrix variables are accessed using ${{ .matrix.variable }} expressions within the job.

For more details, see Matrix jobs.

Job​

Job containing multiple steps or a workflow reference.

#Job: {
    // Name of the job (optional)
    name?: string

    // Runner to run the job on (optional)
    runner?: string

    // List of job IDs that must complete before this job runs (optional)
    depends_on?: [...string]

    // Matrix configuration for parallel job execution (optional)
    matrix?: #Matrix

    // Working directory for all steps in this job (optional)
    working_dir?: string

    // Maximum execution time (optional, uses system default if not specified)
    timeout?: time.Duration

    // Environment variables (optional)
    env?: [string]: string

    // List of steps to execute in order (optional, mutually exclusive with workflow)
    steps?: [...#Step]

    // Call another workflow (optional, mutually exclusive with steps)
    workflow?: #WorkflowCall
}

For more details, see Jobs.

WorkflowCall​

Call to another workflow.

#WorkflowCall: {
    // Workflow reference (required, non-empty)
    // Can be either:
    // - Short ID: "workflow-id" (expands to /workspaces/{current-workspace}/workflows/workflow-id)
    // - Full resource name: "/workspaces/abc/workflows/workflow-id" (for cross-workspace calls)
    name: string & !=""

    // Input values for the called workflow (optional)
    inputs?: [string]: string
}

Example:

jobs:
  process:
    workflow:
      name: data-processor  # Short ID - same workspace
      inputs:
        dataset: "users"

  deploy:
    workflow:
      name: /workspaces/other-workspace-id/workflows/deploy-service  # Full resource name
      inputs:
        version: "v1.2.3"

For more details, see Reusable workflows.

Step​

Single step within a job.

#Step: {
    // Name of the step (optional)
    name?: string

    // Working directory for this step (optional, overrides job working_dir)
    working_dir?: string

    // Shell command(s) to execute (optional)
    run?: string

    // Upload files/folders to H2O Drive (optional)
    upload?: #Upload

    // Download files/folders from H2O Drive (optional)
    download?: #Download

    // Maximum execution time (optional, uses system default if not specified)
    timeout?: time.Duration

    // Continue job execution even if this step fails (optional, defaults to false)
    continue_on_error?: bool

    // Environment variables (optional)
    env?: [string]: string
}
Note

Steps must have exactly one of: run, upload, or download.

For more details, see Steps.

Upload​

Upload files and folders to H2O Drive.

#Upload: {
    // Local path or glob pattern to upload (required, non-empty)
    path: string & !=""

    // H2O Drive destination URL (required, non-empty)
    destination: string & !=""
}

Download​

Download files and folders from H2O Drive.

#Download: {
    // H2O Drive source URL (required, non-empty)
    source: string & !=""

    // Local destination path (required, non-empty)
    path: string & !=""
}

For more details, see Storage.

Feedback