{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/itscrystalline/occasion/refs/heads/main/occasions.schema.json",
"title": "The occasion configuration file.",
"type": "object",
"required": [
"dates"
],
"properties": {
"imports": {
"description": "A list of configuration file paths to import alongside this one, either absolute or relative to **the folder this file is in**. (not strictly the folder $OCCASION_CONFIG is in!) For performance reasons, `occasion` will not process imports more than 3 layers deep.",
"type": "array",
"items": {
"type": "string"
}
},
"dates": {
"description": "A pair of a date pattern to match, and a message to show once the current date at runtime matches the date pattern.",
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"description": "The message to show when the configured date pattern matches.",
"type": "string"
},
"command": {
"description": "The inputs to pass to the spawned shell. This could either be a simple shell command, or a script that you pass into a shell or interpreter.\nThe following environment variables are available to you:\n - `DAY_OF_WEEK`: The name of day of the week. (ex. \"Tuesday\")\n - `DAY_IN_WEEK`: The number of days after the week has started. Week boundary is set in `week_start_day`.\n - `DAY_OF_MONTH`: The day of the month.\n - `WEEK`: The week number in the year.\n - `MONTH`: The month number.\n - `YEAR`: The year in your system's default locale's year format, usually AD.",
"type": "object",
"required": [
"run"
],
"properties": {
"run": {
"description": "The command or script to pass into the shell/interpreter. If `shell_args` is not specified, then an appropriate flag (`-c` or `/C`) is automatically added to tell the shell to run the input.",
"type": "string"
},
"shell": {
"description": "The optional host shell/interpreter. Accepts a path to an executable or just the executable name if it is already in the PATH. Defaults to `sh` on Linux/macOS, and `cmd.exe` on Windows.",
"type": "string"
},
"shell_args": {
"description": "Optional shell arguments as an array to pass to the shell/interpreter. If this is specified, then `occasion` will not add the script flag (`-c` or `/C`) for you. Keep in mind that the command/script in `run` is added last.",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"time": {
"description": "The date pattern to match. Also define `merge_strategy` if you want to change how this property and `condition` are merged togheter.",
"type": "object",
"properties": {
"day_of": {
"description": "The day to match. Can be *either* a day of the week *or* a day of the month. Leaving this empty means it will match for every day.",
"properties": {
"week": {
"description": "The day of the week this pattern will match. Accepts either the full day name, like 'Tuesday', or a shortened form, like 'Tue'. Case-insensitive.",
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"month": {
"description": "The day of the month this pattern will match. Accepts a number from 1-31.",
"type": "array",
"items": {
"type": "number",
"minimum": 1,
"maximum": 31
},
"uniqueItems": true
}
},
"oneOf": [
{
"required": [
"week"
],
"not": {
"required": [
"month"
]
}
},
{
"required": [
"month"
],
"not": {
"required": [
"week"
]
}
}
]
},
"week": {
"description": "The week number (in the year) to match. Accepts a positive number.",
"type": "array",
"items": {
"type": "number",
"minimum": 1,
"maximum": 53,
"uniqueItems": true
}
},
"month": {
"description": "The month to match. Accepts the full month name, like 'April', or a shortened name, like 'Apr'. Case-insensitive.",
"type": "array",
"items": {
"type": "string",
"uniqueItems": true
}
},
"year": {
"description": "The year (in your system's default locale's year format, usually AD) to match. Accepts a positive number.",
"type": "array",
"items": {
"type": "number",
"minimum": 0,
"uniqueItems": true
}
}
}
},
"condition": {
"description": "The custom predicate to match. Also define `merge_strategy` if you want to change how this property and `time` are merged togheter.",
"type": "object",
"properties": {
"shell": {
"description": "The inputs to pass to the spawned shell. This could either be a simple shell command, or a script that you pass into a shell or interpreter. A return code of 0 means `true`, any other value means `false`. Also define `merge_strategy` if you want to change how this property and `predicate` are merged togheter.\nThe following environment variables are available to you:\n - `DAY_OF_WEEK`: The name of day of the week. (ex. \"Tuesday\")\n - `DAY_IN_WEEK`: The number of days after the week has started. Week boundary is set in `week_start_day`.\n - `DAY_OF_MONTH`: The day of the month.\n - `WEEK`: The week number in the year.\n - `MONTH`: The month number.\n - `YEAR`: The year in your system's default locale's year format, usually AD.",
"type": "object",
"required": [
"run"
],
"properties": {
"run": {
"description": "The command or script to pass into the shell/interpreter. If `shell_args` is not specified, then an appropriate flag (`-c` or `/C`) is automatically added to tell the shell to run the input.",
"type": "string"
},
"shell": {
"description": "The optional host shell/interpreter. Accepts a path to an executable or just the executable name if it is already in the PATH. Defaults to `sh` on Linux/macOS, and `cmd.exe` on Windows.",
"type": "string"
},
"shell_args": {
"description": "Optional shell arguments as an array to pass to the shell/interpreter. If this is specified, then `occasion` will not add the script flag (`-c` or `/C`) for you. Keep in mind that the command/script in `run` is added last.",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"predicate": {
"description": "A custom boolean expression to evaluate. Useful if you do not want to evaluate shell args. Also define `merge_strategy` if you want to change how this property and `shell` are merged togheter.\nThe following environment variables are available to you:\n - `DAY_IN_WEEK`: The number of days after the week has started. Week boundary is set in `week_start_day`.\n - `DAY_OF_MONTH`: The day of the month.\n - `WEEK`: The week number in the year.\n - `MONTH`: The month number.\n - `YEAR`: The year in your system's default locale's year format, usually AD.",
"type": "string"
},
"merge_strategy": {
"description": "If `shell` and `predicate` are both defined, This defines how both results should be combined. Accepts boolean operators `AND (and/both/&)`, `OR (or/any/|)`, `XOR (xor/either/^)`, `NAND (nand)` and `NOR (nor/neither)`.",
"type": "string",
"enum": [
"AND",
"and",
"both",
"&",
"OR",
"or",
"any",
"|",
"XOR",
"xor",
"either",
"^",
"NAND",
"nand",
"NOR",
"nor",
"neither"
]
}
}
},
"merge_strategy": {
"description": "If `time` and `condition` are both defined, This defines how both results should be combined. Accepts boolean operators `AND (and/both/&)`, `OR (or/any/|)`, `XOR (xor/either/^)`, `NAND (nand)` and `NOR (nor/neither)`.",
"type": "string",
"enum": [
"AND",
"and",
"both",
"&",
"OR",
"or",
"any",
"|",
"XOR",
"xor",
"either",
"^",
"NAND",
"nand",
"NOR",
"nor",
"neither"
]
}
},
"anyOf": [
{
"anyOf": [
{
"required": [
"message"
]
},
{
"required": [
"command"
]
}
]
},
{
"anyOf": [
{
"required": [
"time"
]
},
{
"required": [
"condition"
]
}
]
}
]
}
},
"multiple_behavior": {
"description": "This option describes what `occasion` should do when multiple configured dates match. Possible options are:\n - `first`, which shows only the first (highest) configured message\n - `last`, which shows only the last (lowest) configured message\n - `random`, which shows a random message\n - `all`, which is an object with a key `seperator` which configures the seperator between the messages.",
"oneOf": [
{
"type": "string",
"enum": [
"first",
"last",
"random"
]
},
{
"type": "object",
"properties": {
"all": {
"type": "object",
"properties": {
"seperator": {
"type": "string"
}
},
"additionalProperties": false
}
},
"required": [
"all"
],
"additionalProperties": false
}
]
},
"week_start_day": {
"description": "The day name in which marks the start of the new week. Accepts either the full day name, like 'Tuesday', or a shortened form, like 'Tue'. Case-insensitive. Defaults to Sunday if not specified.",
"type": "string"
}
}
}