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

KeyRule
manifest_versionThe number 1.
slugMust 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.
versionLooks 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.
entryA .php file that is in the release. It is the file the loader includes.

Optional keys

KeyWhat it takes
name, descriptionAccepted and not validated. They describe the app to people.
requires_php, requires_wpA 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.
tablesUp 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.
optionsUp to 50 option names the app owns: lowercase letters, digits and underscores, up to 64 characters. A deploy snapshots them.
routesA namespace like my-app/v1 and up to 50 endpoints. See below.
admin_pagesUp 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.
cronUp 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).
contractsUp 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.
healthtrue or false. When true, the app's respira_app_health filter is one of the checks. The kit page shows its shape.
teststrue, 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.
consentAn 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.
abilitiesUp to 16 abilities other agents can run. Owner and abilities has the shape and the rules.
emailsA 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.
secretsA 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_dataUp 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, nonce or capability:<cap>.
  • rate_limit: a whole number from 1 to 999999, a slash and min, hour or day, for example 5/hour. The lint refuses a route without one.
  • public: true or left out. When true, auth must be public and reason must say in 1 to 200 characters why anyone may call it. The handler must call respira_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.