Skip to content

Finalizing 1.0 #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Finalizing 1.0 #6

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
05f5959
Finalizing 1.0
Hexagon Jul 2, 2025
b678122
Update OCPS-1.0.md
Hexagon Jul 3, 2025
da1b3d4
Remove increment 1.0
Hexagon Jul 3, 2025
0455724
Update OCPS-1.0.md
Hexagon Jul 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 25 additions & 21 deletions increments/OCPS-increment-1.0.md → specifications/OCPS-1.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# OCPS 1.0: The Baseline

**Status: DRAFT**
**Date: 2025-07-03**
**Status:** FINAL
**Revision:** 1
**Date:** 2025-07-03

## 1. Introduction

Expand All @@ -10,13 +11,9 @@ This document defines version 1.0 of the Open Cron Pattern Specification (OCPS).
---
## 2. Design Rationale

The design of OCPS 1.0 is guided by the core principles of **stability, familiarity, and incremental introduction**.
The design of OCPS 1.0 is predicated on establishing a stable, universally understood foundation by codifying the Vixie/ISC cron dialect. This approach ensures that a significant corpus of existing cron patterns is immediately compliant, providing a frictionless adoption path.

* **Vixie Cron as the Foundation:** The specification intentionally codifies the Vixie/ISC cron dialect because it is the most ubiquitous and widely understood cron syntax in the world. By starting with this de facto standard, OCPS ensures that the vast majority of existing cron patterns work as expected, providing immediate value and a frictionless adoption path for developers and system administrators.

* **Intentional Exclusions:** Features from other popular cron dialects, such as Quartz's `?`, `L`, and `W` characters, or support for second-level precision, are deliberately excluded from this baseline version. This maintains the simplicity and stability of the foundation. These and other features are candidates for inclusion in subsequent, backward-compatible increments.

* **Clarification of Ambiguity:** A key goal of OCPS 1.0 is to go beyond a simple restatement of the syntax by providing strict, explicit rules for previously ambiguous or inconsistently handled edge cases (e.g., invalid ranges, step behavior). This ensures that all OCPS 1.0 compliant implementations will behave identically, increasing the reliability and portability of schedules.
To maintain a strict focus on the core five-field syntax, features that extend beyond it are intentionally deferred. This includes not only modifiers from other dialects (like Quartz's `L`, `W`, `?`) but also scheduling aliases (e.g., `@daily`). While aliases are a common feature of Vixie cron, they are treated as a separate syntactic concept and are introduced in a subsequent version. This keeps the baseline definition clean and focused, with a key objective of providing explicit rules for ambiguous edge cases to ensure all compliant implementations behave identically.

---
## 3. Conformance
Expand All @@ -36,13 +33,13 @@ An OCPS 1.0 pattern MUST consist of five fields separated by whitespace. A compl

### 4.2. Field Values

| Field | Required | Allowed Values |
| :------------- | :------- | :-------------- |
| **Minute** | Yes | 0-59 |
| **Hour** | Yes | 0-23 |
| **Day of Month** | Yes | 1-31 |
| **Month** | Yes | 1-12 or JAN-DEC |
| **Day of Week** | Yes | 0-7 or SUN-SAT |
| Field | Required | Allowed Values |
| :--- | :--- | :--- |
| **Minute** | Yes | 0-59 |
| **Hour** | Yes | 0-23 |
| **Day of Month** | Yes | 1-31 |
| **Month** | Yes | 1-12 or JAN-DEC |
| **Day of Week**| Yes | 0-7 or SUN-SAT |

* Month and Day of Week names MUST be treated as case-insensitive.
* In the Day of Week field, `0` and `7` MUST both be treated as Sunday.
Expand All @@ -58,12 +55,12 @@ After converting any textual representations (e.g., `JAN`, `SUN`) to their numer
---
## 5. Special Characters

| Character | Name | Example | Description |
| :-------- | :------------- | :----------- | :--------------------------------------------------------------------------------------------------------- |
| `*` | Wildcard | `* * * * *` | Matches every allowed value for the field. |
| `,` | List Separator | `0,15,30,45` | Specifies a list of individual values. |
| `-` | Range | `9-17` | Specifies an inclusive range of values. |
| `/` | Step | `5-59/15` | Specifies an interval. The step operates on the range it modifies, yielding `5,20,35,50` for this example. |
| Character | Name | Example | Description |
| :--- | :--- | :--- | :--- |
| `*` | Wildcard | `* * * * *` | Matches every allowed value for the field. |
| `,` | List Separator | `0,15,30,45` | Specifies a list of individual values. |
| `-` | Range | `9-17` | Specifies an inclusive range of values. |
| `/` | Step | `5-59/15` | Specifies an interval. The step operates on the range it modifies, yielding `5,20,35,50` for this example. |

### 5.1. Combining Special Characters

Expand Down Expand Up @@ -108,3 +105,10 @@ To allow for flexibility while maintaining a stable standard, the following rule
OCPS 1.0 patterns are **timezone-agnostic**.

A compliant parser or scheduler MUST interpret the pattern against the implementation's local time. The mechanism for defining this local time is an implementation detail, as per Section 6.3.

---
## Appendix A: Revision History

| Revision | Date | Author(s) | Description of Changes |
| :--- | :--- | :--- | :--- |
| 1 | 2025-07-03 | The OCPS Authors | Initial publication of the 1.0 specification. |