SIGNALS Docs
Exit Reader View
100%
Theme

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_fields is present (non-null) it fully defines the read allowlist.
  • When write_fields is 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 x is allowed when the effective list declares custom_fields (wholesale) or custom_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.


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.