Manifest-Schema

pithyx.json im Wurzelordner eines App-Pakets wird gegen ein einziges JSON-Schema (Draft 2020-12) geprüft: sdk/schema/manifest.v1.schema.json im Repository, veröffentlicht als @pithyx/sdk/schema/manifest.v1.schema.json und identifiziert als https://pithyx.org/schema/manifest.v1.schema.json. Die Box, pithyx validate und die TypeScript-Typen des SDK lesen alle diese Datei. Die Tabellen unten werden bei jedem Build der Website daraus erzeugt; die Beschreibungen kommen aus dem Schema und sind deshalb englisch. Wie die Felder zusammenspielen, erklärt Das Manifest.

Unbekannte Felder sind überall Fehler. Das Schema ist ein stabiler Vertrag: Ein neues optionales Feld ist eine Minor-Änderung, alles andere eine Major-Änderung. Ein Verstoß wird als app.manifest.schema_violation mit dem JSON-Pointer des Felds gemeldet. Über das Schema hinaus prüft die Box die ID (app.manifest.id_invalid, app.manifest.id_reserved), die Versionsbereiche, ob window.minSize in window.defaultSize passt, Duplikate und Verweise zwischen Feldern, die Cron-Ausdrücke und die erweiterten Rechte (Befunde).

Pfade nutzen . für verschachtelte Felder, [] für die Einträge eines Arrays und <name> oder <language> für Schlüssel, die du wählst. “Pflicht” bezieht sich auf das umgebende Objekt: backend.compose ist Pflicht, wenn es ein backend gibt.

Oberste Ebene

Feld	Typ	Pflicht	Standard	Erlaubte Werte	Beschreibung
$schema	string	nein	–	höchstens 500 Zeichen	Path or URL of this schema, for editors. Ignored by the box.
manifestVersion	integer	ja	–	1	The manifest schema this file follows.
id	string	ja	–	höchstens 100 Zeichen; ^[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	ja	–	höchstens 64 Zeichen; ein Muster aus 148 Zeichen, siehe das Schema	SemVer 2.0 version of the app, without build metadata, for example 1.2.0 or 2.0.0-beta.1.
name	object	ja	–	–	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	nein	–	–	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	ja	–	–	Who makes the app.
license	string	nein	–	höchstens 100 Zeichen; ^[!-~]+( [!-~]+)*$	SPDX license expression of the app, for example MIT or MIT OR Apache-2.0.
homepage	string	nein	–	höchstens 500 Zeichen; ^https?://[!-~]+$	The app’s website or source repository.
entry	string	ja	–	höchstens 200 Zeichen; ^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	ja	–	höchstens 100 Zeichen; ein Muster aus 1455 Zeichen, siehe das Schema	SemVer range of @pithyx/sdk the app was built against, for example ^1.0.0.
pithyx	string	nein	–	höchstens 100 Zeichen; ein Muster aus 1455 Zeichen, siehe das 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	nein	–	1 bis 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 aus string	ja	–	keine Duplikate; 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. Jeder Eintrag: 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	ja	–	–	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 aus object	nein	–	höchstens 16 Einträge	Places for files the app needs, each mapped by an administrator to a folder in a shared folder.
fileHandlers	Array aus object	nein	–	höchstens 32 Einträge	Files the app can open.
backend	object	nein	–	–	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

Feld	Typ	Pflicht	Standard	Erlaubte Werte	Beschreibung
name.en	string	ja	–	1 bis 60 Zeichen; ^[^\u0000-\u001f\u007f]+$	The English text, shown when no other language matches. One line, at most 60 characters.
name.<language>	string	nein	–	1 bis 60 Zeichen; ^[^\u0000-\u001f\u007f]+$	Schlüssel passend zu ^[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

Feld	Typ	Pflicht	Standard	Erlaubte Werte	Beschreibung
description.en	string	ja	–	1 bis 500 Zeichen; ^[^\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	nein	–	1 bis 500 Zeichen; ^[^\u0000-\u0009\u000b-\u001f\u007f]+$	Schlüssel passend zu ^[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

Feld	Typ	Pflicht	Standard	Erlaubte Werte	Beschreibung
author.name	string	ja	–	1 bis 100 Zeichen; ^[^\u0000-\u001f\u007f]+$	A person or an organization.
author.url	string	nein	–	höchstens 500 Zeichen; ^https?://[!-~]+$	The author’s website.

window

Feld	Typ	Pflicht	Standard	Erlaubte Werte	Beschreibung
window.instances	string	ja	–	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	ja	–	–	A size in CSS pixels.
window.defaultSize.width	integer	ja	–	100 bis 8192	The width in CSS pixels.
window.defaultSize.height	integer	ja	–	100 bis 8192	The height in CSS pixels.
window.minSize	object	ja	–	–	A size in CSS pixels.
window.minSize.width	integer	ja	–	100 bis 8192	The width in CSS pixels.
window.minSize.height	integer	ja	–	100 bis 8192	The height in CSS pixels.
window.loading	object	nein	–	–	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	nein	–	–	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	ja	–	1 bis 60 Zeichen; ^[^\u0000-\u001f\u007f]+$	The English text, shown when no other language matches. One line, at most 60 characters.
window.loading.text.<language>	string	nein	–	1 bis 60 Zeichen; ^[^\u0000-\u001f\u007f]+$	Schlüssel passend zu ^[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	nein	–	–	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

Feld	Typ	Pflicht	Standard	Erlaubte Werte	Beschreibung
storage[].id	string	ja	–	^[a-z][a-z0-9-]{0,31}$	Unique within the app.
storage[].name	object	ja	–	–	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	ja	–	1 bis 60 Zeichen; ^[^\u0000-\u001f\u007f]+$	The English text, shown when no other language matches. One line, at most 60 characters.
storage[].name.<language>	string	nein	–	1 bis 60 Zeichen; ^[^\u0000-\u001f\u007f]+$	Schlüssel passend zu ^[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	nein	–	–	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	ja	–	1 bis 500 Zeichen; ^[^\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	nein	–	1 bis 500 Zeichen; ^[^\u0000-\u0009\u000b-\u001f\u007f]+$	Schlüssel passend zu ^[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	ja	–	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	ja	–	–	The app cannot start until this storage is mapped.
storage[].services	Array aus string	nein	–	mindestens 1 Einträge; keine Duplikate; ^[a-z0-9][a-z0-9_.-]{0,62}$	Backend services that mount this storage. Needs a backend. Jeder Eintrag: A service of backend/compose.yaml.

fileHandlers

Feld	Typ	Pflicht	Standard	Erlaubte Werte	Beschreibung
fileHandlers[].extensions	Array aus string	ja	–	1 bis 32 Einträge; keine Duplikate; höchstens 32 Zeichen; ^[a-z0-9]+([.+_-][a-z0-9]+)*$	Lowercase extensions without the leading dot, for example png or tar.gz.
fileHandlers[].mimeTypes	Array aus string	nein	–	1 bis 32 Einträge; keine Duplikate; höchstens 127 Zeichen; ^[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*$	MIME types, for example image/png.
fileHandlers[].isDefault	boolean	nein	–	–	Whether the app is the default for these files when it is the only handler.

backend

Feld	Typ	Pflicht	Standard	Erlaubte Werte	Beschreibung
backend.compose	string	ja	–	höchstens 200 Zeichen; ^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	ja	–	höchstens 16 Einträge	The ports the proxy offers, by name. api is required: it is the default endpoint of app.backend.
backend.endpoints.api	object	ja	–	–	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	ja	–	^[a-z0-9][a-z0-9_.-]{0,62}$	A service of backend/compose.yaml.
backend.endpoints.api.port	integer	ja	–	1 bis 65535	The port the service listens on inside the app’s internal network. It never gets a host port.
backend.endpoints.<name>	object	nein	–	–	Schlüssel passend zu ^[a-z][a-z0-9-]{0,31}$. Jeder ist wie backend.endpoints.api.
backend.lifecycle	string	ja	–	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	nein	600	60 bis 86400	Seconds an onDemand backend keeps running after its last window closed. Default 600. Ignored for always.
backend.root	boolean	nein	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	nein	–	–	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 aus string	ja	–	1 bis 32 Einträge; keine Duplikate; ^[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. Jeder Eintrag: A service of backend/compose.yaml.
backend.health	object	nein	–	–	The daemon calls GET path on endpoint to learn whether the backend is ready; a 2xx answer means running.
backend.health.endpoint	string	ja	–	^[a-z][a-z0-9-]{0,31}$	A key of endpoints.
backend.health.path	string	ja	–	höchstens 200 Zeichen; ^/[!-~]*$	A path on a backend endpoint, starting with /.
backend.schedules	Array aus object	nein	–	höchstens 16 Einträge	Recurring jobs that call the backend on a cron schedule, also without an open window.
backend.schedules[].id	string	ja	–	^[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	ja	–	höchstens 100 Zeichen	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	ja	–	^[a-z][a-z0-9-]{0,31}$	A key of endpoints.
backend.schedules[].path	string	ja	–	höchstens 200 Zeichen; ^/[!-~]*$	A path on a backend endpoint, starting with /.
backend.elevated	Array aus string	nein	–	höchstens 32 Einträge; keine Duplikate; höchstens 200 Zeichen; ein Muster aus 131 Zeichen, siehe das Schema	Rights beyond the sandbox. The Compose file must use exactly what these allow. Jeder Eintrag: 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.

Verwandte Schemas

Im selben Ordner: compose.v1.rules.json (die Compose-Regeln), images-lock.v1.schema.json (backend/images.lock.json) und die Katalogformate catalog.v1.schema.json, index.v1.schema.json, index-signature.v1.schema.json, maintainers.v1.schema.json und catalog.v1.rules.json.