From 05f5959c3e2760c72dae659403d2c7c03a834713 Mon Sep 17 00:00:00 2001 From: Hexagon Date: Wed, 2 Jul 2025 23:49:44 +0000 Subject: [PATCH 1/4] Finalizing 1.0 --- specifications/OCPS-1.0.md | 118 +++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 specifications/OCPS-1.0.md diff --git a/specifications/OCPS-1.0.md b/specifications/OCPS-1.0.md new file mode 100644 index 0000000..4cf2376 --- /dev/null +++ b/specifications/OCPS-1.0.md @@ -0,0 +1,118 @@ +# OCPS 1.0: The Baseline + +**Status: FINAL** +**Revision: 1** +**Date: 2025-07-03** + +## 1. Introduction + +This document defines version 1.0 of the Open Cron Pattern Specification (OCPS). This version serves as the foundational baseline for all future versions. Its primary goal is to codify the established Vixie / ISC cron standard, ensuring a stable and universally understood foundation for scheduling. + +--- +## 2. Design Rationale + +The design of OCPS 1.0 is guided by the core principles of **stability, familiarity, and incremental introduction**. + +* **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. + +--- +## 3. Conformance + +An implementation is considered "OCPS 1.0 Compliant" if it correctly parses and evaluates patterns according to all rules specified in this document. Any pattern valid in OCPS 1.0 MUST remain valid and produce an identical schedule in all future versions of the specification. + +--- +## 4. Pattern Format + +### 4.1. Structure +An OCPS 1.0 pattern MUST consist of five fields separated by whitespace. A compliant parser MUST adhere to the following rules: +* It MUST reject a pattern containing any characters not explicitly allowed by Section 4.3 by raising a clear parsing error. +* Any leading or trailing whitespace from the entire string MUST be ignored. +* One or more consecutive whitespace characters MUST be treated as a single delimiter. + +`MINUTE HOUR DAY-OF-MONTH MONTH DAY-OF-WEEK` + +### 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 | + +* 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. + +### 4.3. Character Set + +After converting any textual representations (e.g., `JAN`, `SUN`) to their numeric equivalents, a pattern MUST only contain characters from the following set: + +* **Whitespace:** Space (`U+0020`) or horizontal tab (`U+0009`). +* **Digits:** `0123456789` +* **Special Characters:** `*,-/` + +--- +## 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. | + +### 5.1. Combining Special Characters + +In OCPS 1.0, the special characters are combined within a single field to create complex schedules. The combination follows a specific order of operations. + +1. **List Separation (`,`)**: The comma is the top-level separator. It breaks a field into a list of independent sub-expressions. The final set of values for the field is the union (logical `OR`) of the results of each sub-expression. +2. **Range (`-`) or Wildcard (`*`)**: Within each sub-expression, a range (`10-20`) or a wildcard (`*`) defines the initial set of numbers. A wildcard is equivalent to the full possible range for that field (e.g., `0-59` for minutes). +3. **Step (`/`)**: The step is an operator that filters the set generated by a range or wildcard. The resulting set includes the lowest value of the range, plus every S-th value after that which also falls within the range. + +--- +## 6. Operational Semantics + +### 6.1. Logical Combination of Day of Month and Day of Week +When both the `Day of Month` and `Day of Week` fields are restricted (i.e., not `*`), a match occurs if **either** field matches the current date. This is a logical `OR`. + +* **Example:** The pattern `0 12 1 * MON` will trigger at noon on the first day of every month, AND at noon on every Monday. + +### 6.2. Error Handling and Edge Cases + +#### Out-of-Range Values +A parser MUST reject a pattern if any numeric value falls outside the allowed range for its field (e.g., `60` in the minute field, `32` in the day-of-month field). This MUST be treated as a parsing error. + +#### Invalid Ranges +A range `A-B` where `A` is greater than `B` is invalid. A parser MUST treat this as a parsing error. + +#### Invalid Step Values +A step value of `0` has no logical definition and is invalid. A parser MUST reject any field containing `/0` as a parsing error. + +#### Impossible Date Combinations +A pattern containing a valid but impossible date (e.g., `* * 31 2 *` for February 31st) MUST be considered syntactically valid and MUST NOT cause a parsing error. + +Implementations that provide iterators to find the next or previous occurrences of a schedule (e.g., `findNextRun()`) SHOULD throw a runtime error or otherwise indicate that no valid run time can ever be found for such a pattern. + +### 6.3. Implementation-Specific Configurations +To allow for flexibility while maintaining a stable standard, the following rules apply to implementation-specific configurations: + +* An implementation MAY provide configuration options that alter the default behaviors defined in this specification. +* Compliance with this specification MUST be evaluated based on the implementation's default, unconfigured behavior. + +### 6.4. Time Zone Handling + +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. | \ No newline at end of file From b6781229a009411dfafb7a02becd2fa260ad24b4 Mon Sep 17 00:00:00 2001 From: Hexagon Date: Thu, 3 Jul 2025 02:11:44 +0200 Subject: [PATCH 2/4] Update OCPS-1.0.md * Fixes line breaks in header --- specifications/OCPS-1.0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specifications/OCPS-1.0.md b/specifications/OCPS-1.0.md index 4cf2376..26f2b0c 100644 --- a/specifications/OCPS-1.0.md +++ b/specifications/OCPS-1.0.md @@ -1,8 +1,8 @@ # OCPS 1.0: The Baseline -**Status: FINAL** -**Revision: 1** -**Date: 2025-07-03** +**Status:** FINAL +**Revision:** 1 +**Date:** 2025-07-03 ## 1. Introduction @@ -115,4 +115,4 @@ A compliant parser or scheduler MUST interpret the pattern against the implement | Revision | Date | Author(s) | Description of Changes | | :--- | :--- | :--- | :--- | -| 1 | 2025-07-03 | The OCPS Authors | Initial publication of the 1.0 specification. | \ No newline at end of file +| 1 | 2025-07-03 | The OCPS Authors | Initial publication of the 1.0 specification. | From da1b3d4919045f3466257b7a2c3f6176cd41aa35 Mon Sep 17 00:00:00 2001 From: Hexagon Date: Thu, 3 Jul 2025 00:13:03 +0000 Subject: [PATCH 3/4] Remove increment 1.0 --- increments/OCPS-increment-1.0.md | 110 ------------------------------- 1 file changed, 110 deletions(-) delete mode 100644 increments/OCPS-increment-1.0.md diff --git a/increments/OCPS-increment-1.0.md b/increments/OCPS-increment-1.0.md deleted file mode 100644 index 1a8beec..0000000 --- a/increments/OCPS-increment-1.0.md +++ /dev/null @@ -1,110 +0,0 @@ -# OCPS 1.0: The Baseline - -**Status: DRAFT** -**Date: 2025-07-03** - -## 1. Introduction - -This document defines version 1.0 of the Open Cron Pattern Specification (OCPS). This version serves as the foundational baseline for all future versions. Its primary goal is to codify the established Vixie / ISC cron standard, ensuring a stable and universally understood foundation for scheduling. - ---- -## 2. Design Rationale - -The design of OCPS 1.0 is guided by the core principles of **stability, familiarity, and incremental introduction**. - -* **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. - ---- -## 3. Conformance - -An implementation is considered "OCPS 1.0 Compliant" if it correctly parses and evaluates patterns according to all rules specified in this document. Any pattern valid in OCPS 1.0 MUST remain valid and produce an identical schedule in all future versions of the specification. - ---- -## 4. Pattern Format - -### 4.1. Structure -An OCPS 1.0 pattern MUST consist of five fields separated by whitespace. A compliant parser MUST adhere to the following rules: -* It MUST reject a pattern containing any characters not explicitly allowed by Section 4.3 by raising a clear parsing error. -* Any leading or trailing whitespace from the entire string MUST be ignored. -* One or more consecutive whitespace characters MUST be treated as a single delimiter. - -`MINUTE HOUR DAY-OF-MONTH MONTH DAY-OF-WEEK` - -### 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 | - -* 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. - -### 4.3. Character Set - -After converting any textual representations (e.g., `JAN`, `SUN`) to their numeric equivalents, a pattern MUST only contain characters from the following set: - -* **Whitespace:** Space (`U+0020`) or horizontal tab (`U+0009`). -* **Digits:** `0123456789` -* **Special Characters:** `*,-/` - ---- -## 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. | - -### 5.1. Combining Special Characters - -In OCPS 1.0, the special characters are combined within a single field to create complex schedules. The combination follows a specific order of operations. - -1. **List Separation (`,`)**: The comma is the top-level separator. It breaks a field into a list of independent sub-expressions. The final set of values for the field is the union (logical `OR`) of the results of each sub-expression. -2. **Range (`-`) or Wildcard (`*`)**: Within each sub-expression, a range (`10-20`) or a wildcard (`*`) defines the initial set of numbers. A wildcard is equivalent to the full possible range for that field (e.g., `0-59` for minutes). -3. **Step (`/`)**: The step is an operator that filters the set generated by a range or wildcard. The resulting set includes the lowest value of the range, plus every S-th value after that which also falls within the range. - ---- -## 6. Operational Semantics - -### 6.1. Logical Combination of Day of Month and Day of Week -When both the `Day of Month` and `Day of Week` fields are restricted (i.e., not `*`), a match occurs if **either** field matches the current date. This is a logical `OR`. - -* **Example:** The pattern `0 12 1 * MON` will trigger at noon on the first day of every month, AND at noon on every Monday. - -### 6.2. Error Handling and Edge Cases - -#### Out-of-Range Values -A parser MUST reject a pattern if any numeric value falls outside the allowed range for its field (e.g., `60` in the minute field, `32` in the day-of-month field). This MUST be treated as a parsing error. - -#### Invalid Ranges -A range `A-B` where `A` is greater than `B` is invalid. A parser MUST treat this as a parsing error. - -#### Invalid Step Values -A step value of `0` has no logical definition and is invalid. A parser MUST reject any field containing `/0` as a parsing error. - -#### Impossible Date Combinations -A pattern containing a valid but impossible date (e.g., `* * 31 2 *` for February 31st) MUST be considered syntactically valid and MUST NOT cause a parsing error. - -Implementations that provide iterators to find the next or previous occurrences of a schedule (e.g., `findNextRun()`) SHOULD throw a runtime error or otherwise indicate that no valid run time can ever be found for such a pattern. - -### 6.3. Implementation-Specific Configurations -To allow for flexibility while maintaining a stable standard, the following rules apply to implementation-specific configurations: - -* An implementation MAY provide configuration options that alter the default behaviors defined in this specification. -* Compliance with this specification MUST be evaluated based on the implementation's default, unconfigured behavior. - -### 6.4. Time Zone Handling - -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. From 04557245a8bff204d712738a4c64042ce9874a26 Mon Sep 17 00:00:00 2001 From: Hexagon Date: Mon, 7 Jul 2025 00:03:59 +0200 Subject: [PATCH 4/4] Update OCPS-1.0.md --- specifications/OCPS-1.0.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/specifications/OCPS-1.0.md b/specifications/OCPS-1.0.md index 26f2b0c..1bccd6a 100644 --- a/specifications/OCPS-1.0.md +++ b/specifications/OCPS-1.0.md @@ -11,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