Skip to main content

Schema reference

Complete CUE schema reference for workflow definitions.

Table of Contents​

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}
	// Used when calling this workflow from other workflows
	id: string & !=""

	// Display name of the workflow (optional, non-unique)
	// Used for UI display purposes only
	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
}

See also: Workflow Structure

Input​

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

StringInput​

String input parameter.

#StringInput: {
	// Type is fixed as string
	type: "string"

	// Whether this input is required (optional, defaults to false)
	required?: bool

	// Default value if input not provided (optional)
	default?: string

	// Human-readable description of the input (optional)
	description?: string

	// Whether this input contains sensitive data (optional, defaults to false)
	// When true, value is masked in logs and UI
	secret?: bool
}

BoolInput​

Boolean input parameter.

#BoolInput: {
	// Type is fixed as bool
	type: "bool"

	// Whether this input is required (optional, defaults to false)
	required?: bool

	// Default value if input not provided (optional)
	default?: bool

	// Human-readable description of the input (optional)
	description?: string
}

IntInput​

Integer input parameter.

#IntInput: {
	// Type is fixed as int
	type: "int"

	// Whether this input is required (optional, defaults to false)
	required?: bool

	// Default value if input not provided (optional)
	default?: int

	// Human-readable description of the input (optional)
	description?: string
}

Usage: Inputs are defined as a map using any of the above types:

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

  debug_mode:
    type: bool
    default: false

  max_epochs:
    type: int
    default: 100

See also: Workflow 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
}

See also: Trigger Configuration, Reusable Workflows

Schedule​

Scheduled trigger using cron syntax.

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

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

See also: Trigger Configuration

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> }}.

See also: Secrets Management

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
}

See also: Concurrency Control

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.

See also: 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)
	// When defined, creates multiple job instances with different variable combinations
	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
}

See also: Job Structure

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
}

Reference Formats:

  • Short ID: Use just the workflow ID (e.g., "data-processor"). The system expands this to the full resource name within the current workspace.
  • Full Resource Name: Use the complete path (e.g., "/workspaces/abc/workflows/data-processor") for cross-workspace calls or explicit references.

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 - cross-workspace
      inputs:
        version: "v1.2.3"

See also: 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
}

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

See also: Step Structure

UploadH2ODrive​

Upload files/folders to H2O Drive.

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

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

See also: Storage

DownloadH2ODrive​

Download files/folders from H2O Drive.

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

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

See also: Storage

Feedback