Cron Expression Descriptor

Translate a Small, Common Cron Subset Into Plain Language

Cron expressions are compact enough for configuration and opaque enough to slow down review. This descriptor reads the first five whitespace-separated fields as minute, hour, day of month, month, and day of week, then constructs a short sentence for several common patterns. The default */5 * * * * becomes Every 5 minutes every day.

The generated sentence is an aid to reading, not a complete cron interpreter. The component handles basic wildcards, minute steps when the hour is *, fixed minutes, fixed hour-and-minute pairs, and a non-wildcard day-of-week suffix. It does not validate numeric ranges or fully describe lists, ranges, month restrictions, day-of-month restrictions, names, or scheduler extensions.

That makes it useful for quick orientation on simple schedules while requiring a second, scheduler-aware check before deployment.

How the Sentence Is Built

After trimming and splitting the input on whitespace, the descriptor assigns the first five tokens:

minute hour day-of-month month day-of-week

It then applies a small set of rules:

• * * in minute and hour starts with “Every minute”.
• A minute beginning with */ and an hour of * starts with “Every N minutes”.
• A fixed minute with hour * starts with “At minute N of every hour”.
• Fixed minute and hour fields start with “At HH:MM”, padding each to two characters.
• Wildcards in all three calendar fields append “every day.”
• A non-wildcard day-of-week appends “on day of week VALUE.”

There is no general fallback for every combination. An unsupported calendar pattern can produce an incomplete sentence, and unsupported time syntax may be copied into clock-like output rather than interpreted.

Examples That Fit the Supported Patterns

Enter:

* * * * *

The description is Every minute every day. For:

15 * * * *

the output is At minute 15 of every hour every day. A fixed daily time such as:

30 7 * * *

becomes At 07:30 every day. The zero padding makes fixed times easier to scan.

For a weekday expression:

0 12 * * 1-5

the output is At 12:00 on day of week 1-5. The descriptor preserves 1-5 rather than translating it to Monday through Friday. That wording reflects the implementation and avoids assuming a weekday numbering convention beyond the raw field.

Reviewing a Schedule in a Pull Request

Suppose a configuration change introduces 0 3 * * *. Paste it into the descriptor and read At 03:00 every day. Use that sentence as a first-pass review aid, then check the scheduler documentation for field order and timezone. Add a human-written comment to the configuration only if the project convention supports it; generated text should not replace an execution preview.

For */15 * * * *, confirm that “Every 15 minutes every day” matches the author’s intent. Next, inspect the next several actual run times with the deployment scheduler. This catches timezone differences, unsupported step syntax, or a six-field dialect that interprets the first token as seconds.

When the output merely echoes a raw field, such as “on day of week MON-FRI,” treat it as a label rather than proof the scheduler accepts names. The descriptor does no validation.

Expressions That Produce Incomplete Descriptions

The calendar suffix is only added when all of day of month, month, and day of week are *, or when day of week is non-wildcard. Therefore:

0 9 1 * *

starts with At 09:00 but does not explain “on the first day of every month.” Likewise, 0 9 * 1 * does not describe January. The fields are present; the current rule set simply has no sentence for those restrictions.

An expression such as 0,30 * * * * enters the generic fixed-minute branch and can produce At minute 0,30 of every hour every day. A reader may infer the intent, but the component has not parsed the list. Ranges, steps attached to fixed hours, and names receive similarly literal treatment.

If the output is blank or awkward, inspect the raw expression rather than trying to derive intent from the sentence. Unsupported does not necessarily mean invalid, and a fluent sentence does not necessarily mean valid.

Field Count Behavior

Inputs with fewer than five fields display:

Invalid Cron Expression (less than 5 fields)

Five or more fields proceed. Unlike the Cron Expression Validator page, this descriptor does not reject more than six fields. It takes the first five fields for description and ignores extras in its destructuring.

That can conceal accidental text. Pasting a full line such as 0 7 * * * /usr/bin/report still describes the first five schedule fields, silently leaving the command out. A six-field scheduler that places seconds first is also misread as five-field cron: 0 30 7 * * * is interpreted as minute 0, hour 30, and day of month 7, rather than 07:30:00.

Always supply a five-field expression when you want the output to align with this component’s assumptions.

Validation Comes Before Interpretation

The descriptor does not check 0-59 minute bounds, 0-23 hour bounds, valid calendar values, or punctuation. For example, 75 40 * * * can become At 40:75 every day. The sentence is generated mechanically and does not legitimize the time.

A robust workflow has three layers: validate grammar with the target dialect, describe the schedule for human review, and preview concrete run times. The order matters. Describing malformed input can produce confident-looking nonsense; previewing with a different dialect can produce the wrong dates.

The separate validator in this project only checks token count, so it is not sufficient for field-level assurance either. Use the scheduler’s own parser or a library explicitly matching cron, Quartz, Spring, EventBridge, Kubernetes CronJob, or whichever engine will execute the expression.

Day and Time Semantics the Sentence Cannot Capture

Even a correct description may omit operational details. Cron generally evaluates in a configured timezone, which this input does not include. Daylight-saving transitions can skip or duplicate local clock times. Some implementations treat simultaneous day-of-month and day-of-week restrictions as OR; others use different semantics.

The sentence also says nothing about job duration, overlap, retries, missed executions, jitter, or startup behavior. “Every 5 minutes” describes matching wall-clock slots, not a guarantee that each run starts exactly five minutes after the previous run or that every run completes.

For an expression such as */5 * * * *, execution is usually aligned to minute values divisible by five, not five minutes after the service starts. A scheduler can still delay actual execution due to load.

Scheduler Dialects and Portability

Unix cron commonly uses five scheduling fields. Some libraries add leading seconds; Quartz adds seconds and sometimes year while supporting ?, L, W, and #. Jenkins introduces H for hashed distribution. System crontabs add a user field after the five schedule fields. Cloud services may omit seconds but change day-field rules.

This descriptor assumes the five-field ordering and recognizes none of those extensions semantically. A macro such as @daily has fewer than five fields and receives the invalid message. Named values such as MON may appear verbatim in a day-of-week sentence but are not checked against an allowed vocabulary.

Keep a schedule in the dialect of its execution environment. If moving it, translate and retest rather than relying on superficial similarity.

Error and Quality Checklist

When the page reports fewer than five fields, look for a missing wildcard or a copied fragment. When it produces an odd time, check whether the expression has leading seconds or malformed fixed fields. When it omits calendar detail, compare day-of-month, month, and day-of-week against the supported suffix rules.

Before accepting any generated description:

• Confirm the expression contains exactly the intended five fields.
• Validate each field with the target scheduler.
• Check the next five or more execution timestamps.
• State the timezone alongside operational documentation.
• Review daylight-saving and overlapping-run behavior.
• Keep the original expression visible; the sentence is lossy.

The calculation occurs in the browser as you type and executes no scheduled command. Still, avoid pasting commands or secrets: extra tokens are unnecessary and may be exposed in screenshots.

Cron Expression Descriptor FAQ

Why does 0 9 1 * * only say “At 09:00”?

The current rule set does not translate day-of-month or month restrictions. It only adds “every day” for three wildcards or a raw day-of-week suffix.

Does the descriptor validate cron ranges?

No. It can format out-of-range values into a sentence. Validate with the scheduler that will run the job.

Why is my six-field seconds expression described incorrectly?

The component assumes the first field is minutes and reads only the first five positions. It has no seconds-mode detection.

What happens to fields after the fifth?

They are ignored for description. This is why a full crontab line may appear to work even though commands do not belong in the input.

Can it translate MON-FRI to weekday names?

No. A non-wildcard day-of-week value is included verbatim as “day of week MON-FRI.” Acceptance depends on the target dialect.

Why does @hourly show an error?

The macro has fewer than five fields, and macro aliases are not implemented.

Does “Every 5 minutes” mean five minutes after startup?

Usually not. Cron step syntax normally matches aligned minute values. The descriptor does not calculate concrete run times or startup-relative intervals.