CronWorkflow Schema Reference — aether/v1

The CronWorkflow resource wraps a standard WorkflowSpec with a cron schedule, giving you periodic, time-driven workflow execution without any external job scheduler. The engine stores an immutable snapshot of the definition at submit time and re-submits a fresh WorkflowRun on each schedule tick. CronWorkflow operations require a cron.Scheduler to be injected via WithCronScheduler; calling them without one returns ErrNotSupported.

Top-level fields

string

required

Protocol version. Must be "aether/v1".

string

required

Resource discriminator. Must be "CronWorkflow".

object

required

Standard resource metadata identical to the Workflow resource.

Show metadata fields

string

required

Unique name for this cron workflow definition. Must follow DNS-1123 label rules: lowercase alphanumeric characters or hyphens, must start and end with an alphanumeric character, maximum 63 characters.

string

Optional logical namespace for multi-tenant isolation.

string

Optional user-defined version string. Not interpreted by the engine.

map[string]string

Arbitrary key/value labels for querying and grouping.

map[string]string

Arbitrary key/value annotations. Not interpreted by the engine.

object

required

The cron workflow specification.

Show spec fields

string

required

Standard 5-field cron expression or a predefined macro. The engine validates that the expression has exactly five whitespace-separated fields.

┌─── minute        (0–59)
│ ┌─── hour         (0–23)
│ │ ┌─── day-of-month (1–31)
│ │ │ ┌─── month       (1–12 or JAN–DEC)
│ │ │ │ ┌─── day-of-week  (0–6 or SUN–SAT)
│ │ │ │ │
* * * * *

Supported macros: @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly.Examples: "0 * * * *" (every hour), "30 6 * * 1" (every Monday at 06:30), "@daily".

string

IANA timezone string used to interpret the cron schedule (e.g. "America/New_York", "Europe/Berlin", "UTC"). When omitted the scheduler uses UTC. Invalid timezone strings fail validation.

string

RFC3339 datetime string. Triggers are suppressed before this time. When omitted the schedule is active immediately on submit.Example: "2026-01-01T00:00:00Z"

string

RFC3339 datetime string. Triggers are suppressed after this time. Must be strictly after startAt when both are set. When omitted the schedule runs indefinitely.Example: "2026-12-31T23:59:59Z"

string

default:"Allow"

How the engine handles a new trigger when a previous run is still active.

Value	Behavior
`"Allow"`	Start a new run regardless of active runs. Multiple runs may overlap.
`"Forbid"`	Skip the new trigger if any run from this CronWorkflow is still active.
`"Replace"`	Cancel the oldest active run, then start the new one.

integer

Maximum number of seconds past the scheduled time within which a missed trigger is still eligible to fire. A trigger is considered missed when the engine was down or suspended during the scheduled tick.Must be greater than 0 when set. null (or omitted) means no deadline — missed triggers are always back-filled.

integer

default:"0"

Maximum number of successful WorkflowRun records to retain. Once the limit is reached the oldest successful runs are garbage-collected. 0 means retain all successful runs.

integer

default:"0"

Maximum number of failed WorkflowRun records to retain. Once the limit is reached the oldest failed runs are garbage-collected. 0 means retain all failed runs.

boolean

default:"false"

When true, no new triggers are fired. Existing active runs continue to completion. Use UpdateCronWorkflow to toggle this field without deleting and re-submitting the definition. This is the recommended mechanism for pausing a scheduled workflow.

object

required

The embedded WorkflowSpec that describes what runs on each trigger. This field is validated exactly as if it were spec on a standalone Workflow resource. All template types, arguments, hooks, and timeout fields are supported.

workflowSpec is immutable after submit. Attempting to change it via UpdateCronWorkflow returns ErrValidation. To change the workflow logic, delete the existing CronWorkflow and submit a new one.

See the Workflow Schema reference for the complete WorkflowSpec field documentation. The mutable scheduling fields (schedule, timezone, concurrencyPolicy, suspend, etc.) can be updated freely via UpdateCronWorkflow.

Example

The following example is taken directly from the engine’s integration test suite (28-cron-basic.json). It fires every hour on the hour and runs a single echo task.

{
  "apiVersion": "aether/v1",
  "kind": "CronWorkflow",
  "metadata": {
    "name": "cron-basic",
    "annotations": {
      "description": "Basic CronWorkflow: fires once, inner workflow completes successfully"
    }
  },
  "spec": {
    "schedule": "0 * * * *",
    "workflowSpec": {
      "entrypoint": "main",
      "templates": [
        {
          "task": {
            "name": "main",
            "inputs": {
              "parameters": [
                {
                  "name": "outputs",
                  "value": [
                    { "name": "result", "type": "string", "value": "cron-ok" }
                  ]
                }
              ]
            },
            "executor": { "type": "echo" },
            "outputs": {
              "parameters": [{ "name": "result", "type": "string" }]
            }
          }
        }
      ]
    }
  }
}

Full-featured example

{
  "apiVersion": "aether/v1",
  "kind": "CronWorkflow",
  "metadata": {
    "name": "nightly-report",
    "namespace": "analytics",
    "labels": { "team": "data-eng" }
  },
  "spec": {
    "schedule": "0 2 * * *",
    "timezone": "America/New_York",
    "startAt": "2026-01-01T00:00:00Z",
    "endAt":   "2027-01-01T00:00:00Z",
    "concurrencyPolicy": "Forbid",
    "startingDeadlineSeconds": 300,
    "successfulJobsHistoryLimit": 7,
    "failedJobsHistoryLimit": 3,
    "suspend": false,
    "workflowSpec": {
      "entrypoint": "generate-report",
      "timeout": "45m",
      "templates": [
        {
          "task": {
            "name": "generate-report",
            "executor": { "type": "shell" },
            "outputs": {
              "parameters": [{ "name": "report-url", "type": "string" }]
            }
          }
        }
      ]
    }
  }
}

Immutability and updates

Use Engine.UpdateCronWorkflow to change scheduling parameters (schedule, timezone, concurrencyPolicy, startAt, endAt, suspend, startingDeadlineSeconds, history limits) without re-submitting. The engine re-registers the schedule with the cron backend automatically.

WorkflowRun records created by a CronWorkflow are not cascade-deleted when the CronWorkflow is deleted via DeleteCronWorkflow. Existing run history is preserved. Only future triggers are stopped.

​Top-level fields

​Example

​Full-featured example

​Immutability and updates

Top-level fields

Example

Full-featured example

Immutability and updates