Plugin manifest reference
Complete signals.yaml reference — every section validated by ManifestValidator, exact failure messages, and worked example manifests including Ledger Sync.
Overview
Parsed into App\Sdk\Manifest\PluginManifest and validated by App\Sdk\Manifest\ManifestValidator. Rule keys below are the keys on ManifestValidationException::$errors.
Normalised sections: package, name, icon, version, signals_version, sdk, requires, conflicts, permissions, data_access, tables, hooks, slots, settings, network, operations, nav, pages, notifications, channel_drivers, events, tools, datatables, workflow_handlers, workflow_triggers, workflow_conditions, schedules, routes, connections, actions, integration_principal.
Cross-link: field allowlists → Data models; runtime enforcement → Data access.
Workflow declarations and their runtime lifecycle are covered in Workflow extensions and registries and resolvers.
Validate interactively: the Manifest validator & builder runs any pasted signals.yaml through this exact validator (and builds new manifests section by section), reporting failures under the rule keys below.
File / parse errors (before validator)
Validation messages: All validation rules.
Identity
| Field | Required |
|---|---|
package |
yes |
name |
yes |
version |
yes |
signals_version |
yes |
icon |
no |
Validation messages: All validation rules.
signals_version is constrained against the application version (1.0.0). sdk: "^2.0" declares the independent SDK major; prior-major constraints are rejected with upgrade guidance.
icon is the plugin's identity icon — a kebab-case flux/heroicon name (e.g. bolt, puzzle-piece). It is shown in the Plugin Manager and anywhere the plugin is referenced (dropdowns, titles), and serves as the fallback when nav.icon is omitted.
requires / conflicts
Maps of package => constraint. Same validation; rule keys differ. Each map holds at most 100 entries, and each package name is at most 200 characters.
Validation messages: All validation rules.
requires:
acme/helper: "^1.0"
conflicts:
example/accounting-adapter: "*"
permissions
List of resource.action strings. Every key must be prefixed with {vendor}. where vendor is the first Composer segment of package (e.g. signals/ledger-sync → signals.).
Pattern: /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/
Validation messages: All validation rules.
Wiring via $registrar->permission($key, …) is gated: key must appear here.
data_access
Per-entity allowlist for PluginContext::read(), list() and update(). Allowed declaration operations: read, list, write, delete; delete is reserved: the validator accepts it, but it grants nothing because there is no SDK delete method. list requires read and a non-empty readable field list. Declare permitted filter fields in filters[]; each must be allowed by the entity map. See Runtime for filter operators, cursor options, user visibility and auditing.
Validation messages: All validation rules.
Field list resolution (ManifestDataAccess::fieldsFor):
- When
read_fieldsis present (non-null) it fully defines the read allowlist. - When
write_fieldsis present it fully defines the write allowlist. - Otherwise
fields[]applies for that operation.
Custom-field declaration matching (enforced at runtime by PluginDataAccess, not the YAML field-name grammar):
- Nested custom fields are written under attribute key
custom_fields(flat map). - Nested key
xis allowed when the effective list declarescustom_fields(wholesale) orcustom_fields.x. - Any undeclared top-level or nested key rejects the whole update.
Known entities: accounts, rentals, invoices, credit_notes, payments, purchase_orders, vehicles, catalogue_items, assets, activities, warehouses, users, custom_field_definitions. See Data models.
tables
Validation messages: All validation rules.
Pattern: /^plugin_[a-z][a-z0-9_]*$/
hooks
Validation messages: All validation rules.
Fields: name, type (e.g. event, filter), optional priority (runtime default 50). The validator enum-checks type with HookType::tryFrom: event, filter, validator or decorator. A malformed hook reports "hooks[i] requires a non-empty string name and a supported string type."
slots
Validation messages: All validation rules.
Optional: priority, permission.
settings
Allowed types: string, integer, boolean, enum, json.
Validation messages: All validation rules.
Accepted on the DTO but not validated by ManifestValidator: encrypted, default (applied when context settings are read).
Storage group: plugin_ + package with / and - → _ (e.g. signals/ledger-sync → plugin_signals_ledger_sync). See Plugin settings.
network
Bare hostnames only — no wildcards, schemes, paths, or ports.
Validation messages: All validation rules.
operations
Names for PluginContext::operation(). Format resource.action.
Validation messages: All validation rules.
Must also be mapped in PluginOperationRegistry. Seeded today: activities.create, activities.complete, favourites.toggle, rentals.change_status, rentals.allocate_assets, documents.generate, payments.record_external, payments.refund_external, payments.reverse_external, credit_notes.allocate_external, purchase_orders.mark_billed_external, purchase_orders.unmark_billed_external. See Plugin Operation Registry.
nav
Top-level nav group (one per plugin) shown in the app header after Finance, with a matching group sidebar on the plugin's UI pages. Items reference declared pages[] keys and are wired at runtime via PluginRegistrar::navGroup().
nav:
group: Field Ops # header group label
icon: map # kebab-case flux icon name
items:
- key: jobs # slug, unique within the plugin
label: Jobs
page: jobs # references pages[].key
permission: acme.fieldops.view # optional; gates header item, sidebar item, and page
icon: briefcase # optional; falls back to the group icon
Validation messages: All validation rules.
pages
Page section types: stat-grid, table, html, datatable, form, actions, connections, map.
Config-driven UI pages rendered by core components only — no plugin views. Each page renders at /plugins/{vendor}/{name}/{key} (the Composer package split into two path segments). Section data is supplied at runtime by PluginRegistrar::page($key, $dataProvider).
pages:
- key: jobs
title: Jobs
description: Field jobs overview
layout: console # only 'console' in v1
sections:
- type: stat-grid # rows of core stat cards
- type: table # columns + rows, values escaped
- type: html # trusted HTML string (same trust model as Html slots)
- type: datatable # a declared datatables[] key, rendered by the shared DataTable
datatable: acme.fieldops.jobs
Validation messages: All validation rules.
A datatable section takes no data from the page's provider — the registered definition is its content. It is skipped for a viewer without the definition's permission, so sibling sections keep rendering.
See Plugin UI for the runtime wiring and section data shapes.
datatables
Listing tables the plugin may register with PluginRegistrar::datatable(). Keys are global — page sections and slots reference a table by key alone — so they must be dotted and vendor-prefixed exactly like permissions. See DataTable SDK and Plugin Data Table Registry.
datatables:
- key: acme.fieldops.jobs
permission: acme.fieldops.view # optional here, mandatory on the definition
description: Open field jobs.
Validation messages: All validation rules.
The declaration is the gate: datatable() refuses a key that is not listed here, and when permission is declared the registered definition must gate on exactly that permission. A permission is mandatory on the definition in every case.
notifications
Types the plugin may send via PluginContext::notify(). Keys must be vendor-prefixed like permissions. Channels (when present) are a non-empty subset of core channels (database, mail, broadcast) or logical channels supplied by an installed plugin. Cross-plugin availability is checked at activation.
notifications:
- key: acme.sync.failed
label: Sync Failed
group: Acme
channels: [database, mail, notify]
description: Fired when a sync fails.
Validation messages: All validation rules.
Wiring via $registrar->notification($key, …) is gated: key must appear here. See Plugin UI.
channel_drivers
Notification channel drivers the plugin may register via $registrar->channelDriver($key, $class). Keys must be vendor-prefixed like permissions. Guide: Plugin channel providers.
channel_drivers:
- key: acme.example_channel
channel: notify
label: AcmeNotify Incoming Webhook
config_fields:
- webhook_url
- default_channel
Validation messages: All validation rules.
Wiring via $registrar->channelDriver($key, …) is gated: key must appear here.
tools
Optional MCP / CLI tools. Names must be vendor-prefixed like permissions. Wired at runtime via PluginRegistrar::tool(). See Plugin MCP / CLI tools and Plugin Tool Registry.
Validation messages: All validation rules.
events
Plugin-owned EventRegistry names for event() / webhookEvent() / PluginContext::emit(). Names must be vendor-prefixed (e.g. acme.sync.completed).
events:
- name: acme.sync.completed
label: Sync Completed
webhook: true
workflow: true
Validation messages: All validation rules.
Wiring via $registrar->event($name, …) / webhookEvent($name) is gated: name must appear here; webhook and workflow visibility also require the matching webhook: true or workflow: true declaration. Event names cannot shadow core or already-registered names. See Plugin events.
Workflow extension declarations
Workflow extension identifiers use the plugin vendor namespace and are checked for collisions and complete declarations before registration. The three declaration lists have these contracts:
| Section | Required contract fields |
|---|---|
workflow_handlers |
id, class, version, contract_version, capabilities, retry, outcomes, input_schema, configuration_schema; output_schema and sensitive_fields are supported |
workflow_triggers |
id, class, version, contract_version, capabilities, input_schema, output_schema, sensitive_fields |
workflow_conditions |
id, class, version, contract_version, capabilities, context, sanitized, side_effect_free, queries, mutations, input_schema, output_schema |
Handler retry declarations are internally consistent: automatic retry requires an idempotent handler that is safe for automatic retry. Conditions must be sanitized and side-effect-free, declare only the allowlisted workflow context paths, and cannot declare query or mutation capabilities. These rules protect the workflow runtime; they are not a general data-access allowlist.
workflow_handlers:
- id: acme.dispatch.driver
class: Acme\\Signals\\Workflow\\DispatchDriver
version: 1.0.0
contract_version: 1.0.0
capabilities: [external.http]
retry:
idempotent: true
automatic_retry: true
automatic_retry_safe: true
outcomes: [continue_with_output, failure]
input_schema: {}
configuration_schema: {}
The complete runtime lifecycle, health states, and registration entry points are in Workflow extensions.
Example A — minimal valid
package: acme/hello
name: Acme Hello
version: 1.0.0
signals_version: "^1.0"
permissions:
- acme.hello.view
slots:
- slot: dashboard.widgets
component: signals.stat-card
priority: 90
permission: acme.hello.view
settings:
- key: greeting
type: string
label: Greeting
default: Hello
network: []
Example B — Ledger Sync (annotated)
Example source after separate Composer installation: vendor/signals/ledger-sync/signals.yaml.
package: signals/ledger-sync # identity.package — Composer name
name: Ledger Sync
version: 1.0.0 # SemVer
signals_version: "^1.0" # application version support, independent of sdk: "^2.0"
permissions: # vendor prefix signals.
- signals.ledger.sync
- signals.ledger.view
data_access:
- entity: accounts
read_fields: # asymmetric read allowlist
- name
- email # virtual field (primary email sync)
- custom_fields.ledger_contact_id
write_fields: # write only the Ledger id CF
- custom_fields.ledger_contact_id
operations:
- read
- write
- entity: invoices
read_fields:
- number
- total
- currency_code
- account_id
- custom_fields.ledger_invoice_id
write_fields:
- custom_fields.ledger_invoice_id
operations:
- read
- write
operations: [] # no PluginContext::operation() names
tables:
- plugin_ledger_sync_log # must match migration-created table
hooks:
- name: invoice.issued # EventRegistry + AuditableEvent
type: event
priority: 50
- name: account.updated
type: event
priority: 50
slots:
- slot: dashboard.widgets
component: signals.stat-card # core Blade component
priority: 70
permission: signals.ledger.view
settings:
- key: client_id
type: string
label: Ledger Client ID
rules: [nullable, string, max:255]
- key: client_secret
type: string
label: Ledger Client Secret
encrypted: true # leave-blank-to-keep on save
- key: tenant_id
type: string
label: Ledger Tenant ID
rules: [nullable, string, max:255]
- key: sync_direction
type: enum
label: Sync Direction
options: [push, pull, both]
default: push
network: # exact hosts for PluginHttpClient
- api.ledger.example
- identity.ledger.example
Example C — recipes
UI-only plugin
package: acme/dashboard-tip
name: Dashboard Tip
version: 1.0.0
signals_version: "^1.0"
permissions:
- acme.dashboard_tip.view
slots:
- slot: dashboard.widgets
component: signals.stat-card
permission: acme.dashboard_tip.view
settings:
- key: tip_text
type: string
label: Tip text
default: Remember to confirm returns
network: []
Data-sync plugin
package: acme/crm-push
name: CRM Push
version: 1.0.0
signals_version: "^1.0"
permissions:
- acme.crm_push.sync
data_access:
- entity: accounts
read_fields: [name, email, custom_fields.external_id]
write_fields: [custom_fields.external_id]
operations: [read, write]
hooks:
- name: account.updated
type: event
priority: 50
network:
- api.partner.example
settings:
- key: api_token
type: string
label: API token
encrypted: true
Import/export extension plugin
Import/export registrar seams (importableModel, exportableModel, importTransform, planTemplate) are available without a manifest section. See Import/export plugins for their contracts. Declare data_access and hooks when the integration also reads or updates core records.
schedules
Each entry has a unique local slug key, optional description, and exactly one of cron (a five-field expression) or frequency (everyMinute, everyFiveMinutes, everyFifteenMinutes, everyThirtyMinutes, hourly, daily, weekly). Register its handler with $registrar->schedule($key, $handler). See Jobs and schedules for a complete declaration and execution rules.
Malformed declaration types produce {section}.malformed diagnostics before hydration; unknown fields produce {section}.unknown_fields. Use ManifestValidationException::issues() or check --json for every {rule, path, message} issue, including repeated failures under one rule. The generated table below includes section shape rules and notification template messages.
Validation messages: All validation rules.
Machine-readable specification (JSON Schema)
The repository includes an internal versioned JSON Schema for structural checks in development tooling. JSON Schema is useful for structural checks, but it cannot replace authoritative validation. Cross-field checks include the package-derived vendor prefix, entity field/filter allowlists and declaration references; registration also enforces wiring ⊆ declaration.
php artisan signals:plugin check {package} runs the authoritative validator
and reports failures using the same rule keys the schema documents.
For the authoritative validator over HTTP — no checkout required — POST /docs/tools/manifest-validate with {"yaml": "..."} (public, rate-limited;
response {valid, errors, issues, parse_error?}; invalid manifests return 200, never 500; YAML parse errors return 422, input over 64 KB returns 413, and rate limiting returns 429. Details in the LLM guide),
or use the interactive Manifest validator & builder.
All validation rules
| Rule | Section | Message template |
|---|---|---|
actions.fields |
actions |
Action fields require unique names, supported types, safe rules, declared options, readable searchable records and declared connections. |
actions.key_unique |
actions |
Action keys must be unique. |
actions.malformed |
actions |
Actions require a label and complete confirmation labels. / Action record must name a supported record type or entity. / {path} must be {expected}; got {actual}. |
actions.namespace |
actions |
Action keys must use the package vendor prefix and dotted resource.name format. |
actions.permission |
actions |
Action permission must be declared by the plugin or registered by core. |
actions.slots |
actions |
Action slots must be known detail header actions matching the record type. |
actions.unknown_fields |
actions |
{path} contains unknown declaration field(s): {fields}. |
channel_drivers.config_fields |
channel_drivers |
Config fields require a supported type; select requires options and extends_network requires url. |
channel_drivers.identity_collision |
channel_drivers |
Plugin [{package}] declarations [{identifiers}] collide with installed plugin [{installed}]. |
channel_drivers.key_unique |
channel_drivers |
channel_drivers[{index}] key [{key}] is declared more than once; driver keys must be unique. |
channel_drivers.malformed |
channel_drivers |
channel_drivers[{index}] requires non-empty key, channel, and label. / channel_drivers[{index}] channel [{channel}] must be a lowercase slug (e.g. notify, messenger). / channel_drivers[{index}] channel [{channel}] collides with a core notification channel. / channel_drivers[{index}] config_fields must be a non-empty list when present. / channel_drivers[{index}] config_fields must be a list of non-empty strings. / {path} must be {expected}; got {actual}. |
channel_drivers.namespace |
channel_drivers |
Channel driver [{key}] must be namespaced with vendor prefix [{prefix}]. / Channel driver [{key}] must use resource.action format under the vendor prefix. |
channel_drivers.unknown_fields |
channel_drivers |
{path} contains unknown declaration field(s): {fields}. |
conflicts.constraint |
conflicts |
{value} / Dependency package [{package}] must be a Composer name in vendor/name format. / Dependency constraint [{constraint}] for [{package}] is not well-formed. |
conflicts.malformed |
conflicts |
{path} must be {expected}; got {actual}. |
connections.endpoints |
connections |
Connection endpoints require HTTPS, declared exact hosts or a network URL field, declared placeholders, and no userinfo or fragment. |
connections.fields |
connections |
Connection fields require unique names, supported types, select options and URL-only network grants. / OAuth client fields must name declared connection fields. / Connection secret and extends_network flags must be booleans. |
connections.key_unique |
connections |
Connection keys must be unique. |
connections.malformed |
connections |
Connections require valid key, label, scope and authentication; OAuth configuration must match its grant. / Organisation selection must be required or optional. / Connections require explicit key, label, scope and auth. / {path} must be {expected}; got {actual}. |
connections.namespace |
connections |
Connection keys must use the package vendor prefix and dotted resource.name format. |
connections.permission |
connections |
Connection permission must be declared by the plugin or registered by core. |
connections.unknown_fields |
connections |
{path} contains unknown declaration field(s): {fields}. |
data_access.fields |
data_access |
data_access[{index}] has no field list for [{operation}]; declare fields[] or {operation}_fields. |
data_access.filters |
data_access |
data_access[{index}] filter [{filter}] is not allowed for [{entity}]. |
data_access.list_requires_read |
data_access |
data_access[{index}] list access requires the read operation and a non-empty readable field list. |
data_access.malformed |
data_access |
data_access[{index}] is missing a non-empty entity. / data_access[{index}] must declare at least one operation. / data_access[{index}] operation [{operation}] is invalid; allowed: {allowed}. / data_access[{index}] entity [{entity}] is read-only. / {path} must be {expected}; got {actual}. |
data_access.read_fields |
data_access |
data_access[{index}].read_fields must be a non-empty list when present. |
data_access.readable |
data_access |
data_access[{index}] field [{field}] is outside the readable allowlist for [{entity}]. |
data_access.unknown_fields |
data_access |
{path} contains unknown declaration field(s): {fields}. |
data_access.write_fields |
data_access |
data_access[{index}].write_fields must be a non-empty list when present. |
datatables.identity_collision |
datatables |
Plugin [{package}] declarations [{identifiers}] collide with installed plugin [{installed}]. |
datatables.key_unique |
datatables |
datatables[{index}] key [{key}] is declared more than once; datatable keys must be unique. |
datatables.malformed |
datatables |
datatables[{index}] key [{key}] must use dotted resource.name format (e.g. acme.jobs.table). / datatables[{index}] key [{key}] must be namespaced with vendor prefix [{prefix}]. / datatables[{index}] permission must be a non-empty permission key when declared. / {path} must be {expected}; got {actual}. |
datatables.permission |
datatables |
datatables[{index}] permission [{permission}] must be a declared plugin permission or a registered core permission. |
datatables.unknown_fields |
datatables |
{path} contains unknown declaration field(s): {fields}. |
events.identity_collision |
events |
Plugin [{package}] declarations [{identifiers}] collide with installed plugin [{installed}]. |
events.malformed |
events |
events[{index}] requires a non-empty name. / {path} must be {expected}; got {actual}. |
events.name_unique |
events |
Declarations must be unique; repeated identity: {duplicates}. |
events.namespace |
events |
Event [{name}] must be namespaced with vendor prefix [{prefix}]. / Event [{name}] must use dotted resource.action format under the vendor prefix (e.g. acme.sync.completed). |
events.unknown_fields |
events |
{path} contains unknown declaration field(s): {fields}. |
hooks.malformed |
hooks |
hooks[{index}] requires non-empty name and type. / hooks[{index}] type [{type}] is invalid; allowed: {allowed}. / Hooks must be a list of declarations. / hooks[{index}] requires a non-empty string name and a supported string type. / {path} must be {expected}; got {actual}. |
hooks.unknown_fields |
hooks |
{path} contains unknown declaration field(s): {fields}. |
icon.malformed |
icon |
{path} must be {expected}; got {actual}. |
identity.icon.format |
identity |
icon [{icon}] must be a kebab-case flux icon name (e.g. bolt, puzzle-piece). |
identity.package.format |
identity |
Package [{package}] must be a Composer name in vendor/name format. |
identity.required |
identity |
Manifest identity is missing required field(s): {missing}. |
identity.signals_version.constraint |
identity |
signals_version [{signals_version}] is not a well-formed version constraint. |
identity.version.semver |
identity |
Version [{version}] must be a valid semantic version (e.g. 1.2.0). |
integration_principal.fields |
integration_principal |
Principal field grants must be lists contained in declared readable entity fields. / Principal field grants must be lists of field names. |
integration_principal.malformed |
integration_principal |
Integration principals require a label, a reason and warehouses: grant. / {path} must be {expected}; got {actual}. |
integration_principal.permissions |
integration_principal |
Integration permissions must be declared or registered and cannot include administration, security, privacy or impersonation abilities. |
integration_principal.unknown_fields |
integration_principal |
{path} contains unknown declaration field(s): {fields}. |
manifest.file |
manifest |
Manifest file not found: {path} / Manifest file could not be read: {path} |
manifest.malformed |
manifest |
Manifest declarations could not be hydrated; check their field types. |
manifest.parse |
manifest |
Manifest YAML could not be parsed: {getMessage} / Manifest YAML must parse to a mapping. |
manifest.unknown_fields |
manifest |
{path} contains unknown declaration field(s): {fields}. |
name.malformed |
name |
{path} must be {expected}; got {actual}. |
nav.items |
nav |
nav.items[{index}] key [{key}] must be a lowercase slug. / nav.items[{index}] requires a non-empty label. / nav.items[{index}] key [{key}] is declared more than once; item keys must be unique. / nav.items[{index}] icon [{icon}] must be a kebab-case flux icon name. |
nav.malformed |
nav |
nav requires a non-empty group label. / nav icon is required unless a top-level plugin icon is declared as the fallback. / nav icon [{icon}] must be a kebab-case flux icon name (e.g. map, puzzle-piece). / nav must declare at least one item. / {path} must be {expected}; got {actual}. |
nav.page_ref |
nav |
nav.items[{index}] page [{page}] does not reference a declared pages[] key. |
nav.unknown_fields |
nav |
{path} contains unknown declaration field(s): {fields}. |
network.malformed |
network |
{path} must be {expected}; got {actual}. |
network.wildcard |
network |
Network allowlist entries must be concrete hostnames. / Network allowlist entry [{host}] must not contain wildcards; declare a concrete host. / Network allowlist entry [{host}] must be a bare hostname (no scheme, path, or port). / Network allowlist entry [{host}] is not a valid hostname. |
notifications.channel_unavailable |
notifications |
Install a provider for channel [{channel}] before enabling this plugin. |
notifications.identity_collision |
notifications |
Plugin [{package}] declarations [{identifiers}] collide with installed plugin [{installed}]. |
notifications.malformed |
notifications |
notifications[{index}] requires non-empty key and label. / notifications[{index}] channels must be a non-empty subset of core channels (database, mail, broadcast) or channels declared in channel_drivers[] when present. / notifications[{index}] channel [{channel}] must be a channel slug. / {path} must be {expected}; got {actual}. |
notifications.namespace |
notifications |
Notification [{key}] must be namespaced with vendor prefix [{prefix}]. / Notification [{key}] must use resource.action format under the vendor prefix. |
notifications.templates.attachments |
notifications |
notifications[{index}].templates[{templateIndex}] attachments must be a list of non-empty document-template slug strings (not IDs). / {path} attachments must be a list of non-empty document-template slug strings (not IDs). |
notifications.templates.blade |
notifications |
notifications[{index}].templates[{templateIndex}] must not contain Blade syntax (@directives, {!! !!}, or <?php); use Markdown with {{ merge }} fields only. / notifications[{index}].templates[{templateIndex}] chrome fields must not contain Blade syntax. |
notifications.templates.channel |
notifications |
notifications[{index}].templates[{templateIndex}] channel [{channel}] must be a channel slug. |
notifications.templates.malformed |
notifications |
Template output_type must be text or json; structured templates require valid JSON. / notifications[{index}].templates[{templateIndex}] requires non-empty subject and body. |
notifications.templates.merge_fields |
notifications |
notifications[{index}].templates[{templateIndex}].{fieldName} uses undeclared merge field [{path}]; declare it in data_schema or use an ambient company/user path. |
notifications.templates.parent |
notifications |
notifications[{index}] templates require a declared notification key in the same manifest. |
notifications.unique |
notifications |
Declarations must be unique; repeated identity: {duplicates}. |
notifications.unknown_fields |
notifications |
{path} contains unknown declaration field(s): {fields}. |
operations.malformed |
operations |
operations[{index}] must be a non-empty operation name string. / operations[{index}] [{operation}] must use resource.action format (e.g. activities.complete). / {path} must be {expected}; got {actual}. |
package.malformed |
package |
{path} must be {expected}; got {actual}. |
pages.key_unique |
pages |
pages[{index}] key [{key}] is declared more than once; page keys must be unique. |
pages.malformed |
pages |
pages[{index}] key [{key}] must be a lowercase slug (e.g. jobs, sync-status). / pages[{index}] requires a non-empty title. / pages[{index}] layout [{layout}] is invalid; allowed: {allowed}. / {path} must be {expected}; got {actual}. |
pages.sections |
pages |
pages[{index}] must declare at least one section. / Section keys must be unique lowercase slugs. / Refreshing sections require a key and an interval from 15 to 3600 seconds. / Form and action sections must reference declared actions. / pages[{index}].sections[{sectionIndex}] type [{type}] is invalid; allowed: {allowed}. / Connection sections must reference a declared connection. / pages[{index}].sections[{sectionIndex}] of type [datatable] must name a declared datatables[] key. / pages[{index}].sections[{sectionIndex}] references undeclared datatable [{datatable}]. |
pages.unknown_fields |
pages |
{path} contains unknown declaration field(s): {fields}. |
permissions.identity_collision |
permissions |
Plugin declarations [{corePermissions}] collide with first-party core permissions. / Plugin [{package}] declarations [{identifiers}] collide with installed plugin [{installed}]. |
permissions.malformed |
permissions |
{path} must be {expected}; got {actual}. |
permissions.namespace |
permissions |
Permission entries must be non-empty resource.action strings. / Permission [{permission}] must be namespaced with vendor prefix [{prefix}]. / Permission [{permission}] must use resource.action format under the vendor prefix. |
permissions.unique |
permissions |
Declarations must be unique; repeated identity: {duplicates}. |
requirements.conflicts |
requirements |
Plugin [{package}] conflicts with active plugin [{package}] version [{installedVersion}] matching [{constraint}]. / Plugin [{package}] conflicts with active plugin [{package}] version [{activeVersion}] matching [{constraint}]. / Active plugin [{package}] conflicts with plugin [{package}] version [{version}] matching [{constraint}]. |
requirements.host |
requirements |
Plugin [{package}] requires host version [{signals_version}], but [{hostVersion}] is installed. |
requirements.requires |
requirements |
Plugin [{package}] requires plugin [{package}] matching [{constraint}], but it is not installed. / Plugin [{package}] requires plugin [{package}] matching [{constraint}], but version [{installedVersion}] is installed. |
requirements.requires_active |
requirements |
Plugin [{package}] requires installed plugin(s) to be enabled: {inactive}. |
requirements.requires_cycle |
requirements |
Plugin dependency cycle: {cycle}. |
requirements.reverse_dependencies |
requirements |
Plugin [{package}] is required by enabled plugin(s): {dependants}. / Plugin [{package}] version [{candidateVersion}] is incompatible with enabled dependant(s): {incompatible}. |
requirements.sdk |
requirements |
SDK 2.1 sections [{list}] require sdk: ^2.1. / SDK 2.2 operations [{list}] require sdk: ^2.2. / Channel drivers require an explicit sdk constraint. Upgrade to SDK v2 and declare sdk: ^2.0. / Upgrade this plugin to SDK v2: send() must return ChannelSendResult and addressField() is required. |
requires.constraint |
requires |
{value} / Dependency package [{package}] must be a Composer name in vendor/name format. / Dependency constraint [{constraint}] for [{package}] is not well-formed. |
requires.malformed |
requires |
{path} must be {expected}; got {actual}. |
routes.malformed |
routes |
Routes require a unique method/path, explicit api (with ability), public or verifier:name authentication, and rate_limit between 1 and 6000. / {path} must be {expected}; got {actual}. |
routes.unknown_fields |
routes |
{path} contains unknown declaration field(s): {fields}. |
schedules.cron |
schedules |
schedules[{index}] must declare exactly one valid five-field cron expression or supported frequency. |
schedules.key_unique |
schedules |
Declarations must be unique; repeated identity: {duplicates}. |
schedules.malformed |
schedules |
schedules[{index}] key must be a non-empty slug. / {path} must be {expected}; got {actual}. |
schedules.unknown_fields |
schedules |
{path} contains unknown declaration field(s): {fields}. |
sdk.malformed |
sdk |
{path} must be {expected}; got {actual}. |
settings.key_unique |
settings |
Declarations must be unique; repeated identity: {duplicates}. |
settings.malformed |
settings |
settings[{index}] requires non-empty key, type, and label. / settings[{index}] type [{type}] is invalid; allowed: {allowed}. / settings[{index}] of type enum requires a non-empty options list. / settings[{index}] rules must be a list of non-empty strings. / {path} must be {expected}; got {actual}. |
settings.storage_collision |
settings |
Plugin [{package}] settings storage collides with installed plugin [{installed}]. |
settings.unknown_fields |
settings |
{path} contains unknown declaration field(s): {fields}. |
signals_version.malformed |
signals_version |
{path} must be {expected}; got {actual}. |
slots.declaration_unique |
slots |
Declarations must be unique; repeated identity: {duplicates}. |
slots.malformed |
slots |
slots[{index}] requires non-empty slot and component. / {path} must be {expected}; got {actual}. |
slots.unknown_fields |
slots |
{path} contains unknown declaration field(s): {fields}. |
tables.identity_collision |
tables |
Plugin [{package}] declarations [{identifiers}] collide with installed plugin [{installed}]. |
tables.malformed |
tables |
{path} must be {expected}; got {actual}. |
tables.prefix |
tables |
Table [{table}] must start with plugin_ and use snake_case (e.g. plugin_acme_log). |
tables.unique |
tables |
Declarations must be unique; repeated identity: {duplicates}. |
tools.action |
tools |
tools[{index}] action [{action}] must be a fully-qualified class name (e.g. Vendor\Plugin\Actions\EchoTool). |
tools.args |
tools |
tools[{index}].args[{argIndex}] requires non-empty name and type. / tools[{index}].args[{argIndex}] type [{type}] is invalid; allowed: {allowed}. |
tools.malformed |
tools |
tools[{index}] requires non-empty name, title, action, and permission. / {path} must be {expected}; got {actual}. |
tools.name_unique |
tools |
tools[{index}] name [{name}] is declared more than once; tool names must be unique. |
tools.namespace |
tools |
Tool [{name}] must be namespaced with vendor prefix [{prefix}]. / Tool [{name}] must use resource.action format under the vendor prefix. |
tools.permission |
tools |
tools[{index}] permission [{permission}] must be a declared plugin permission or a registered core permission. |
tools.surfaces |
tools |
tools[{index}] surfaces must be a non-empty subset of mcp, cli when present. / tools[{index}] surface [{surface}] is invalid; allowed: {allowed}. |
tools.unknown_fields |
tools |
{path} contains unknown declaration field(s): {fields}. |
version.malformed |
version |
{path} must be {expected}; got {actual}. |
workflow_conditions.capabilities |
workflow_conditions |
workflow_conditions[{index}] capabilities must be a list of non-empty strings. / workflow_conditions[{index}] capabilities must contain only non-empty strings. |
workflow_conditions.class |
workflow_conditions |
workflow_conditions[{index}] class [{class}] must be a fully-qualified class name; it is recorded only and is never resolved during manifest validation. |
workflow_conditions.context |
workflow_conditions |
workflow_conditions[{index}] context path [{path}] must use a sanitized workflow context namespace (trigger, subject, originator, workflow, steps, or vars). / workflow_conditions[{index}] context must be a list of non-empty strings. / workflow_conditions[{index}] context must contain only non-empty strings. |
workflow_conditions.contract_version |
workflow_conditions |
workflow_conditions[{index}] contract_version must be a positive integer or non-blank string. |
workflow_conditions.identity |
workflow_conditions |
workflow_conditions[{index}] id [{id}] must use the plugin vendor prefix [{prefix}] and dotted resource.action format. |
workflow_conditions.malformed |
workflow_conditions |
workflow_conditions[{index}] requires non-empty id and class. / {path} must be {expected}; got {actual}. |
workflow_conditions.no_live_access |
workflow_conditions |
workflow_conditions[{index}] capability [{capability}] implies live data access; conditions may only use side-effect-free helpers and sanitized context. / workflow_conditions[{index}] cannot declare live queries or mutations; use an explicit action handler instead. |
workflow_conditions.sanitized |
workflow_conditions |
workflow_conditions[{index}] must declare sanitized: true for the constrained workflow context. |
workflow_conditions.side_effect_free |
workflow_conditions |
workflow_conditions[{index}] must declare side_effect_free: true. |
workflow_conditions.unknown_fields |
workflow_conditions |
{path} contains unknown declaration field(s): {fields}. |
workflow_conditions.version |
workflow_conditions |
workflow_conditions[{index}] version must be a positive integer or non-blank string. |
workflow_extensions.identity_collision |
workflow_extensions |
Plugin [{package}] extension [{id}] collides with a reserved first-party or installed plugin identity. |
workflow_extensions.identity_unique |
workflow_extensions |
{section}[{index}] id [{id}] is already declared by {value}; workflow extension identities must be unique across handlers, triggers, and conditions. |
workflow_handlers.capabilities |
workflow_handlers |
workflow_handlers[{index}] capabilities must be a list of non-empty strings. / workflow_handlers[{index}] capabilities must contain only non-empty strings. |
workflow_handlers.class |
workflow_handlers |
workflow_handlers[{index}] class [{class}] must be a fully-qualified class name; it is recorded only and is never resolved during manifest validation. |
workflow_handlers.contract_version |
workflow_handlers |
workflow_handlers[{index}] contract_version must be a positive integer or non-blank string. |
workflow_handlers.identity |
workflow_handlers |
workflow_handlers[{index}] id [{id}] must use the plugin vendor prefix [{prefix}] and dotted resource.action format. |
workflow_handlers.malformed |
workflow_handlers |
workflow_handlers[{index}] requires non-empty id and class. / {path} must be {expected}; got {actual}. |
workflow_handlers.outcomes |
workflow_handlers |
workflow_handlers[{index}] outcomes must be a non-empty list of typed outcomes. / workflow_handlers[{index}].outcomes[{outcomeIndex}] must define a non-blank string type. |
workflow_handlers.retry |
workflow_handlers |
workflow_handlers[{index}] retry must define boolean [idempotent], [automatic_retry], and [automatic_retry_safe] values. / workflow_handlers[{index}] automatic_retry requires an idempotent handler. / workflow_handlers[{index}] automatic_retry requires automatic_retry_safe: true. |
workflow_handlers.sensitive_fields |
workflow_handlers |
workflow_handlers[{index}] sensitive_fields must be a list of non-empty strings. / workflow_handlers[{index}] sensitive_fields must contain only non-empty strings. |
workflow_handlers.unknown_fields |
workflow_handlers |
{path} contains unknown declaration field(s): {fields}. |
workflow_handlers.version |
workflow_handlers |
workflow_handlers[{index}] version must be a positive integer or non-blank string. |
workflow_triggers.capabilities |
workflow_triggers |
workflow_triggers[{index}] capabilities must be a list of non-empty strings. / workflow_triggers[{index}] capabilities must contain only non-empty strings. |
workflow_triggers.class |
workflow_triggers |
workflow_triggers[{index}] class [{class}] must be a fully-qualified class name; it is recorded only and is never resolved during manifest validation. |
workflow_triggers.contract_version |
workflow_triggers |
workflow_triggers[{index}] contract_version must be a positive integer or non-blank string. |
workflow_triggers.identity |
workflow_triggers |
workflow_triggers[{index}] id [{id}] must use the plugin vendor prefix [{prefix}] and dotted resource.action format. |
workflow_triggers.malformed |
workflow_triggers |
workflow_triggers[{index}] requires non-empty id and class. / {path} must be {expected}; got {actual}. |
workflow_triggers.sensitive_fields |
workflow_triggers |
workflow_triggers[{index}] sensitive_fields must be a list of non-empty strings. / workflow_triggers[{index}] sensitive_fields must contain only non-empty strings. |
workflow_triggers.unknown_fields |
workflow_triggers |
{path} contains unknown declaration field(s): {fields}. |
workflow_triggers.version |
workflow_triggers |
workflow_triggers[{index}] version must be a positive integer or non-blank string. |
SDK v2 channel extensions
config_fields accepts field-name strings or objects with name, type, required, secret, options, help, placeholder, default, rules and extends_network. Network extension is valid only for a URL field, and applies only to the saved provider's exact host. Runtime ChannelConfigFieldData supplies the editable schema and save-time rules.
Notification template channel is a logical slug; output_type: text|json identifies structured payloads. JSON merge fields belong inside string values. Provider limits and segmentation remain the driver's responsibility.
routes is a list of {path, method, auth, ability?, rate_limit?} objects. Methods are GET, POST, PUT, PATCH or DELETE. Routes mount under /api/v1/plugins/{vendor}/{name}/{path} and require an enabled plugin. Complete declarations for each auth mode:
routes:
- path: status
method: GET
auth: public
rate_limit: 10
- path: sync
method: POST
auth: api
ability: plugins:write
rate_limit: 60
- path: callback
method: POST
auth: verifier:callback
rate_limit: 600
ability is required for api authentication and checked against the active user's token. Public routes are visibly flagged and fixed at ten requests per IP/minute; API routes are fixed at sixty. Only verified routes use the configurable rate_limit (1–6000, default 600) after successful verification, per provider and route. Register the verifier and all handlers as shown in Plugin inbound requests. OAuth installation/personal callbacks are host-owned and need no public plugin route.
See Plugin Channel Providers for generic verifiers, identity linking, encrypted OAuth token storage, the SDK v2 migration and the three Acme Notify pattern fixtures.
Connections (SDK 2.1)
connections[] declares vendor-prefixed keys, labels, installation or user scope, a management permission, authentication kind and fields. OAuth connections additionally declare endpoints, credential fields, scopes and optional organisation discovery. Multiple connections require installation scope. Endpoints must use declared HTTPS hosts or a URL field marked extends_network. See Plugin Connections for a complete descriptor and the core management flow.
Action declarations
SDK 2.1 actions[] declares permission-gated handlers, safe fields and optional record header placements. Pages use form and actions sections. See Actions and forms.
SDK 2.2 correction and billing-marker operations require sdk: ^2.2 (a constraint that accepts the host and excludes 2.1.1). Older operation declarations retain their existing constraints.
The generated schema exposes operation input and result constraints in x-operation-contracts. credit_notes.allocate_external prohibits value_date and omits it from its result; it posts on the recording date.