The manifest

Where it comes from#

plugin.json sits at the archive root. It is validated in layers, and each layer produces a different kind of failure:

1. Structural parsing. Not valid JSON, missing a required field, a wrong type, an unknown top-level key, a kind other than data/process, an unknown or empty scopes list, a bad ingestRoots entry, or an i18n block that breaks the rules below all fail the same way: PLUGIN_BAD_MANIFEST, "plugin.json failed structural validation." No finer reason is given at this layer. The packaging tool runs the same check, so it catches these before you install.
2. Id and version. Checked separately, with a specific reason each: PLUGIN_BAD_ID or PLUGIN_BAD_VERSION.
3. UI and events shape. The ui.* and events blocks are checked field by field, each with its own reason (PLUGIN_BAD_UI_CONTRIBUTIONS, PLUGIN_BAD_UI_CONFIG_PAGES, and so on).
4. Registration-time semantics, once the archive has already been installed: pluginApi, the fliks range, route methods, paths and policies, jobs, permissions, webhooks, the release picker, contribution targets, the i18n namespace. A failure here does not undo the install; the plugin is written to disk with status: 'failed' and a statusReason naming exactly which rule it broke, so you can fix the manifest and reinstall.

Layers 1-3 run during inspect, before anything reaches the database (see Architecture). Layer 4 runs during register, right after confirm.

Base fields (both tiers)#

Process-only fields#

A data manifest may not carry any of these; a process manifest must carry all of them except where marked optional.

routes[]#

No two routes may share the same method and path (duplicate-route).

scopes[]#

Calling a host method without every scope it needs rejects with plugin "<id>" is missing scope "<scope>" required for "<method>". Declare every scope every method you call needs; there's no partial grant within one method.

jobs[]#

permissions[]#

Each entry must match ^[a-z][a-z0-9_-]{0,63}$ and be unique. Every distinct action:subject policy your routes[] declare under a given permission name becomes its own tick box in the roles editor (so read:plugin:<id>:queue can be granted separately from manage:plugin:<id>:queue); a declared name no route mentions is offered whole and grants every action once ticked. Nothing is granted by default: until an admin ticks a box, only admins pass the routes declared under it.

The i18n block#

"i18n": {
  "en": { "acme.settings.title": "Settings", "acme.settings.hint": "..." },
  "fr": { "acme.settings.title": "Paramètres", "acme.settings.hint": "..." }
}

• Every key must contain at least one dot; a bare "title" is refused.
• No key may be a dotted ancestor of another declared key (acme.config alongside acme.config.title is refused).
• Every key across every locale must share exactly one root segment (here, acme). It does not have to equal or derive from the plugin's own id.
• Breaking any of the three rules above refuses the archive with PLUGIN_BAD_MANIFEST.
• At registration, that root is claimed: a second plugin declaring the same root fails with i18n-namespace-conflict; whichever plugin loaded first keeps it.

Full validation error reference#

Any reason other than disabled, tampered, db-provision-failed, spawn-failed, incompatible-fliks or incompatible-api tears the plugin's routes, contributions, permissions and jobs down entirely; those six instead leave the plugin "installed but not running", so a request to one of its routes gets a 503 rather than acting as if the plugin never existed.

A worked example#

The scaffold's manifest in Your first plugin is the minimum that satisfies every process-tier rule above. For every field in real, production use at once, read Examples, which walks through fliks.download's full manifest field by field.

Proposing a new extension point#

Everything a plugin can reach, the host methods, the scopes, the UI slots, the routes a manifest may declare, is a closed set on purpose: a closed set is what makes a plugin's blast radius reviewable, and what lets core promise a plugin keeps working across a release. "Can my plugin do X?" has no answer an author can reach alone when X isn't already in one of those sets; that's a core change, proposed as an issue that says:

1. What the plugin is trying to do, as a user-visible outcome, not the API you imagined for it.
2. What you tried within the existing set, and where it stopped.
3. What core would have to trust you with: a new host method is a new scope, or a widening of one, say which, and what a hostile plugin holding it could do.
4. Whether it can be additive. pluginApi is a single integer, and within one value the contract only grows: a new method, scope or slot lands without changing it. Removing something, or changing an existing one's shape or meaning, bumps pluginApi; core keeps accepting the old value for a while (SUPPORTED_PLUGIN_API_VERSIONS), then drops it, which orphans every plugin that hasn't republished.