Reference
Pattern
All Croner implementations (JavaScript/TypeScript, Rust, Python, .NET and C++) use the same pattern syntax, described on this page. Croner is compliant with the Open Cron Pattern Specification (OCPS) versions 1.0 through 1.4, with one documented deviation in the recommended DST handling (see below). The expressions are based on Vixie Cron with powerful extensions:
Note
Options are named in the style of each language, for example domAndDow in JavaScript and dom_and_dow in Rust, Python and C++. .NET uses its own names, such as RequireBothDayFields. See Options in each language below.
-
OCPS 1.2: Optional second and year fields for enhanced precision:
- 6-field format:
SECOND MINUTE HOUR DAY-OF-MONTH MONTH DAY-OF-WEEK - 7-field format:
SECOND MINUTE HOUR DAY-OF-MONTH MONTH DAY-OF-WEEK YEAR - Supported year range: 1-9999 in JavaScript, Python and C++. Rust and .NET accept years up to 5000 in the pattern, but stop searching at the start of year 5000, so in practice runs go up to 4999
- 6-field format:
-
OCPS 1.3: Advanced calendar modifiers:
- L: Last day of month or last occurrence of a weekday.
Lin day-of-month = last day of month;LW= last weekday of the month;5L,5#LorFRI#L= last Friday of the month. - W: Nearest weekday.
15Wtriggers on the weekday closest to the 15th (moves to Friday if 15th is Saturday, Monday if 15th is Sunday). Won't cross month boundaries. - #: Nth occurrence of a weekday.
5#2= second Friday;MON#1= first Monday of the month.
- L: Last day of month or last occurrence of a weekday.
-
OCPS 1.4: Enhanced logical control:
- +: Explicit AND logic modifier. Prefix the day-of-week field with
+to require both day-of-month AND day-of-week to match. Example:0 12 1 * +MONonly triggers when the 1st is also a Monday. - ?: Wildcard alias (behaves identically to
*). Non-portable: Its use is discouraged in patterns intended for cross-system use. JavaScript, Python and C++ accept it in every field. Rust and .NET accept it only in day-of-month and day-of-week. - DST handling, the same in every implementation and based on Vixie cron, which deviates from OCPS 1.4 §4.3.1 (see below):
- Fixed-time jobs, with a single value in each of seconds, minutes and hours (e.g.
0 30 2 * * *): A time that occurs twice (DST fall back) runs once, at the first occurrence. A time that doesn't exist (DST spring forward) runs at the first valid time after the gap, on the same day. - Interval jobs, with a wildcard, step, range or list in seconds, minutes or hours (e.g.
*/5 * * * *or0 30 1,2 * * *): A time that occurs twice runs on both occurrences, so the job keeps running through the repeated hour. A time that doesn't exist is skipped. - Which jobs are fixed-time jobs differs from Vixie cron. Vixie cron treats a job as wild only when its minute or hour field starts with
*, so a list or range (e.g.30 2,14 * * *) is a fixed-time job there, but an interval job in Croner. - Searches for next and previous runs move in real time. They never return a time they have passed, and cover the first pass through a repeated hour before the second.
- Fixed-time jobs, with a single value in each of seconds, minutes and hours (e.g.
- +: Explicit AND logic modifier. Prefix the day-of-week field with
Deviation from OCPS 1.4
OCPS 1.4 §4.3.1 recommends that every job skips times in a DST gap, and runs only once when a time occurs twice. The same section asks implementations to align with Vixie cron, which runs interval jobs on both occurrences and runs fixed-time jobs after a gap. All Croner implementations follow Vixie cron, so that they schedule the same. They are stricter than Vixie cron about which jobs are fixed-time jobs, see above.
-
The implementations that schedule jobs (JavaScript, Python, .NET and C++) can also run a function once, at a date. JavaScript and Python take a date object or an ISO 8601 formatted string instead of the pattern. C++ uses
croner::Cron::once(), with a time point or an ISO 8601 string, and .NET aCronJobconstructor that takes aDateTimeOffset. An ISO 8601 string without an offset is read as local time in the job's time zone. -
By default, Croner uses OR logic for day-of-month and day-of-week (OCPS 1.0 compliant). Example:
0 20 1 * MONtriggers on the 1st of the month OR on Mondays. Use the+modifier (0 20 1 * +MON) or thedomAndDowoption for AND logic (OCPS 1.4 compliant). For more information, see issue #53.
| Field | Required | Allowed values | Allowed special characters | Remarks |
|---|---|---|---|---|
| Seconds | Optional | 0-59 | * , - / ? | OCPS 1.2: Optional, defaults to 0. ? not in Rust and .NET |
| Minutes | Yes | 0-59 | * , - / ? | ? not in Rust and .NET |
| Hours | Yes | 0-23 | * , - / ? | ? not in Rust and .NET |
| Day of Month | Yes | 1-31 | * , - / ? L W | L = last day, W = nearest weekday, LW = last weekday |
| Month | Yes | 1-12 or JAN-DEC | * , - / ? | ? not in Rust and .NET |
| Day of Week | Yes | 0-7 or SUN-SAT | * , - / ? L # + | 0 and 7 = Sunday (standard mode) 1-7 = Sunday-Saturday (Quartz mode with the alternativeWeekdays option)# = nth occurrence (e.g. MON#2) + = AND logic modifier (OCPS 1.4) |
| Year | Optional | 1-9999 | * , - / | OCPS 1.2: Optional, defaults to *. See the year range above |
Note
- Weekday and month names are case-insensitive. Both
MONandmonwork. - When using
Lin the Day of Week field with a range, it affects all specified weekdays. For example,5-6#Lmeans the last Friday and Saturday in the month. - The
#character specifies the "nth" weekday of the month. For example,5#2= second Friday,MON#1= first Monday. - The
Wcharacter operates within the current month and won't cross month boundaries. If the 1st is a Saturday,1Wmatches Monday the 3rd. - The
+modifier (OCPS 1.4) enforces AND logic:0 12 1 * +MONonly runs when the 1st is also a Monday. - Quartz mode: Enable the
alternativeWeekdaysoption to use Quartz-style weekday numbering (1=Sunday, 2=Monday, ..., 7=Saturday) instead of the standard format (0=Sunday, 1=Monday, ..., 6=Saturday). This is useful for compatibility with Quartz cron expressions.
OCPS 1.1: Predefined schedule nicknames are supported:
| Nickname | Description |
|---|---|
| @yearly / @annually | Run once a year, i.e. "0 0 1 1 *". |
| @monthly | Run once a month, i.e. "0 0 1 * *". |
| @weekly | Run once a week, i.e. "0 0 * * 0". |
| @daily / @midnight | Run once a day, i.e. "0 0 * * *". @midnight is not supported in Rust. |
| @hourly | Run once an hour, i.e. "0 * * * *". |
| @reboot | Recognized but not supported. Gives an error, as Croner cannot detect system reboot events. |
Options in each language#
The options that change how patterns are read have the same meaning in every implementation:
| JavaScript | Rust | Python | .NET | C++ |
|---|---|---|---|---|
domAndDow |
dom_and_dow |
dom_and_dow |
RequireBothDayFields |
dom_and_dow |
alternativeWeekdays |
alternative_weekdays |
alternative_weekdays |
QuartzWeekdays |
alternative_weekdays |
sloppyRanges |
sloppy_ranges |
sloppy_ranges |
LenientSteps |
sloppy_ranges |
mode |
seconds, year |
mode |
Seconds, Year |
mode |
In Rust these are set on the CronParser builder, and in .NET on CronParserOptions. See the documentation of each implementation for all options: JavaScript, Rust, Python, .NET and C++.