Fuzzy Schedule Time Syntax Specification | GitHub Agentic Workflows
Skip to main content Fuzzy Schedule Time Syntax Specification Version : 1.2.0 Status : Draft Specification Latest Version : fuzzy-schedule-specification Editor : GitHub Agentic Workflows Team Abstract Section titled “Abstract” This specification defines the Fuzzy Schedule Time Syntax, a human-friendly scheduling language for GitHub Agentic Workflows that automatically distributes workflow execution times to prevent server load spikes.
The syntax supports daily, hourly, weekly, and interval-based schedules with optional time constraints and timezone conversions. The specification includes a deterministic scattering algorithm that uses hash functions to assign consistent execution times to workflows based on their identifiers, ensuring predictable behavior across multiple compilations while distributing load across an organization’s infrastructure.
Status of This Document Section titled “Status of This Document” This section describes the status of this document at the time of publication. This is a draft specification and may be updated, replaced, or made obsolete by other documents at any time. This document is governed by the GitHub Agentic Workflows project specifications process. Table of Contents Section titled “Table of Contents” Introduction Conformance Core Syntax Time Specifications Timezone Support Scattering Algorithm Cron Expression Generation Safeguards Error Handling Compliance Testing Sync Notes Calendar Output Schema Norms 1.
Introduction Section titled “1. Introduction” 1.1 Purpose Section titled “1.1 Purpose” The Fuzzy Schedule Time Syntax addresses the problem of server load spikes that occur when multiple workflows execute simultaneously using fixed-time schedules. Traditional cron expressions require explicit time specifications, leading developers to commonly use convenient times (e.g., midnight, on-the-hour) that create load concentration.
This specification defines a natural language syntax that automatically distributes execution times while preserving schedule semantics. 1.2 Scope Section titled “1.2 Scope” This specification covers: Natural language schedule expressions for daily, hourly, weekly, and interval-based schedules Time constraint syntax using around and between modifiers Timezone conversion syntax for local-to-UTC time translation Deterministic scattering algorithm for execution time distribution Cron expression generation from fuzzy syntax Validation requirements and error handling This specification does NOT cover: Standard cron expression syntax (handled by GitHub Actions) Monthly or yearly schedule patterns Dynamic schedule adjustment based on load metrics Schedule conflict resolution between workflows 1.3 Design Goals Section titled “1.3 Design Goals” This specification prioritizes: Human readability : Natural language expressions that clearly communicate intent Load distribution : Automatic scattering prevents simultaneous workflow execution Determinism : Same workflow identifier always produces same execution time Predictability : Execution times remain consistent across recompilations Timezone awareness : Support for local time specifications with UTC conversion 2.
Conformance Section titled “2. Conformance” 2.1 Conformance Classes Section titled “2.1 Conformance Classes” A conforming implementation is a parser that satisfies all MUST, MUST NOT, REQUIRED, SHALL, and SHALL NOT requirements in this specification. A conforming fuzzy schedule expression is a schedule string that conforms to the syntax grammar defined in Section 3 and produces a valid fuzzy cron placeholder. A conforming scattering implementation is an implementation that satisfies all scattering algorithm requirements in Section 6.
2.2 Requirements Notation Section titled “2.2 Requirements Notation” The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 . 2.3 Compliance Levels Section titled “2.3 Compliance Levels” Level 1 (Basic) : Supports daily and weekly schedules without time constraints Level 2 (Standard) : Adds support for time constraints ( around , between ) and hourly schedules Level 3 (Complete) : Includes timezone conversion, interval schedules, and bi-weekly/tri-weekly patterns 3.
Core Syntax Section titled “3. Core Syntax” 3.1 Grammar Definition Section titled “3.1 Grammar Definition” A fuzzy schedule expression MUST conform to the following ABNF grammar: fuzzy-schedule = daily-schedule / hourly-schedule / weekly-schedule / interval-schedule daily-schedule = "daily" [time-constraint] weekly-schedule = "weekly" ["on" weekday] [time-constraint] hourly-schedule = "hourly" / ("every" hour-interval) interval-schedule = "every" (minute-interval / hour-interval / day-interval / week-interval) time-constraint = around-constraint / between-constraint around-constraint = "around" time-spec between-constraint = "between" time-spec "and" time-spec time-spec = (hour-24 ":" minute) [utc-offset] / (hour-12 am-pm) [utc-offset] / time-keyword [utc-offset] time-keyword = "midnight" / "noon" am-pm = "am" / "pm" utc-offset = "utc" ("+" / "-") (hours / hours ":" minutes) weekday = "sunday" / "monday" / "tuesday" / "wednesday" / "thursday" / "friday" / "saturday" hour-24 = 1*2DIGIT ; 0-23 hour-12 = 1*2DIGIT ; 1-12 minute = 2DIGIT ; 00-59 hours = 1*2DIGIT minutes = 2DIGIT minute-interval = 1*DIGIT ("m" / "minutes" / "minute") hour-interval = 1*DIGIT ("h" / "hours" / "hour") day-interval = 1*DIGIT ("d" / "days" / "day") week-interval = 1*DIGIT ("w" / "weeks" / "week") 3.2 Daily Schedules Section titled “3.2 Daily Schedules” 3.2.1 Basic Daily Schedule Section titled “3.2.1 Basic Daily Schedule” A basic daily schedule expression SHALL take the form: daily An implementation MUST generate a fuzzy cron placeholder: FUZZY:DAILY * * * The execution time SHALL be deterministically scattered across all 24 hours and 60 minutes of the day.
3.2.2 Daily Around Time Section titled “3.2.2 Daily Around Time” A daily around schedule expression SHALL take the form: daily around <time-spec> An implementation MUST generate a fuzzy cron placeholder: FUZZY:DAILY_AROUND:HH:MM * * * The execution time SHALL be scattered within a ±60 minute window around the specified time. Example : daily around 14:00 # Generates: FUZZY:DAILY_AROUND:14:0 * * * # Scatters within window: 13:00 to 15:00 3.2.3 Daily Between Times Section titled “3.2.3 Daily Between Times” A daily between schedule expression SHALL take the form: daily between <start-time> and <end-time> An implementation MUST generate a fuzzy cron placeholder: FUZZY:DAILY_BETWEEN:START_H:START_M:END_H:END_M * * * The execution time SHALL be scattered uniformly within the specified time range, including handling of midnight-crossing ranges.
Example : daily between 9:00 and 17:00 # Generates: FUZZY:DAILY_BETWEEN:9:0:17:0 * * * # Scatters within window: 09:00 to 17:00 daily between 22:00 and 02:00 # Generates: FUZZY:DAILY_BETWEEN:22:0:2:0 * * * # Scatters within window: 22:00 to 02:00 (crossing midnight) 3.3 Weekly Schedules Section titled “3.3 Weekly Schedules” 3.3.1 Basic Weekly Schedule Section titled “3.3.1 Basic Weekly Schedule” A basic weekly schedule expression SHALL take the form: weekly An implementation MUST generate a fuzzy cron placeholder: FUZZY:WEEKLY * * * The execution SHALL be scattered across all seven days of the week and all hours/minutes of each day.
3.3.2 Weekly with Day Specification Section titled “3.3.2 Weekly with Day Specification” A weekly day schedule expression SHALL take the form: weekly on <weekday> An implementation MUST generate a fuzzy cron placeholder: FUZZY:WEEKLY:DOW * * DOW Example : weekly on monday # Generates: FUZZY:WEEKLY:1 * * 1 # Scatters across all hours on Monday 3.3.3 Weekly with Time Constraints Section ti
The rest of this page is on the live site.