Cron Expression Parser

Introduction:

A cron schedule is small enough to fit on one line, but it can decide when backups run, when queues are drained, when reports are mailed, and when maintenance scripts compete with production traffic. That compact line is useful because cron checks calendar time regularly and launches matching commands without a person staying logged in. It is also easy to misread because the schedule part is positional. Moving a number by one field can turn weekday polling into every-day polling or a monthly task into a weekly one.

Unix cron syntax normally starts with five time fields: minute, hour, day of month, month, and day of week. The command comes after those fields in a real crontab entry, but the schedule itself is just the five-field pattern. Each field expands to a set of allowed values. An asterisk means the full field range, a comma joins values, a hyphen creates an inclusive range, and a slash applies a step inside that range. Month and weekday names such as JAN and MON are readability shortcuts, not separate calendar systems.

The day fields are the usual source of wrong schedules. When day of month and day of week are both restricted, many Vixie and Cronie style cron implementations run the command when either day field matches, as long as minute, hour, and month also match. The expression 30 4 1,15 * 5 therefore runs at 04:30 on the 1st and 15th of each month and every Friday. It does not mean only Fridays that are also the 1st or 15th.

Macros and dialects add another layer of caution. Shortcuts such as @daily and @monthly can expand to ordinary clock schedules, while @reboot describes daemon startup rather than a future timestamp. Quartz, Jenkins, and newer cron variants define characters such as ?, L, W, #, H, or randomized tilde ranges that are not interchangeable with a standard five-field Unix check.

Timezones are part of the schedule, not just the display. A cron daemon usually evaluates entries in its own local timezone unless an environment setting such as CRON_TZ changes that behavior. Daylight-saving transitions can skip local times that never occur or repeat jobs during a duplicated hour, so a valid expression still needs to be compared with the runtime that will execute it.

How to Use This Tool:

Review the schedule text before adding the command that would follow it in a crontab line. The parser accepts one supported @macro or one Unix five-field expression.

1. Enter the schedule in Cron expression. If the status changes to Needs edit, fix the validation message before using the result tables.
2. Choose Preview basis. Use Browser local for local date parts, or UTC when the schedule is documented and reviewed in UTC.
3. Add a Deployment timezone note such as UTC, Asia/Kuala_Lumpur, or local server time. The note is preserved in review artifacts, but it does not change the preview calculation by itself.
4. Open Advanced when you need a fixed Preview start or a specific Preview runs count. The count is bounded from 3 to 24 rows, and a blank start begins at the next whole minute after the current browser time.
5. Read Field Ledger first. Every field should show Parsed, and the expanded values should match the schedule owner's intent.
6. Compare Next Run Preview with the first real run times you expect on the target system. A weekday, day, hour, or UTC shift usually points to timezone, field order, or day-field semantics.
7. Finish with Schedule Risk Ledger. Resolve high-severity syntax or scan findings and document any remaining day-rule, step-value, daylight-saving, macro, or timezone note before sharing the result.

The Run Cadence Map and JSON output are useful handoff evidence after the field expansion and preview rows make sense. They do not prove that another scheduler dialect accepts the same text.

Interpreting Results:

Valid syntax means the expression fits the supported Unix parser rules. It does not prove that the command exists, that the target daemon has loaded the entry, that the job has the right environment, or that a CI scheduler with its own cron dialect will behave the same way.

• Field Ledger is the best place to catch field-order errors because it expands raw text into allowed values for each cron field.
• Next Run Preview should agree with the first expected target runs. Check the human time and ISO time when UTC evidence matters.
• Schedule Risk Ledger warnings deserve review even when parsing succeeds. Day-field, DST, step-value, and timezone notes can change real run behavior.
• Run Cadence Map shows the gap between previewed runs. It helps spot bursts and long pauses, but it cannot confirm target daemon support.
• @reboot can be valid without a clock preview. Test startup behavior on the target host because no next-run timestamp can be calculated.

Technical Details:

Unix cron matching is a calendar test evaluated at whole-minute granularity. Minute, hour, and month must match their expanded value sets. Day of month and day of week use the cron day rule, so their relationship depends on whether either field is unrestricted.

Field expansion happens before run scanning. Lists are merged, ranges are inclusive, and steps move through the selected field range instead of through elapsed wall-clock time. For example, */23 in the hour field matches hour 0 and hour 23 inside each calendar day; it does not create a stable 23-hour interval across days.

Rule Core:

Field Bounds:

Day-Match Logic:

The matching rule can be expressed as a small decision table. A restricted field is any day field that does not contain *.

Macro and Preview Rules:

Clock-based macros expand to ordinary five-field schedules before preview rows are scanned. @reboot is accepted as an event macro, but it is not a clock schedule.

Interval Formula:

The cadence chart uses the minute gap between each preview row and the previous preview row. For the first row, the selected preview start is used as the previous point.

I is the displayed interval in minutes, and each timestamp is compared in milliseconds. The label is then shortened to minutes, hours, or days depending on the size of the gap.

Preview Scan:

A blank start begins at the next whole minute after the current browser clock. Local preview reads local date parts, while UTC preview reads UTC date parts. The scan stops after the requested number of rows or after a five-year search window.

Impossible calendar combinations can still pass field parsing. A narrow February 31 pattern, for example, may have valid field values but no matching future timestamp inside the preview window.

Accuracy Notes:

Cron parsing is deterministic for the supported Unix field rules, but production behavior can still differ when the target scheduler uses another dialect, another timezone, or command-side logic.

• The parser does not evaluate Quartz, Jenkins, or randomized cron extensions.
• The preview basis is limited to browser local date parts or UTC date parts; the deployment timezone note is documentation, not a timezone engine.
• Parsing, field expansion, next-run preview, charting, and JSON creation run in the browser, so the expression is not sent to a server for parsing.

Worked Examples:

FAQ:

Glossary:

Cron expression

A compact schedule string that describes when a cron job should run.

Five-field syntax

The Unix order of minute, hour, day of month, month, and day of week.

Macro

A shortcut beginning with @, such as @daily or @reboot.

Step value

A slash pattern such as */15 that skips through values inside a field range.

Day of month

The calendar date field, from 1 through 31.

Day of week

The weekday field, where Sunday can be represented as 0 or 7.

Preview basis

The date-part basis used for preview runs, either browser local time or UTC.

CRON_TZ

A cron timezone setting used by some cron daemons to interpret schedule times.

References:

• crontab(5), Linux man-pages.
• crontab(5), Debian Manpages.
• CronTrigger Tutorial, Quartz Scheduler.
• Pipeline Syntax, Jenkins.
• How to create a cron job in Linux, Simplified Guide.
• How to list cron jobs in Linux, Simplified Guide.