Schedules Are Rules, Not Lists of Timestamps: Introducing Yarunoka
A developer has introduced Yarunoka, a language-independent JSON DSL designed to preserve schedule rules and intent rather than just flat timestamp lists.
Stock photo for illustration only, not from the actual event
- Yarunoka is a language-independent specification for a compact JSON DSL named Yrnk.
- The core philosophy centers on preserving schedule rules and logic instead of merely generating date lists.
- The initial PHP implementation requires PHP 8.4 and integrates with Yasumi for holiday management.
- Designed so that both human readers and generative AI can easily interpret scheduling intent.
Imagine translating a complex schedule requirement into data: payday falls on the 25th of every month, but if the 25th is not a business day, it shifts to the previous business day. A plain timestamp or a cron expression simply cannot capture this underlying business rule, leaving developers to scatter conditional logic across application codebases.
To solve this, the creator introduced Yarunoka, a language-independent specification for a small JSON DSL called Yrnk. The name originates from the Japanese question "やるのか？" (yaru no ka?), translating roughly to "Are you going to do it?" which mirrors the evaluation purpose of the system.
Consider this data representation for a payday transfer:
{
"label": "Payday transfer",
"description": "At 10:00 on the 25th of every month. If the 25th is not a business day, move it to the previous business day.",
"days": [25],
"shift": ["prev", "or_same", "business_day"],
"times": ["10:00"]
}Even without reading the implementation code, the broad meaning remains immediately clear from the data structure. Fields like label and description act as human-facing annotations that travel with the schedule without ever affecting the evaluation process itself.
Stock photo for illustration only, not from the actual event
Separating scheduling logic from job execution systems is an effective architectural pattern. It allows the exact same schedule document to be shared across vastly different applications without binding the scheduling rules to a single execution engine, queues, retry loops, or state management.
The creator noted a long-standing frustration with the boundary between calendars and to-do lists. While a to-do list tracks tasks and a calendar tracks events, both represent plans. While building a personal AI agent that needed to understand recurring activities and schedules, the goal was not just a generated list of dates, but an underlying representation of the rule itself.
A Yrnk document is built on core concepts, and its PHP implementation can integrate seamlessly with Yasumi to handle public holidays. For instance, a recycling schedule looks like this:
{
"label": "Recycling collection",
"description": "At 07:30 on the first and third Friday of each month, except on public holidays.",
"days": [["1st", "fri"], ["3rd", "fri"]],
"if": ["not", "holiday"],
"times": ["07:30"]
}Matching holidays are excluded entirely rather than shifted to alternate dates. The intent is to provide a format where intent is transparent to humans and generative AI alike, eliminating ambiguity.
The first core implementation, yarunoka/core, requires PHP 8.4 or newer with zero runtime dependencies. While version 1.0 does not yet cover abstract expressions like "the first half of March," conformance tests are provided to ensure that different language ports evaluate documents consistently.
Source: Dev.to
Found something wrong in this article? Report an issue with this article
Comments
Leave a Comment