occasions.schema.json

{
  "$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"
    }
  }
}