# Manifest schema

> Every field of pithyx.json with its type, whether it is required, its default, its allowed values and its description, generated from the JSON Schema.

Source: https://pithyx.org/docs/reference/manifest-schema/
Markdown: https://pithyx.org/docs/reference/manifest-schema.md

`pithyx.json` at the root of an app package is validated against one JSON Schema (draft 2020-12): `sdk/schema/manifest.v1.schema.json` in the repository, published as `@pithyx/sdk/schema/manifest.v1.schema.json` and identified as `https://pithyx.org/schema/manifest.v1.schema.json`. The box, `pithyx validate` and the TypeScript types of the SDK all read this file. The tables below are generated from it each time the site is built; how the fields work together is explained in [The manifest](https://pithyx.org/docs/developers/apps/manifest/).

Unknown fields are errors everywhere. The schema is a stable contract: a new optional field is a minor change, anything else a major one. A violation is reported as [`app.manifest.schema_violation`](https://pithyx.org/docs/reference/errors/#app.manifest.schema_violation) with the JSON pointer of the field. Beyond the schema the box checks the id ([`app.manifest.id_invalid`](https://pithyx.org/docs/reference/errors/#app.manifest.id_invalid), [`app.manifest.id_reserved`](https://pithyx.org/docs/reference/errors/#app.manifest.id_reserved)), the version ranges, that `window.minSize` fits into `window.defaultSize`, duplicates and references between fields, the cron expressions and the elevated rights ([Findings](https://pithyx.org/docs/reference/cli/findings/#app-packages)).

Paths use `.` for nested fields, `[]` for the entries of an array and `<name>` or `<language>` for keys you choose. "Required" is relative to the enclosing object: `backend.compose` is required when there is a `backend`.

## Top level

| Field             | Type            | Required | Default | Allowed values                                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------- | --------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$schema`         | string          | no       | –       | at most 500 characters                                                                                                           | Path or URL of this schema, for editors. Ignored by the box.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `manifestVersion` | integer         | yes      | –       | `1`                                                                                                                              | The manifest schema this file follows.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `id`              | string          | yes      | –       | at most 100 characters; `^[a-z][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*){2,4}$`                                                           | The author's domain reversed plus the app name: 3 to 5 parts of lowercase letters, digits and dashes, at most 100 characters, for example `com.mueller.chat` or `io.github.jan.chat`. Unique per box. `org.pithyx.*` is reserved for the system apps and the official catalog.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `version`         | string          | yes      | –       | at most 64 characters; a pattern of 148 characters, see the schema                                                               | SemVer 2.0 version of the app, without build metadata, for example `1.2.0` or `2.0.0-beta.1`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `name`            | object          | yes      | –       | –                                                                                                                                | A short text in several languages, keyed by BCP 47 language tag, for example the app's name or a storage request's name. `en` is required and used when nothing else matches. One line, at most 60 characters per language.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `description`     | object          | no       | –       | –                                                                                                                                | A text in several languages, keyed by BCP 47 language tag, for example the app's description of one or two sentences for the store and the install dialog. `en` is required and used when nothing else matches. At most 500 characters per language; line breaks are allowed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `author`          | object          | yes      | –       | –                                                                                                                                | Who makes the app.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `license`         | string          | no       | –       | at most 100 characters; `^[!-~]+( [!-~]+)*$`                                                                                     | SPDX license expression of the app, for example `MIT` or `MIT OR Apache-2.0`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `homepage`        | string          | no       | –       | at most 500 characters; `^https?://[!-~]+$`                                                                                      | The app's website or source repository.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `entry`           | string          | yes      | –       | at most 200 characters; `^frontend/([A-Za-z0-9_][A-Za-z0-9._-]*/)*[A-Za-z0-9_][A-Za-z0-9._-]*\.html$`                            | Path of the HTML page the desktop loads in the sandboxed window, inside `frontend/` of the package, for example `frontend/index.html`. Segments never start with a dot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `sdk`             | string          | yes      | –       | at most 100 characters; a pattern of 1455 characters, see the schema                                                             | SemVer range of `@pithyx/sdk` the app was built against, for example `^1.0.0`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `pithyx`          | string          | no       | –       | at most 100 characters; a pattern of 1455 characters, see the schema                                                             | SemVer range of the Pithyx versions the app runs on, for example `>=0.1.0`. Optional; without it the app claims to run on every version. A box installs a version only when its own version is in the range, and lists a catalog version only then. Unlike npm, a box running a prerelease matches by plain SemVer precedence, so `>=0.1.0` includes `0.2.0-beta.1`, while `^0.1.0` does not (it ends below `0.2.0-0`). Catalogs require it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `dataVersion`     | integer         | no       | –       | 1 to 2147483647                                                                                                                  | The version of the format of the app's stored data (volumes, its stored values and the files of its storage requests), an integer from 1. Optional. Raise it with every release that converts data in a way the previous version cannot read. A box goes back to an older version from a catalog only when both declare the same `dataVersion`; going back to the version before an update with its snapshot works without it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `permissions`     | array of string | yes      | –       | no duplicates; `files.read`, `files.write`, `files.shares`, `notifications`, `directory.read`, `network.internet`, `network.lan` | The permissions the app asks for. Each one appears in the install dialog and can be revoked later. Each entry: A permission an app declares. Nothing is granted by using an API: the install dialog lists every declared permission, an administrator confirms them for the app, and each one can be revoked later (the app gets `permissionsChange`). Which users may use the app at all is a separate grant per user and group. The daemon checks every permission on every call that reaches data or leaves the window. An update that declares a new permission waits until an administrator confirms it; the old version keeps running. `files.read`: read files the user opens with the app or picks in a desktop file dialog. `files.write`: write those files, and save new files where the user chooses in a desktop save dialog. `files.shares`: browse every shared folder the user may access, with the user's own rights. `notifications`: show notifications. `directory.read`: list all users and groups of the box. `network.internet`: outgoing connections to the internet, from the window (`connect-src https:`) and from the backend. `network.lan`: outgoing connections from the backend to the local network (private, shared and link-local addresses such as `192.168.0.0/16`); without it the backend reaches no other device in the LAN, also with `network.internet`. The box itself is never reachable. |
| `window`          | object          | yes      | –       | –                                                                                                                                | How the app's windows behave. `defaultSize` is the size of a new window when the user has no remembered size for the app; `minSize` is the smallest size on screens that can fit it, at most `defaultSize` in both dimensions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `storage`         | array of object | no       | –       | at most 16 entries                                                                                                               | Places for files the app needs, each mapped by an administrator to a folder in a shared folder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `fileHandlers`    | array of object | no       | –       | at most 32 entries                                                                                                               | Files the app can open.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `backend`         | object          | no       | –       | –                                                                                                                                | An optional backend of one or more containers, described by a Compose file in the package and reached only through the daemon's proxy.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## name

| Field             | Type   | Required | Default | Allowed values                                  | Description                                                                                                                                                            |
| ----------------- | ------ | -------- | ------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name.en`         | string | yes      | –       | 1 to 60 characters; `^[^\u0000-\u001f\u007f]+$` | The English text, shown when no other language matches. One line, at most 60 characters.                                                                               |
| `name.<language>` | string | no       | –       | 1 to 60 characters; `^[^\u0000-\u001f\u007f]+$` | Keys matching `^[a-z]{2,3}(-[A-Za-z0-9]{1,8})*$`. The text in the language of the key, a BCP 47 language tag such as `de` or `pt-BR`. One line, at most 60 characters. |

## description

| Field                    | Type   | Required | Default | Allowed values                                                | Description                                                                                                                                                                            |
| ------------------------ | ------ | -------- | ------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `description.en`         | string | yes      | –       | 1 to 500 characters; `^[^\u0000-\u0009\u000b-\u001f\u007f]+$` | The English text, shown when no other language matches. At most 500 characters; line breaks are allowed.                                                                               |
| `description.<language>` | string | no       | –       | 1 to 500 characters; `^[^\u0000-\u0009\u000b-\u001f\u007f]+$` | Keys matching `^[a-z]{2,3}(-[A-Za-z0-9]{1,8})*$`. The text in the language of the key, a BCP 47 language tag such as `de` or `pt-BR`. At most 500 characters; line breaks are allowed. |

## author

| Field         | Type   | Required | Default | Allowed values                                   | Description                  |
| ------------- | ------ | -------- | ------- | ------------------------------------------------ | ---------------------------- |
| `author.name` | string | yes      | –       | 1 to 100 characters; `^[^\u0000-\u001f\u007f]+$` | A person or an organization. |
| `author.url`  | string | no       | –       | at most 500 characters; `^https?://[!-~]+$`      | The author's website.        |

## window

| Field                            | Type    | Required | Default | Allowed values                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------- | ------- | -------- | ------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `window.instances`               | string  | yes      | –       | `single`, `multi`                               | `single`: opening the app again focuses the user's existing window on this device and passes the launch arguments to it (`launch` event). `multi`: every launch opens a new window.                                                                                                                                                                                                                                                                                                                                                    |
| `window.defaultSize`             | object  | yes      | –       | –                                               | A size in CSS pixels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `window.defaultSize.width`       | integer | yes      | –       | 100 to 8192                                     | The width in CSS pixels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `window.defaultSize.height`      | integer | yes      | –       | 100 to 8192                                     | The height in CSS pixels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `window.minSize`                 | object  | yes      | –       | –                                               | A size in CSS pixels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `window.minSize.width`           | integer | yes      | –       | 100 to 8192                                     | The width in CSS pixels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `window.minSize.height`          | integer | yes      | –       | 100 to 8192                                     | The height in CSS pixels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `window.loading`                 | object  | no       | –       | –                                               | What a window shows before the app is ready. The desktop always draws the app's icon and name in a new window and an indicator after 300 ms, until the app connected (or, with `untilReady`, until it called `app.window.ready()`). While the backend starts, a line of text says so; without `text` it is the desktop's own, such as "Starting Lists ...". `text` is the line shown while the backend starts, in the user's language, for example "Opening your lists ...": say what happens in plain words, without technical terms. |
| `window.loading.text`            | object  | no       | –       | –                                               | A short text in several languages, keyed by BCP 47 language tag, for example the app's name or a storage request's name. `en` is required and used when nothing else matches. One line, at most 60 characters per language.                                                                                                                                                                                                                                                                                                            |
| `window.loading.text.en`         | string  | yes      | –       | 1 to 60 characters; `^[^\u0000-\u001f\u007f]+$` | The English text, shown when no other language matches. One line, at most 60 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `window.loading.text.<language>` | string  | no       | –       | 1 to 60 characters; `^[^\u0000-\u001f\u007f]+$` | Keys matching `^[a-z]{2,3}(-[A-Za-z0-9]{1,8})*$`. The text in the language of the key, a BCP 47 language tag such as `de` or `pt-BR`. One line, at most 60 characters.                                                                                                                                                                                                                                                                                                                                                                 |
| `window.loading.untilReady`      | boolean | no       | –       | –                                               | Whether the window keeps the placeholder after the app connected until it calls `app.window.ready()`, for an app that first loads its data. The desktop removes it after 30 seconds in any case. Default false.                                                                                                                                                                                                                                                                                                                        |

## storage

| Field                              | Type            | Required | Default | Allowed values                                                   | Description                                                                                                                                                                                                                                                                   |
| ---------------------------------- | --------------- | -------- | ------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `storage[].id`                     | string          | yes      | –       | `^[a-z][a-z0-9-]{0,31}$`                                         | Unique within the app.                                                                                                                                                                                                                                                        |
| `storage[].name`                   | object          | yes      | –       | –                                                                | A short text in several languages, keyed by BCP 47 language tag, for example the app's name or a storage request's name. `en` is required and used when nothing else matches. One line, at most 60 characters per language.                                                   |
| `storage[].name.en`                | string          | yes      | –       | 1 to 60 characters; `^[^\u0000-\u001f\u007f]+$`                  | The English text, shown when no other language matches. One line, at most 60 characters.                                                                                                                                                                                      |
| `storage[].name.<language>`        | string          | no       | –       | 1 to 60 characters; `^[^\u0000-\u001f\u007f]+$`                  | Keys matching `^[a-z]{2,3}(-[A-Za-z0-9]{1,8})*$`. The text in the language of the key, a BCP 47 language tag such as `de` or `pt-BR`. One line, at most 60 characters.                                                                                                        |
| `storage[].description`            | object          | no       | –       | –                                                                | A text in several languages, keyed by BCP 47 language tag, for example the app's description of one or two sentences for the store and the install dialog. `en` is required and used when nothing else matches. At most 500 characters per language; line breaks are allowed. |
| `storage[].description.en`         | string          | yes      | –       | 1 to 500 characters; `^[^\u0000-\u0009\u000b-\u001f\u007f]+$`    | The English text, shown when no other language matches. At most 500 characters; line breaks are allowed.                                                                                                                                                                      |
| `storage[].description.<language>` | string          | no       | –       | 1 to 500 characters; `^[^\u0000-\u0009\u000b-\u001f\u007f]+$`    | Keys matching `^[a-z]{2,3}(-[A-Za-z0-9]{1,8})*$`. The text in the language of the key, a BCP 47 language tag such as `de` or `pt-BR`. At most 500 characters; line breaks are allowed.                                                                                        |
| `storage[].access`                 | string          | yes      | –       | `read`, `readWrite`                                              | The most the app may do with the mapped folder: `read` or `readWrite`. Users never get more than their own rights on the folder, and with `read` every backend service mounts it read-only.                                                                                   |
| `storage[].required`               | boolean         | yes      | –       | –                                                                | The app cannot start until this storage is mapped.                                                                                                                                                                                                                            |
| `storage[].services`               | array of string | no       | –       | at least 1 entries; no duplicates; `^[a-z0-9][a-z0-9_.-]{0,62}$` | Backend services that mount this storage. Needs a `backend`. Each entry: A service of `backend/compose.yaml`.                                                                                                                                                                 |

## fileHandlers

| Field                       | Type            | Required | Default | Allowed values                                                                                                    | Description                                                                  |
| --------------------------- | --------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `fileHandlers[].extensions` | array of string | yes      | –       | 1 to 32 entries; no duplicates; at most 32 characters; `^[a-z0-9]+([.+_-][a-z0-9]+)*$`                            | Lowercase extensions without the leading dot, for example `png` or `tar.gz`. |
| `fileHandlers[].mimeTypes`  | array of string | no       | –       | 1 to 32 entries; no duplicates; at most 127 characters; `^[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*$` | MIME types, for example `image/png`.                                         |
| `fileHandlers[].isDefault`  | boolean         | no       | –       | –                                                                                                                 | Whether the app is the default for these files when it is the only handler.  |

## backend

| Field                           | Type            | Required | Default | Allowed values                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------- | --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `backend.compose`               | string          | yes      | –       | at most 200 characters; `^backend/([A-Za-z0-9_][A-Za-z0-9._-]*/)*[A-Za-z0-9_][A-Za-z0-9._-]*\.ya?ml$`  | Path of the Compose file inside `backend/` of the package, usually `backend/compose.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `backend.endpoints`             | object          | yes      | –       | at most 16 entries                                                                                     | The ports the proxy offers, by name. `api` is required: it is the default endpoint of `app.backend`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `backend.endpoints.api`         | object          | yes      | –       | –                                                                                                      | A port of a backend service that the proxy offers to the app's windows. Container ports never appear in a URL: the endpoint `api` is `/apps/<id>/api/`, every other endpoint `<name>` is `/apps/<id>/api-<name>/`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `backend.endpoints.api.service` | string          | yes      | –       | `^[a-z0-9][a-z0-9_.-]{0,62}$`                                                                          | A service of `backend/compose.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `backend.endpoints.api.port`    | integer         | yes      | –       | 1 to 65535                                                                                             | The port the service listens on inside the app's internal network. It never gets a host port.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `backend.endpoints.<name>`      | object          | no       | –       | –                                                                                                      | Keys matching `^[a-z][a-z0-9-]{0,31}$`. Each one is like `backend.endpoints.api`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `backend.lifecycle`             | string          | yes      | –       | `always`, `onDemand`                                                                                   | `always`: runs while the app is installed and its pool is available. `onDemand`: runs while at least one window of the app is open for any user, plus `idleTimeout`, or while a schedule holds it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `backend.idleTimeout`           | integer         | no       | `600`   | 60 to 86400                                                                                            | Seconds an `onDemand` backend keeps running after its last window closed. Default 600. Ignored for `always`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `backend.root`                  | boolean         | no       | `false` | –                                                                                                      | The containers run as root inside the container (unprivileged on the host through user namespaces). The install dialog warns about it. Default false: they run as the app's own user.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `backend.network`               | object          | no       | –       | –                                                                                                      | Which services get the network out of the box that `network.internet` and `network.lan` open. Without it every service gets it; the others stay on the app's internal network only. No effect without one of the two permissions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `backend.network.services`      | array of string | yes      | –       | 1 to 32 entries; no duplicates; `^[a-z0-9][a-z0-9_.-]{0,62}$`                                          | The services of the Compose file that may connect out, for example only the one that fetches. Each entry: A service of `backend/compose.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `backend.health`                | object          | no       | –       | –                                                                                                      | The daemon calls `GET path` on `endpoint` to learn whether the backend is ready; a 2xx answer means running.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `backend.health.endpoint`       | string          | yes      | –       | `^[a-z][a-z0-9-]{0,31}$`                                                                               | A key of `endpoints`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `backend.health.path`           | string          | yes      | –       | at most 200 characters; `^/[!-~]*$`                                                                    | A path on a backend endpoint, starting with `/`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `backend.schedules`             | array of object | no       | –       | at most 16 entries                                                                                     | Recurring jobs that call the backend on a cron schedule, also without an open window.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `backend.schedules[].id`        | string          | yes      | –       | `^[a-z][a-z0-9-]{0,31}$`                                                                               | Stable name, unique within the app; the Log Center names it with each run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `backend.schedules[].cron`      | string          | yes      | –       | at most 100 characters                                                                                 | Five fields separated by single spaces (minute 0-59, hour 0-23, day of month 1-31, month 1-12, day of week 0-7 with 0 and 7 for Sunday), in the box's time zone. Each field is a comma list of `*`, numbers and ranges `a-b`; `*` and ranges may take a step `/n`. No names.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `backend.schedules[].endpoint`  | string          | yes      | –       | `^[a-z][a-z0-9-]{0,31}$`                                                                               | A key of `endpoints`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `backend.schedules[].path`      | string          | yes      | –       | at most 200 characters; `^/[!-~]*$`                                                                    | A path on a backend endpoint, starting with `/`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `backend.elevated`              | array of string | no       | –       | at most 32 entries; no duplicates; at most 200 characters; a pattern of 131 characters, see the schema | Rights beyond the sandbox. The Compose file must use exactly what these allow. Each entry: A right beyond the sandbox, for the backend only (D71): `host.network` (the host's network namespace), `host.pid` (the host's process namespace), `device:<path under /dev>` (one device node, for example `device:/dev/dri/renderD128`), `capability:<NAME>` (one Linux capability without the `CAP_` prefix, for example `capability:NET_ADMIN`), `docker.socket` (the Docker Engine API through the daemon's filtering proxy) and `host.full` (a privileged container: root on the host). The schema describes the planned rights; Pithyx 1.0.0 refuses every one of them with `app.elevated.unsupported`, and a later version grants them to administrators only, after a confirmation with password and TOTP. |

## Related schemas

In the same folder: `compose.v1.rules.json` (the [Compose rules](https://pithyx.org/docs/reference/compose-rules/)), `images-lock.v1.schema.json` (`backend/images.lock.json`), and the catalog formats `catalog.v1.schema.json`, `index.v1.schema.json`, `index-signature.v1.schema.json`, `maintainers.v1.schema.json` and `catalog.v1.rules.json`.