SYNTAX.md

Scope

This document defines the user-facing schedule syntax accepted by Kron. The same syntax is used by:

  • Kubernetes CRDs (KronJob.spec.schedule, KronJob.spec.window, KronJob.spec.distribution, KronJob.spec.constraints)

  • krontab entries for krond

The syntax is designed to be:

  • Cron-compatible for the baseline schedule

  • Explicit for probabilistic extensions

  • Deterministic and fully parseable

Grammar overview

A Kron schedule is composed of:

  1. A baseline cron expression

  2. Optional modifiers

Canonical form:

<cron> [@tz(<tz>)] [@win(<mode>,<duration>)] [@dist(<name>[,<k=v>...])] [@seed(<strategy>[,<k=v>...])] [@policy(<k=v>...)] [@avoid(<spec>)] [@only(<spec>)]

Order of modifiers is not significant.

Whitespace separates tokens. Parentheses do not contain unescaped whitespace.

Cron expression

Kron accepts standard 5-field cron:

<minute> <hour> <day-of-month> <month> <day-of-week>

Ranges, lists, and steps are supported:

  • *

  • n

  • n-m

  • n,m,k

  • */s

  • n-m/s

Aliases are supported where common:

  • months: JAN..DEC

  • weekdays: SUN..SAT

Day-of-week values:

  • 0-6 with 0=SUN

  • SUN..SAT

Examples:

0 0 * * *           # daily at midnight
15 9 * * MON-FRI    # weekdays at 09:15
*/5 * * * *         # every 5 minutes
0 3 1 * *           # monthly on the 1st at 03:00

Timezone modifier

@tz(<tz>)

<tz> is an IANA timezone name.

Examples:

0 10 * * * @tz(Europe/Paris)
0 18 * * * @tz(America/Los_Angeles)

If omitted, timezone is UTC.

Window modifier

@win(<mode>,<duration>)

<mode>:

  • after

  • around

<duration> is a Go-style duration:

  • ns, us, ms, s, m, h

  • composite forms are allowed: 1h30m

Semantics:

  • after: window is [nominal, nominal + duration]

  • around: window is [nominal - duration/2, nominal + duration/2]

Examples:

0 0 * * * @win(after,2h)
0 10 * * * @win(around,45m)

If omitted, window is after,0s.

Distribution modifier

@dist(<name>[,<k=v>...])

<name>:

  • uniform

  • normal

  • skewEarly

  • skewLate

  • exponential

Parameters are k=v pairs. Unknown keys are invalid.

MVP runtime status:

  • krontab explain and krontab next execute: uniform, skewEarly, skewLate

  • normal and exponential are syntax-valid and lint-validated, but runtime execution is not part of current MVP

uniform

@dist(uniform)

No parameters.

normal

@dist(normal[,mu=<anchor>][,sigma=<duration>])

MVP runtime note: syntax-valid and lint-validated, but not executed by krontab explain/krontab next.

  • mu sets the mean anchor point.

  • sigma sets standard deviation.

mu anchors:

  • nominal

  • start

  • mid

  • end

Defaults:

  • mu=nominal for around

  • mu=mid for after

  • sigma=window/6

Examples:

0 10 * * * @win(around,2h) @dist(normal,sigma=20m)
0 10 * * * @win(after,2h)  @dist(normal,mu=start,sigma=15m)

skewEarly / skewLate

@dist(skewEarly[,shape=<float>])
@dist(skewLate[,shape=<float>])

  • shape controls skew intensity.

  • shape is a positive float.

  • default shape=2.0

Examples:

0 10 * * * @win(after,2h) @dist(skewEarly,shape=3)
0 10 * * * @win(after,2h) @dist(skewLate,shape=1.5)

exponential

@dist(exponential[,lambda=<float>][,dir=<dir>])

MVP runtime note: syntax-valid and lint-validated, but not executed by krontab explain/krontab next.

  • lambda is a positive float controlling decay rate.

  • dir:

    • early biases toward window start

    • late biases toward window end

  • defaults: lambda=1.0, dir=early

Examples:

0 10 * * * @win(after,2h) @dist(exponential,dir=early,lambda=1.2)
0 10 * * * @win(after,2h) @dist(exponential,dir=late,lambda=0.8)

If omitted, distribution is uniform.

Seed modifier

@seed(<strategy>[,<k=v>...])

<strategy>:

  • stable

  • daily

  • weekly

Parameters:

  • salt=<string>

<string> is a UTF-8 string without unescaped whitespace. Quoted strings are supported:

  • "..." with \" escapes

Examples:

0 0 * * * @seed(stable,salt="team-a")
0 10 * * * @seed(daily)
0 10 * * MON @seed(weekly,salt=prod)

If omitted, seed strategy is stable with empty salt.

Policy modifier

@policy(<k=v>[,<k=v>...])

Keys:

  • concurrency=allow|forbid|replace

  • deadline=<duration>

  • suspend=true|false

Defaults:

  • concurrency=forbid

  • deadline=0s (skip missed periods)

  • suspend=false

Examples:

0 0 * * * @policy(concurrency=forbid,deadline=10m)
0 10 * * * @policy(concurrency=replace)

Constraints modifiers

Constraints restrict when a chosen time may be selected. Constraints apply after the window is computed and before a final time is accepted. If a candidate time violates constraints, a new candidate is drawn. If no valid time can be found, the period is unschedulable.

Avoid modifier

@avoid(<spec>)

Only modifier

@only(<spec>)

A constraint spec is a semicolon-separated list of clauses:

<clause> ; <clause> ; ...

Clause forms:

  • hours=<range>

  • dow=<range>

  • dom=<range>

  • months=<range>

  • between=<hh:mm>-<hh:mm>

  • date=<yyyy-mm-dd>

  • dates=<yyyy-mm-dd>..<yyyy-mm-dd>

Ranges:

  • numeric ranges with lists and hyphens, e.g. 1-5,7,9-12

  • weekdays: SUN..SAT

  • months: JAN..DEC

Time values are interpreted in the schedule timezone.

Examples:

0 10 * * * @win(after,2h) @avoid(hours=0-6)
0 18 * * * @win(around,1h) @only(dow=MON-FRI;between=08:00-20:00)
0 19 * * * @avoid(date=2026-12-25)
0 19 * * * @avoid(dates=2026-12-24..2026-12-31)

Validation rules

  • Cron expression must be valid and resolvable.

  • Timezone must be a valid IANA name.

  • Window duration must be non-negative.

  • For around mode, duration/2 is computed with nanosecond precision.

  • Distributions must be recognized; parameters must be valid and within allowed ranges.

  • In current MVP runtime, only uniform, skewEarly, and skewLate are executable in explain/next.

  • Seed strategy must be recognized.

  • Policy keys must be recognized; values must be valid.

  • Constraint specs must be parseable; unknown clause keys are invalid.

  • @only(...) and @avoid(...) may both be present.

  • If constraints eliminate the entire window, the period is unschedulable.

Examples (MVP executable with explain/next)

Load smoothing (spread backups)

0 0 * * * @tz(UTC) @win(after,3h) @dist(uniform) @seed(stable,salt=backup) @policy(concurrency=forbid,deadline=30m)

Human-like messaging (late-biased)

0 10 * * * @tz(Europe/Paris) @win(around,90m) @dist(skewLate,shape=2.5) @seed(daily,salt=msgs) @only(dow=MON-FRI;between=08:00-20:00)

Home automation (gentle unpredictability)

0 18 * * * @tz(America/Los_Angeles) @win(around,20m) @dist(skewLate,shape=1.4) @seed(daily,salt=lights)

Avoid nights and weekends

0 * * * * @tz(UTC) @win(after,30m) @dist(skewEarly) @only(dow=MON-FRI;hours=8-18)

Monthly with wide window, strict deadline

0 2 1 * * @tz(UTC) @win(after,8h) @dist(uniform) @policy(concurrency=forbid,deadline=15m)

Lint-only Examples (planned runtime distributions)

These pass krontab lint but are not executable by MVP krontab explain/krontab next.

0 10 * * * @win(around,2h) @dist(normal,sigma=20m)
0 10 * * * @win(after,2h)  @dist(exponential,dir=early,lambda=1.2)