The cron expression

An expression has five fields, in this order.

A field takes one of five forms.

• * — any value.
• a single value, such as 6.
• a range, such as 1-5.
• a list, such as 1,15.
• a step over a range, such as */15.

The forms compose within a field, so one expression can select the first minute of the first working day of a month.

There is no seconds field: an expression resolves to whole minutes, so the shortest interval between two firings is one minute and a firing is never due at a stated second. A recurrence more frequent than once a minute cannot be expressed.

The boundary that accepts a job validates its expression, and a malformed expression is rejected there, before it reaches a row. Validation happens once, on the way in: the scheduler stores only expressions it can evaluate, and the stored text is the text that passed validation. A rejected expression is returned to the caller as an error, because the caller asked for a schedule and got none.

The scheduler never parses an expression into fields of its own. It asks the expression for the next occurrence after a given instant. Adding a value form to the notation therefore adds it to every stored expression.

A job is due when both of these hold.

1. The job's active flag is true.
2. The next occurrence after the job's last recorded firing has already passed.

Condition two fixes the last firing as the reference point, and three properties follow from it.

• A new job runs at its next occurrence. A job with no recorded firing is evaluated from the current minute, so its first execution is the next occurrence its expression defines, not the moment of registration.
• Missed occurrences are not replayed. A job whose occurrence passed while the scheduler was down runs once when the scheduler restarts. The reference is the last recorded firing, so the scheduler builds no backlog and performs no work for the occurrences it missed.
• An inactive job is never due. The active flag is condition one, so an inactive job does not fire. It keeps its row and its execution history, and activating it applies the same rule as before.

The loop evaluates this condition for every job it holds at each minute. The scheduler loop describes the evaluation and what follows from it.

An expression defines no property of the action: not the action type, not the payload, not the tenant or party the job runs for. Those are separate fields of the job definition, read at the firing. The separation is why an expression can be changed without changing what a job does, and why the action can be replaced without moving the schedule.