Cron Expression Parser

Introduction:

A Unix cron expression is a compact schedule written as five time fields: minute, hour, day of month, month, and day of week. It is common in Linux and Unix job scheduling because a short string can describe anything from every minute to one weekday maintenance run each month. The compactness is useful, but it also makes mistakes easy to miss before a job reaches production.

The practical risk is not only invalid syntax. A schedule such as */15 9-17 * * MON-FRI is readable once you know the field order, but a misplaced value can move a job from business hours to midnight, or from weekdays to every day. Day-of-month and day-of-week rules need extra care because many Vixie/Cronie-style cron daemons treat both restricted day fields as an OR match rather than an intersection.

Previewing cron is different from proving the target daemon will run exactly the same way. System cron, application schedulers, CI schedulers, and Quartz-style triggers can use different field counts, special characters, hashing, or timezone rules. A readable expression should still be checked against the runtime that will execute it.

A parser is most useful before a schedule is installed, during incident review, or when a team is moving a job between hosts. It turns a terse string into field values, expected run times, and warnings that make a risky schedule easier to spot.

Technical Details:

Unix cron matching starts by expanding each field into allowed values. Asterisks mean the full range for that field, ranges are inclusive, comma lists combine values, and step values skip through a field range. Month and weekday names use three-letter English abbreviations, and weekday Sunday can be written as either 0 or 7 in many cron implementations.

The five-field form omits the command column and any seconds or year fields. That distinction matters because Quartz expressions often have six or seven fields, while Jenkins adds hash-based H syntax. A Unix parser can reject those dialect markers even when they are valid in a different scheduler.

Rule Core:

The schedule match is an ordered test against the current minute. Minute, hour, and month must match. The two day fields then apply the cron day rule, which changes when both fields are restricted.

Dialect and Validation Rules:

The parser treats a valid time-based expression as either one supported macro or exactly five whitespace-separated fields. It does not evaluate a shell command column, seconds field, optional year field, randomized tilde selection, Quartz day modifiers, or Jenkins hash syntax.

Preview Mechanics:

Run previews are found by scanning whole-minute timestamps from the chosen start point. Blank start time begins at the next whole minute after the browser clock. Browser local time reads local date parts, while UTC reads UTC date parts. The deployment timezone note is recorded for review and exports, but it does not change the preview unless the matching preview basis is selected.

Everyday Use & Decision Guide:

Start with the exact string you plan to install, without the command after it. Paste it into Cron expression, then read the summary before opening the detailed tabs. If the badge says Needs edit, fix the syntax first; the later tables are review aids, not a way around an invalid schedule.

Use the Preview basis that matches how you want to check the dates. Browser local time is useful when you are reviewing a host that runs in your local timezone. UTC is better for infrastructure schedules that are documented in UTC. Put the intended server timezone or CRON_TZ value in Deployment timezone note so the preview and target runtime do not get mixed up in the handoff.

• Use Sample when you need a known-good expression to compare against the field order.
• Open Advanced when you want a repeatable Preview start or more than the default number of Preview runs.
• Read Field Ledger when the expression is unfamiliar. It expands values such as MON-FRI and */15.
• Read Next Run Preview before installing a job. The first run often reveals a timezone or field-order mistake faster than prose.
• Use Schedule Risk Ledger for warnings about day-field semantics, step values, local daylight-saving behavior, and missing timezone notes.
• Use Run Cadence Map when interval gaps matter, such as maintenance jobs that should not bunch up after month boundaries.

A useful result does not prove the target scheduler supports the same dialect. If a production scheduler accepts Quartz, Jenkins, Kubernetes, or application-specific cron forms, confirm the expression there too. The parser is intentionally strict about Unix five-field input so unsupported characters fail early instead of looking meaningful.

Before sharing the output, compare the first few rows in Next Run Preview with the target server's timezone and the schedule owner's intent. If Schedule Risk Ledger has any non-OK severity, clear the issue or record why it is acceptable for that job.

Step-by-Step Guide:

Parse the expression, confirm each field, then compare the previewed runs with the scheduler that will execute the job.

1. Paste the schedule into Cron expression. Enter only one supported macro or one five-field expression; if a command column or extra seconds field is present, the validation message reports the field-count problem.
2. Set Preview basis to Browser local time or UTC. The summary badge then reports Unix 5-field or Cron macro and shows whether preview runs are available.
3. Enter a Deployment timezone note such as UTC, Asia/Kuala_Lumpur, or local server time. The risk ledger marks this as recorded when the note is present.
4. Open Advanced if the review needs a fixed Preview start or a larger Preview runs count. The count accepts 3 to 24 rows.
5. Check Field Ledger. Each row should show Parsed and an expanded value list or a clear macro description.
6. Check Next Run Preview. If no rows appear for a valid time-based expression, review impossible calendar combinations such as February 31 or very narrow month and day filters.
7. Check Schedule Risk Ledger. Fix syntax errors, unsupported macros, missing timezone notes, or day-field warnings before treating the expression as ready.
8. Use JSON, table exports, or chart exports only after Field Ledger, Next Run Preview, and Schedule Risk Ledger match the schedule you intend to keep.

Interpreting Results:

Valid syntax means the expression fits the supported Unix parser rules. It does not mean the job command exists, the target daemon has loaded it, the scheduler uses the same dialect, or the timezone is correct. Treat the parse as schedule evidence, then verify runtime behavior on the target host or scheduler.

• Field Ledger is the best place to catch field-order mistakes. A value that looks right in the raw string can still expand into the wrong field.
• Next Run Preview should be checked against the first real expected run. A one-hour or one-day shift usually points to timezone basis, UTC documentation, or a day-field misunderstanding.
• Schedule Risk Ledger warnings deserve review even when syntax is valid. Day field semantics, Step value boundary, and DST and local time can all change how a schedule behaves in practice.
• Run Cadence Map is useful for gaps, not for approval. A smooth-looking chart still needs timezone and dialect checks.
• JSON is a handoff artifact. Use it after the visible results are correct, not as a substitute for reading the tables.

Worked Examples:

Weekday Business-Hour Polling

*/15 9-17 * * MON-FRI parses as every 15 minutes during hours 9 through 17 on weekdays. Field Ledger expands the minute field to quarter-hour values, the hour field to nine allowed hours, and the weekday field to Monday through Friday. Next Run Preview should show quarter-hour intervals inside that window, while Schedule Risk Ledger should mainly remind you to compare the preview basis with the deployment timezone.

Monthly Plus Friday Surprise

30 4 1,15 * 5 looks like it might mean 04:30 on the 1st and 15th only when those dates are Friday. Under common Vixie/Cronie day rules, both day fields are restricted, so either field can match. Schedule Risk Ledger reports Day field semantics with medium severity, and Next Run Preview can show runs on the 1st, the 15th, and Fridays.

Startup Macro With No Clock Preview

@reboot is accepted as a supported macro, but it is not previewable because it runs when the cron daemon starts. Field Ledger shows the macro detail instead of five expanded time fields. Next Run Preview has no rows, and Schedule Risk Ledger recommends testing startup behavior on the target host.

Quartz Syntax Caught Before Handoff

0 15 10 ? * MON-FRI has six fields and includes the Quartz ? character. The parser reports that Unix cron expressions need exactly five fields and flags Quartz/Jenkins-only syntax. Remove the seconds field and replace Quartz-specific day syntax with a supported Unix form before using Field Ledger or Next Run Preview for review.

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 to 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, HTML rendering 2026-01-16.
• crontab(5), Debian Manpages.
• CronTrigger Tutorial, Quartz Scheduler.
• Pipeline Syntax, Jenkins.