Job

Source: packages/spec/src/system/job.zod.ts

TypeScript Usage

import { CronScheduleSchema, IntervalScheduleSchema, JobSchema, JobExecutionSchema, JobExecutionStatus, OnceScheduleSchema, RetryPolicySchema, ScheduleSchema } from '@objectstack/spec/system';
import type { CronSchedule, IntervalSchedule, Job, JobExecution, JobExecutionStatus, OnceSchedule, RetryPolicy, Schedule } from '@objectstack/spec/system';

// Validate data
const result = CronScheduleSchema.parse(data);

CronSchedule

Properties

Property	Type	Required	Description
type	`'cron'`	✅
expression	`string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }`	✅	Cron expression — cron`0 0 * * *` for daily at midnight. Build emits `{dialect:"cron",source}` envelope.
timezone	`string`	optional (default: `"UTC"`)	Timezone for cron execution (e.g., "America/New_York")

IntervalSchedule

Properties

Property	Type	Required	Description
type	`'interval'`	✅
intervalMs	`integer`	✅	Interval in milliseconds

Properties

Property	Type	Required	Description
name	`string`	✅	Job name (snake_case)
label	`string`	optional	Human-readable label
description	`string`	optional	Job description / purpose
schedule	`{ type: 'cron'; expression: string \| object; timezone?: string } \| { type: 'interval'; intervalMs: integer } \| { type: 'once'; at: string }`	✅	Job schedule configuration
handler	`string`	✅	Handler function name (must match a key in `defineStack({ functions })`)
retryPolicy	`{ maxRetries?: integer; backoffMs?: integer; backoffMultiplier?: number; maxRetryDelayMs?: integer; … }`	optional	Retry policy: failed runs (including timeouts) are retried with exponential backoff (delay = min(backoffMs * backoffMultiplier^(retry-1), maxRetryDelayMs), optionally jittered) up to maxRetries retries after the initial attempt. Omit the block for a single attempt; declaring it without `maxRetries` also means no retry since 17.0.0 — state a count to opt in.
timeout	`integer`	optional	Per-attempt time limit in milliseconds; an over-limit run is recorded with execution status "timeout". The in-flight handler is abandoned, not forcibly cancelled. Omit for no time limit.
enabled	`boolean`	optional (default: `true`)	Whether the job is enabled
_lock	`Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>`	optional	Item-level lock — controls overlay & delete (ADR-0010).
_lockReason	`string`	optional	Human-readable reason shown when a write is refused by _lock.
_lockSource	`Enum<'artifact' \| 'package' \| 'env-forced'>`	optional	Layer that set _lock (artifact \| package \| env-forced).
_provenance	`Enum<'package' \| 'org' \| 'env-forced'>`	optional	Origin of the item (package \| org \| env-forced).
_packageId	`string`	optional	Owning package machine id.
_packageVersion	`string`	optional	Owning package version.
_lockDocsUrl	`string`	optional	Optional documentation link surfaced next to _lockReason.

Nested Shape: `Job.schedule[type='cron']`

Property	Type	Required	Description
type	`'cron'`	✅
expression	`string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }`	✅	Cron expression — cron`0 0 * * *` for daily at midnight. Build emits `{dialect:"cron",source}` envelope.
timezone	`string`	optional (default: `"UTC"`)	Timezone for cron execution (e.g., "America/New_York")

Nested Shape: `Job.schedule[type='interval']`

Property	Type	Required	Description
type	`'interval'`	✅
intervalMs	`integer`	✅	Interval in milliseconds

Nested Shape: `Job.schedule[type='once']`

Property	Type	Required	Description
type	`'once'`	✅
at	`string`	✅	ISO 8601 datetime when to execute

Nested Shape: `Job.retryPolicy`

Property	Type	Required	Description
maxRetries	`integer`	optional (default: `0`)	Retry attempts after the initial one. 0 (the default) means no retry — state a count to opt in.
backoffMs	`integer`	optional (default: `1000`)	Base delay before the first retry (ms); subsequent delays multiply by backoffMultiplier
backoffMultiplier	`number`	optional (default: `1`)	Exponential backoff multiplier; 1 (the default) keeps the delay flat
maxRetryDelayMs	`integer`	optional (default: `30000`)	Ceiling for a single backoff delay (ms)
jitter	`boolean`	optional (default: `false`)	Randomize each delay within [50%, 100%] of its computed value — spreads a thundering herd of simultaneous retries
retryDelayMs	`never`	optional	[REMOVED] `retryDelayMs` was removed in @objectstack/spec 17.0.0 — the retry policy now has ONE spelling for its base delay across every surface that carries it: `job.retryPolicy`, a `try_catch` node's `retry` and `flow.errorHandling`. Rename the key to `backoffMs`; the value (milliseconds before the first retry) is unchanged. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.

JobExecution

Properties

Property	Type	Required	Description
jobId	`string`	✅	Job identifier
startedAt	`string`	✅	ISO 8601 datetime when execution started
completedAt	`string`	optional	ISO 8601 datetime when execution completed
status	`Enum<'running' \| 'success' \| 'failed' \| 'timeout' \| 'degraded'>`	✅	Execution status
error	`string`	optional	Error message if failed
durationMs	`integer`	optional	Execution duration in milliseconds

JobExecutionStatus

Allowed Values

running
success
failed
timeout
degraded

OnceSchedule

Properties

Property	Type	Required	Description
type	`'once'`	✅
at	`string`	✅	ISO 8601 datetime when to execute

RetryPolicy

Properties

Property	Type	Required	Description
maxRetries	`integer`	optional (default: `0`)	Retry attempts after the initial one. 0 (the default) means no retry — state a count to opt in.
backoffMs	`integer`	optional (default: `1000`)	Base delay before the first retry (ms); subsequent delays multiply by backoffMultiplier
backoffMultiplier	`number`	optional (default: `1`)	Exponential backoff multiplier; 1 (the default) keeps the delay flat
maxRetryDelayMs	`integer`	optional (default: `30000`)	Ceiling for a single backoff delay (ms)
jitter	`boolean`	optional (default: `false`)	Randomize each delay within [50%, 100%] of its computed value — spreads a thundering herd of simultaneous retries
retryDelayMs	`never`	optional	[REMOVED] `retryDelayMs` was removed in @objectstack/spec 17.0.0 — the retry policy now has ONE spelling for its base delay across every surface that carries it: `job.retryPolicy`, a `try_catch` node's `retry` and `flow.errorHandling`. Rename the key to `backoffMs`; the value (milliseconds before the first retry) is unchanged. Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand.

Schedule

Union Options

This schema accepts one of the following structures:

Option 1

Type: cron

Properties

Property	Type	Required	Description
type	`'cron'`	✅
expression	`string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }`	✅	Cron expression — cron`0 0 * * *` for daily at midnight. Build emits `{dialect:"cron",source}` envelope.
timezone	`string`	optional (default: `"UTC"`)	Timezone for cron execution (e.g., "America/New_York")

Option 2

Type: interval

Properties

Property	Type	Required	Description
type	`'interval'`	✅
intervalMs	`integer`	✅	Interval in milliseconds

Option 3

Type: once

Properties

Property	Type	Required	Description
type	`'once'`	✅
at	`string`	✅	ISO 8601 datetime when to execute

Job

On this page