The manifest: app.json
Every key, what it needs and what it is checked against.
Every app has an app.json at the top of its folder. Respira Code reads it at upload, and again whenever it serves the app. A release whose manifest does not pass is refused before anything is written. This page lists every key the validator knows, read from the add-on's own check, Respira_Code_Manifest::validate, and from the kit classes that validate the keys they own. The caps are generated from the source, the same data the limits page prints.
The smallest manifest
{
"manifest_version": 1,
"slug": "hello",
"version": "0.1.0",
"entry": "entry.php"
} Four keys are required: manifest_version, slug, version and entry. Everything else is optional.
A fuller one
{
"manifest_version": 1,
"slug": "demo",
"name": "Demo",
"description": "A sign-up list.",
"version": "1.0.0",
"requires_php": "7.4",
"requires_wp": "6.2",
"entry": "entry.php",
"tables": [ { "name": "demo_people" } ],
"options": [ "demo_settings" ],
"admin_pages": [ { "slug": "demo", "capability": "manage_options" } ],
"secrets": [ { "name": "RESEND_KEY", "label": "Resend API key", "required": true } ],
"emails": [
{ "kind": "welcome", "audience": "one", "vars": ["first_name"] },
{ "kind": "news", "audience": "many", "vars": ["first_name"] }
],
"personal_data": [
{
"table": "demo_people",
"pk": "id",
"email_column": "email",
"columns": ["name", "email"],
"purpose": "Send the list.",
"basis": "consent",
"children": [ { "table": "demo_mail", "fk": "person_id" } ],
"retention": [
{ "table": "demo_people", "after": { "column": "created", "days": 30 }, "where": { "status": "unconfirmed" } }
]
}
],
"tests": { "timeout": 20 }
} Required keys
| Key | Rule |
|---|---|
manifest_version | The number 1. |
slug | Must equal the slug the upload is for. Lowercase letters, digits and hyphens, up to 40 characters, starting and ending with a letter or a digit. |
version | Looks like 1.2.3 or 1.2.3-rc.1. Each number has up to 4 digits; the part after the hyphen has up to 32 letters, digits and dots. |
entry | A .php file that is in the release. It is the file the loader includes. |
Optional keys
| Key | What it takes |
|---|---|
name, description | Accepted and not validated. They describe the app to people. |
requires_php, requires_wp | A minimum version such as 7.4 or 6.5.2. A site running older is refused at deploy with a message that names both versions. |
tables | Up to 32. Each is { "name": "..." }, a name of lowercase letters, digits and underscores, starting with a letter, up to 48 characters, without the site prefix. A name may not start with respira. Migrations need their tables declared here. |
options | Up to 50 option names the app owns: lowercase letters, digits and underscores, up to 64 characters. A deploy snapshots them. |
routes | A namespace like my-app/v1 and up to 50 endpoints. See below. |
admin_pages | Up to 10 screens. Each needs a slug (lowercase letters, digits, hyphens, up to 40) and a capability. Other fields in an entry are not checked. |
cron | Up to 10 jobs. Each needs a hook (lowercase letters, digits, underscores, up to 64) and a schedule: hourly, twicedaily, daily, weekly. Optional timeout in seconds (default 300, from 10 to 1800) and offset_minutes (0 to 1440). |
contracts | Up to 20 page checks. Each has a url that is a path on this site starting with one slash (up to 300 characters, no spaces), a status from 100 to 599 (default 200), and must and must_not, lists of up to 20 strings of 1 to 200 characters. The canary and verify read them. |
health | true or false. When true, the app's respira_app_health filter is one of the checks. The kit page shows its shape. |
tests | true, false or { "timeout": 1 to 60 } seconds per test (default 10). When on, the release must hold at least one tests/*.php. They run in the canary request. |
consent | An object with allow_hosts, allow_cookies and cmp_markers, each a list of up to 50 strings, for the consent check. Another key inside it is ignored with a warning. |
abilities | Up to 16 abilities other agents can run. Owner and abilities has the shape and the rules. |
emails | A list of kinds. Each has a kind (lowercase letters, digits, hyphens, underscores) and an audience of one (the default) or many. Optional: vars, languages, bulk_limit. A many kind needs the unsubscribe link in every template. |
i18n | { "default": "en", "languages": [...] }, and optionally "allow_missing": true. Strings live in i18n/<lang>.json. |
secrets | A list of { "name", "label", "required" }. A name is capital letters, digits and underscores, starts with a letter, 3 to 64 characters, with no double underscore. Up to 32 are read. A list of bare names is not read. |
personal_data | Up to 20 tables the app owns. See below. |
routes.endpoints
path: starts with/, up to 200 characters.methods: a list from GET, POST, PUT, PATCH, DELETE. The default is GET.auth: required.public,logged_in,nonceorcapability:<cap>.rate_limit: a whole number from 1 to 999999, a slash andmin,hourorday, for example5/hour. The lint refuses a route without one.public:trueor left out. When true,authmust bepublicandreasonmust say in 1 to 200 characters why anyone may call it. The handler must callrespira_app_rate_limit()before the first write.
personal_data
Each entry names a table the app owns and needs columns, a list of the personal columns. Optional: pk (default id), email_column (without it, erasure by address cannot find rows, so Respira warns), purpose, basis (consent, contract, legitimate_interest or legal_obligation), children and retention.
children belongs on the entry. Each child is { "table", "fk" }: a table the app owns and the column that points at the entry's key. Erasure and retention delete child rows first. A retention rule may carry a children list of its own, written { "table", "key" }, and when it does, that list replaces the entry's for that rule. Most apps never need it.
{
"manifest_version": 1,
"slug": "demo",
"version": "1.0.0",
"entry": "entry.php",
"tables": [ { "name": "demo_people" }, { "name": "demo_mail" } ],
"personal_data": [
{
"table": "demo_people",
"email_column": "email",
"columns": ["email"],
"basis": "consent",
"children": [ { "table": "demo_mail", "fk": "person_id" } ],
"retention": [
{ "table": "demo_people", "after": { "column": "created", "days": 30 }, "where": { "status": "unconfirmed" }, "chunk": 500 }
]
}
]
} The key that is accepted and not read
assets is accepted. Respira Code does not read it: the upload says so in a warning and the lint adds the notice manifest-assets-unused. Files in the assets/ folder are served as they are, with or without the key. Remove it.
Any other key the validator does not know is ignored with a warning, never an error.
How these samples were checked
The manifests on this page, and on the pages next to it, were run through the add-on's own validator and upload lint. 66 lint rules are on their own page.