initiative-plugin-sdk 2.0.0

package/schemas/plugin-manifest.json

@@ -0,0 +1,1747 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://initiative.morels.me/schemas/plugin-manifest-v1.json",
+  "title": "Initiative plug-in manifest (the 'definition' body)",
+  "description": "What a plug-in declares it can do. A plug-in is a container, which names its `service` and answers Initiative's calls, or declarative, which names its `hosts` and no service, and whose endpoints, connection checks and webhook events Initiative runs itself from the requests and JSONata expressions written here; one plug-in is never both. This is the 'definition' field of the document served at /.well-known/initiative-plugin.json, NOT that whole document: a registrar also requires protocol_version, public_id and kind alongside it, and refuses a definition served bare. Generated from the platform's own validator vocabulary. A manifest that satisfies this schema is well-formed, not necessarily acceptable. Cross-references (the endpoint a widget binds, a requires term's connection, an endpoint's service prefix), the direction-specific rules on an endpoint, the features/blocks cross-check in both directions, UTF-8 byte-size caps, the rules tying a connection's flow and token to its scope and fields, what a webhooks block names, what a vendor setup writes to, whether every expression parses, what a declarative request and its steps name, and the bounds and unique ids of schedules are enforced by the platform on publish and are not expressible here.",
+  "type": "object",
+  "required": [
+    "plugin_kind",
+    "features"
+  ],
+  "properties": {
+    "plugin_kind": {
+      "const": "service",
+      "description": "The kind every plug-in manifest has, container or declarative: a declarative plug-in is one with no 'service' block."
+    },
+    "service": {
+      "type": "object",
+      "required": [
+        "public_id"
+      ],
+      "properties": {
+        "public_id": {
+          "type": "string",
+          "maxLength": 120,
+          "pattern": "^[\\-.0123456789_abcdefghijklmnopqrstuvwxyz]*\\.[\\-.0123456789_abcdefghijklmnopqrstuvwxyz]*$",
+          "description": "'<publisher>.<slug>'. The name the deployment's registration is matched by, and the namespace this plug-in's events are emitted under."
+        },
+        "protocol": {
+          "enum": [
+            1
+          ],
+          "default": 1
+        },
+        "scopes": {
+          "type": "array",
+          "maxItems": 54,
+          "uniqueItems": true,
+          "items": {
+            "anyOf": [
+              {
+                "enum": [
+                  "projects:read",
+                  "projects:write",
+                  "documents:read",
+                  "documents:write",
+                  "queues:read",
+                  "queues:write",
+                  "counter_groups:read",
+                  "counter_groups:write",
+                  "calendars:read",
+                  "calendars:write",
+                  "dashboards:read",
+                  "dashboards:write",
+                  "posts:read",
+                  "posts:write",
+                  "galleries:read",
+                  "galleries:write",
+                  "wikis:read",
+                  "wikis:write",
+                  "comments:read",
+                  "comments:write",
+                  "relationships:read",
+                  "relationships:write",
+                  "tags:read",
+                  "tags:write",
+                  "sharing:read",
+                  "sharing:write",
+                  "members:read",
+                  "initiatives:read",
+                  "initiatives:moderate",
+                  "community:admin"
+                ]
+              },
+              {
+                "$ref": "#/$defs/pluginScope"
+              }
+            ]
+          },
+          "description": "The scopes this plug-in asks a community to grant: what its installation and member tokens act with. The fixed scopes, and 'plugins:<public_id>' for each plug-in this one calls (at most 24 of those). The community grants some or all of them when it installs the plug-in, and a token never carries more than was granted. Writing implies reading. Absent means none."
+        }
+      },
+      "description": "A container plug-in's service, which Initiative calls. Absent for a declarative plug-in, whose public id is its listing's."
+    },
+    "features": {
+      "type": "array",
+      "maxItems": 4,
+      "items": {
+        "enum": [
+          "dashboards",
+          "embeds",
+          "endpoints",
+          "widgets"
+        ]
+      },
+      "description": "What this plug-in contributes. Cross-checked against the blocks present in both directions: a feature with no block, or a block with no feature, is refused."
+    },
+    "default_name": {
+      "type": "string",
+      "maxLength": 255
+    },
+    "hosts": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 8,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/host"
+      },
+      "description": "Declarative plug-ins, which must name at least one: every host their requests, paging and links may reach. A container plug-in names none."
+    },
+    "auth": {
+      "$ref": "#/$defs/vendorAuth",
+      "description": "Declarative plug-ins only."
+    },
+    "vendor": {
+      "$ref": "#/$defs/vendor"
+    },
+    "connections": {
+      "type": "array",
+      "maxItems": 20,
+      "items": {
+        "$ref": "#/$defs/connection"
+      }
+    },
+    "webhooks": {
+      "$ref": "#/$defs/webhooks"
+    },
+    "schedules": {
+      "type": "array",
+      "maxItems": 8,
+      "items": {
+        "$ref": "#/$defs/schedule"
+      },
+      "description": "What Initiative calls the plug-in's schedule hook for, and how often. At most 8."
+    },
+    "endpoints": {
+      "type": "array",
+      "maxItems": 64,
+      "items": {
+        "$ref": "#/$defs/endpoint"
+      }
+    },
+    "community_summary": {
+      "$ref": "#/$defs/namespacedId",
+      "description": "A read endpoint whose declared returns describe this community's standing with your service — what it has used, what it is allowed. A deployment may render them on the community's own settings page, beside its own figures. Whether it does is the deployment's decision and not this manifest's: a plug-in the operator did not ship is declaring where it would like to appear, which is not the same as appearing."
+    },
+    "widgets": {
+      "type": "array",
+      "maxItems": 12,
+      "items": {
+        "$ref": "#/$defs/widget"
+      }
+    },
+    "embeds": {
+      "type": "array",
+      "maxItems": 12,
+      "items": {
+        "$ref": "#/$defs/embed"
+      }
+    },
+    "dashboards": {
+      "type": "array",
+      "maxItems": 8,
+      "items": {
+        "$ref": "#/$defs/bundledDashboard"
+      },
+      "description": "Ready-made arrangements of this plug-in's own widgets. Publishing the plug-in publishes one ordinary dashboard listing per entry, offered to communities that install the plug-in."
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[\\-0123456789_abcdefghijklmnopqrstuvwxyz]+$"
+    },
+    "path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "pattern": "^(?!.*(?://|\\.\\.))/[\\-./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz]*$",
+      "description": "A route on the plug-in's own service, never an address. The deployment joins it to the base URL its registration supplies."
+    },
+    "localizedText": {
+      "type": "object",
+      "description": "Localized text, keyed by language tag. At least one usable entry; the platform falls back to the reader's language, then to any entry. Values should be strings: text longer than 120 characters is truncated, and an entry that is not a string, is not a language tag, or falls past the first 40 is ignored rather than refused.",
+      "minProperties": 1
+    },
+    "requires": {
+      "type": "object",
+      "description": "Connection ids that must hold a value before this is offered. Exactly one of 'all_of' or 'any_of'; each id must name a connection this manifest declares. Absent means always available.",
+      "properties": {
+        "all_of": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 10,
+          "items": {
+            "$ref": "#/$defs/identifier"
+          }
+        },
+        "any_of": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 10,
+          "items": {
+            "$ref": "#/$defs/identifier"
+          }
+        }
+      },
+      "oneOf": [
+        {
+          "required": [
+            "all_of"
+          ]
+        },
+        {
+          "required": [
+            "any_of"
+          ]
+        }
+      ]
+    },
+    "accessHint": {
+      "type": "object",
+      "description": "What the credential will be used for. Display-only: it is shown beside the form so an admin can mint a minimal credential, and no other system's permissions are enforced from it.",
+      "properties": {
+        "api": {
+          "type": "string",
+          "maxLength": 120
+        },
+        "scopes": {
+          "type": "array",
+          "maxItems": 24,
+          "items": {
+            "type": "string",
+            "maxLength": 120
+          }
+        }
+      }
+    },
+    "connectionField": {
+      "type": "object",
+      "required": [
+        "key",
+        "type",
+        "label"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "$ref": "#/$defs/identifier"
+        },
+        "type": {
+          "enum": [
+            "bool",
+            "int",
+            "secret",
+            "select",
+            "string",
+            "url"
+          ]
+        },
+        "required": {
+          "type": "boolean",
+          "default": false
+        },
+        "label": {
+          "$ref": "#/$defs/localizedText"
+        },
+        "options": {
+          "type": "array",
+          "description": "Required when type is 'select'.",
+          "maxItems": 24,
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "maxLength": 120
+          }
+        },
+        "managed": {
+          "type": "boolean",
+          "default": false,
+          "description": "Returned by the plug-in's after_connect hook when a flow finishes; it is not typed into the settings form."
+        }
+      },
+      "if": {
+        "properties": {
+          "type": {
+            "const": "select"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "required": [
+          "options"
+        ]
+      }
+    },
+    "vendor": {
+      "type": "object",
+      "description": "What an operator supplies once per deployment for the vendor's own client: its id, its secret, its signing key. Declared here and never valued here: the values are entered on the deployment, or written there by the vendor's own setup flow, and referenced from a connection's flow or token as '{vendor.<key>}'.",
+      "required": [
+        "fields"
+      ],
+      "properties": {
+        "label": {
+          "$ref": "#/$defs/localizedText",
+          "description": "What the vendor client is called, for the operator's form."
+        },
+        "fields": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 12,
+          "items": {
+            "$ref": "#/$defs/vendorField"
+          }
+        },
+        "setup": {
+          "$ref": "#/$defs/vendorSetup",
+          "description": "How the vendor's client can be made for a deployment by the vendor itself, rather than registered by hand. Absent: the operator enters every value."
+        }
+      }
+    },
+    "vendorField": {
+      "type": "object",
+      "required": [
+        "key",
+        "type",
+        "label"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "$ref": "#/$defs/identifier"
+        },
+        "type": {
+          "enum": [
+            "secret",
+            "string",
+            "url"
+          ],
+          "description": "A 'secret' is written once and never shown again."
+        },
+        "required": {
+          "type": "boolean",
+          "default": false,
+          "description": "The plug-in is not live on a deployment until every required value is set."
+        },
+        "label": {
+          "$ref": "#/$defs/localizedText"
+        }
+      }
+    },
+    "vendorSetup": {
+      "description": "A flow at the vendor that creates the vendor's client and answers with its values. Initiative runs it from the operator's browser and writes what the vendor answers into the deployment's vendor values, so none is typed or copied. One member per flow, told apart by 'kind'.",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/githubAppManifestSetup"
+        }
+      ]
+    },
+    "githubAppManifestSetup": {
+      "type": "object",
+      "description": "A GitHub App created from a manifest (GitHub's app manifest flow). The operator confirms it on GitHub, and Initiative exchanges the code GitHub returns for the new app's values. Initiative fills in every address itself (the callback, setup, webhook and redirect URLs), so the manifest names none.",
+      "required": [
+        "kind",
+        "app",
+        "values"
+      ],
+      "properties": {
+        "kind": {
+          "const": "github_app_manifest"
+        },
+        "app": {
+          "$ref": "#/$defs/githubAppManifest"
+        },
+        "values": {
+          "type": "object",
+          "description": "Which vendor value each of GitHub's answers is written to: one of this plug-in's vendor field keys to one field of GitHub's manifest-conversion response. Every key must be a field of the vendor block, each response field is written at most once, and 'client_secret', 'pem' and 'webhook_secret' are written only to a 'secret' field.",
+          "minProperties": 1,
+          "maxProperties": 6,
+          "propertyNames": {
+            "$ref": "#/$defs/identifier"
+          },
+          "additionalProperties": {
+            "enum": [
+              "client_id",
+              "client_secret",
+              "id",
+              "pem",
+              "slug",
+              "webhook_secret"
+            ]
+          }
+        }
+      }
+    },
+    "githubAppManifest": {
+      "type": "object",
+      "description": "What GitHub is asked to create: the parts of a GitHub App manifest a plug-in decides.",
+      "required": [
+        "name",
+        "url"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120,
+          "description": "The name GitHub offers for the new app. The operator may change it on GitHub, where an app's name is unique."
+        },
+        "url": {
+          "type": "string",
+          "maxLength": 300,
+          "pattern": "^https://\\S+$",
+          "description": "The app's homepage, https."
+        },
+        "public": {
+          "type": "boolean",
+          "default": false,
+          "description": "Any GitHub account may install the new app. Absent: only the account that owns it."
+        },
+        "default_permissions": {
+          "type": "object",
+          "maxProperties": 100,
+          "propertyNames": {
+            "$ref": "#/$defs/identifier"
+          },
+          "additionalProperties": {
+            "enum": [
+              "read",
+              "write"
+            ]
+          },
+          "description": "The permissions the app is created with, by GitHub's name for each, such as 'issues'. At most 100."
+        },
+        "default_events": {
+          "type": "array",
+          "maxItems": 100,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/identifier"
+          },
+          "description": "The webhook events the app subscribes to, by GitHub's name for each, such as 'issues'. GitHub accepts an event only beside a permission that covers it. At most 100."
+        }
+      }
+    },
+    "endpointParam": {
+      "type": "object",
+      "required": [
+        "key",
+        "type",
+        "label"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "$ref": "#/$defs/identifier"
+        },
+        "type": {
+          "enum": [
+            "bool",
+            "datetime",
+            "int",
+            "select",
+            "string",
+            "url"
+          ]
+        },
+        "required": {
+          "type": "boolean",
+          "default": false
+        },
+        "label": {
+          "$ref": "#/$defs/localizedText"
+        },
+        "options": {
+          "type": "array",
+          "description": "Required when type is 'select'. The values themselves — a consumer that shows a menu writes its own words for them.",
+          "maxItems": 24,
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "maxLength": 120
+          }
+        },
+        "options_from": {
+          "type": "object",
+          "description": "Where this parameter's values come from when only the plug-in can know them. Names a read endpoint in THIS manifest and which of its returns holds the values; a consumer building a form asks the deployment to resolve it rather than showing a text box. For everything a manifest cannot list because the answer differs per install and changes after it — a repository, a channel, a board, a project. `options` is the other case: a set that is the same on every deployment forever. Declaring values, not a control: what to draw is still the consumer's. Resolution is server-side, inherits the source endpoint's `requires` and `cache_ttl_seconds`, and a source that cannot be resolved leaves the parameter enterable rather than unusable.",
+          "properties": {
+            "endpoint": {
+              "$ref": "#/$defs/namespacedId",
+              "description": "A read endpoint this same manifest declares. Not another plug-in's: reading across plug-ins has no consent story, and an id from elsewhere is refused on publish."
+            },
+            "key": {
+              "$ref": "#/$defs/identifier",
+              "description": "Which of that endpoint's returns holds the values. Must be one it declares, and a list: a menu comes from a column of values, not from one."
+            },
+            "label_key": {
+              "$ref": "#/$defs/identifier",
+              "description": "Optional. A second return, parallel to `key`, holding what a person reads — a board's title beside its opaque id. Absent means the value is its own label."
+            },
+            "needs": {
+              "type": "object",
+              "description": "Optional. What to send that endpoint, written as one of ITS parameter names to one of THIS endpoint's. A repository's labels, a board's fields, a field's values — past the first source in a form, most of them answer differently depending on what has been chosen already, and a source that could not be told a sibling's answer could only ever offer the whole account's worth. Every named sibling must be a parameter this endpoint declares, and none of them this one. Until all of them have a value the source is not called and the parameter stays enterable, exactly as for a source that will not resolve.",
+              "propertyNames": {
+                "$ref": "#/$defs/identifier"
+              },
+              "additionalProperties": {
+                "$ref": "#/$defs/identifier"
+              },
+              "maxProperties": 12
+            }
+          },
+          "required": [
+            "endpoint",
+            "key"
+          ]
+        },
+        "list": {
+          "type": "boolean",
+          "default": false,
+          "description": "Several values rather than one. Cardinality is a fact about the value, so it is yours; what to draw for it is the consumer's. Without it, a plug-in wanting several of something declares a string and documents a comma — which nothing downstream can validate or complete."
+        }
+      },
+      "if": {
+        "properties": {
+          "type": {
+            "const": "select"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "required": [
+          "options"
+        ]
+      }
+    },
+    "endpointReturn": {
+      "type": "object",
+      "required": [
+        "key",
+        "type"
+      ],
+      "properties": {
+        "key": {
+          "$ref": "#/$defs/identifier"
+        },
+        "type": {
+          "enum": [
+            "bool",
+            "datetime",
+            "int",
+            "string",
+            "url"
+          ],
+          "description": "The parameter vocabulary minus 'select', because a select is a control and the value behind one is a string."
+        },
+        "label": {
+          "$ref": "#/$defs/localizedText"
+        },
+        "list": {
+          "type": "boolean",
+          "description": "Several values rather than one. It matters to a consumer with somewhere to put exactly one — a form field, a tile's number — which is why it is a flag rather than a second set of types."
+        }
+      }
+    },
+    "connection": {
+      "type": "object",
+      "required": [
+        "id",
+        "scope",
+        "label",
+        "fields"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/identifier"
+        },
+        "scope": {
+          "enum": [
+            "interactive",
+            "static"
+          ],
+          "description": "Who the credential belongs to. 'static' is one credential the whole community uses; 'interactive' is each member's own account at a vendor that authorizes people. It does not say how the credential is obtained: a static connection with a 'flow' is still one credential for the whole community, run by an admin through the vendor's own pages rather than typed into a form. An interactive connection always declares a 'flow'."
+        },
+        "label": {
+          "$ref": "#/$defs/localizedText"
+        },
+        "fields": {
+          "type": "array",
+          "maxItems": 12,
+          "items": {
+            "$ref": "#/$defs/connectionField"
+          },
+          "description": "Without a 'flow', what an admin types. With one, only the values the plug-in's after_connect hook returns, and every field is 'managed'. The tokens a flow obtains are held apart from these, under reserved keys the plug-in never declares."
+        },
+        "flow": {
+          "$ref": "#/$defs/connectionFlow",
+          "description": "How the connection is established. Initiative runs it: the redirect, the code exchange, refreshing and revoking. The plug-in never holds the vendor client's secret or a refresh token."
+        },
+        "token": {
+          "$ref": "#/$defs/connectionToken",
+          "description": "How a usable access token is got for this connection. Absent: the tokens the flow stored, refreshed as needed. Static connections only."
+        },
+        "access_hint": {
+          "$ref": "#/$defs/accessHint"
+        },
+        "health": {
+          "$ref": "#/$defs/connectionHealth"
+        }
+      }
+    },
+    "connectionFlow": {
+      "type": "object",
+      "description": "An OAuth 2.0 authorization code flow (RFC 6749 §4.1) that Initiative runs for a connection, with the redirect addresses the deployment publishes.",
+      "required": [
+        "type",
+        "authorize_url",
+        "token_url",
+        "client_id"
+      ],
+      "properties": {
+        "type": {
+          "enum": [
+            "oauth2"
+          ]
+        },
+        "authorize_url": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "description": "The vendor's authorization endpoint, https. May name a vendor value as '{vendor.<key>}' and one of this connection's own fields as '{<key>}'."
+        },
+        "token_url": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "description": "The vendor's token endpoint, https. May name a vendor value as '{vendor.<key>}' and one of this connection's own fields as '{<key>}'."
+        },
+        "client_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "description": "The vendor client's id, normally '{vendor.client_id}'. May name a vendor value as '{vendor.<key>}' and one of this connection's own fields as '{<key>}'."
+        },
+        "client_secret": {
+          "type": "string",
+          "maxLength": 300,
+          "description": "The vendor client's secret, normally '{vendor.client_secret}'. Absent for a public client. May name a vendor value as '{vendor.<key>}' and one of this connection's own fields as '{<key>}'."
+        },
+        "scopes": {
+          "type": "array",
+          "maxItems": 24,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 120
+          },
+          "description": "The vendor scopes asked for, sent space-separated."
+        },
+        "pkce": {
+          "type": "boolean",
+          "default": true,
+          "description": "Send an S256 code challenge (RFC 7636)."
+        },
+        "authorize_params": {
+          "type": "object",
+          "maxProperties": 12,
+          "propertyNames": {
+            "$ref": "#/$defs/identifier"
+          },
+          "additionalProperties": {
+            "type": "string",
+            "maxLength": 2000
+          },
+          "description": "Extra query parameters for the authorization request. May name a vendor value as '{vendor.<key>}' and one of this connection's own fields as '{<key>}'."
+        },
+        "install_url": {
+          "type": "string",
+          "maxLength": 300,
+          "description": "Static connections only. The vendor's install page, for a connection an organization installs: the person installs first, the vendor returns to the setup address with the installation's id, and one authorization trip follows so the plug-in can check who installed it. Requires 'after_connect'. May name a vendor value as '{vendor.<key>}' and one of this connection's own fields as '{<key>}'."
+        },
+        "after_connect": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/afterConnect"
+            }
+          ],
+          "default": false,
+          "description": "What runs once the code is exchanged, with the fresh access token, to learn the connection's managed values and an account label, or to refuse it. A container plug-in sets true, and Initiative calls its after_connect hook; a declarative plug-in gives the call and its mapping."
+        },
+        "revoke": {
+          "enum": [
+            "github_grant",
+            "hook",
+            "rfc7009"
+          ],
+          "description": "How a grant is ended at the vendor when the connection ends: 'rfc7009' posts to 'revoke_url' with the client's credentials; 'github_grant' sends DELETE to 'revoke_url' (GitHub's 'Delete an app authorization') with the client's credentials as HTTP Basic auth and the access token in the JSON body as 'access_token'; 'hook' calls the plug-in's revoke hook with the tokens, so a container plug-in's only. Absent: the tokens are deleted and nothing is sent."
+        },
+        "revoke_url": {
+          "type": "string",
+          "maxLength": 300,
+          "description": "The vendor's revocation endpoint: RFC 7009's for 'rfc7009', or GitHub's grant address (https://api.github.com/applications/{vendor.client_id}/grant) for 'github_grant'. Required when 'revoke' is either. May name a vendor value as '{vendor.<key>}' and one of this connection's own fields as '{<key>}'."
+        }
+      }
+    },
+    "connectionToken": {
+      "type": "object",
+      "description": "An access token minted on demand rather than stored: Initiative signs a JWT with the vendor key and exchanges it, and caches the answer until shortly before it expires.",
+      "required": [
+        "type",
+        "exchange_url",
+        "iss",
+        "key"
+      ],
+      "properties": {
+        "type": {
+          "enum": [
+            "jwt_bearer"
+          ]
+        },
+        "exchange_url": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "description": "Where the signed JWT is posted, https. The answer's 'token' (or 'access_token') and 'expires_at' (or 'expires_in') are read. May name a vendor value as '{vendor.<key>}' and one of this connection's own fields as '{<key>}'."
+        },
+        "iss": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "description": "The JWT's issuer, normally '{vendor.app_id}'. May name a vendor value as '{vendor.<key>}' and one of this connection's own fields as '{<key>}'."
+        },
+        "key": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "description": "The signing key, as a vendor value: '{vendor.private_key}'. A PEM private key."
+        },
+        "alg": {
+          "enum": [
+            "ES256",
+            "RS256"
+          ],
+          "default": "RS256"
+        },
+        "lifetime": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 600,
+          "default": 540,
+          "description": "How long the signed JWT lives, in seconds."
+        }
+      }
+    },
+    "webhooks": {
+      "type": "object",
+      "description": "The vendor's webhooks, received by Initiative at one address per plug-in on the deployment, '/api/v1/plugin-hooks/<public_id>'. Initiative checks each delivery's signature, drops one it has already delivered, finds the communities it belongs to by a value in its body, and forwards it to the plug-in's webhook hook once for each. A container plug-in's hook receives each delivery; a declarative plug-in maps it with 'events' and 'status' instead.",
+      "required": [
+        "verify",
+        "dedup",
+        "route"
+      ],
+      "properties": {
+        "verify": {
+          "$ref": "#/$defs/webhookVerify"
+        },
+        "dedup": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[\\-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz]+$",
+          "description": "The header carrying the vendor's id for one delivery, such as 'X-GitHub-Delivery'. A delivery with an id already forwarded to a community is not forwarded to it again."
+        },
+        "route": {
+          "$ref": "#/$defs/webhookRoute"
+        },
+        "events": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "items": {
+            "$ref": "#/$defs/webhookEvent"
+          },
+          "description": "Declarative plug-ins: how a delivery becomes one of this plug-in's events. The first row whose 'when' holds emits; a delivery no row matches is dropped."
+        },
+        "status": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 12,
+          "items": {
+            "$ref": "#/$defs/webhookStatus"
+          },
+          "description": "Declarative plug-ins: deliveries that say what state a connection is in at the vendor. The first row whose 'when' holds sets it."
+        }
+      }
+    },
+    "webhookVerify": {
+      "type": "object",
+      "description": "How a delivery's signature is checked: an HMAC over the raw body under a vendor value.",
+      "required": [
+        "scheme",
+        "header",
+        "encoding",
+        "secret"
+      ],
+      "properties": {
+        "scheme": {
+          "enum": [
+            "hmac_sha1",
+            "hmac_sha256"
+          ]
+        },
+        "header": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[\\-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz]+$",
+          "description": "The header carrying the signature, such as 'X-Hub-Signature-256'."
+        },
+        "prefix": {
+          "type": "string",
+          "maxLength": 64,
+          "description": "What precedes the signature in the header, such as 'sha256='. Absent: nothing does."
+        },
+        "encoding": {
+          "enum": [
+            "base64",
+            "hex"
+          ],
+          "description": "How the signature is written."
+        },
+        "secret": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "description": "The signing secret, as one vendor value: '{vendor.<key>}'."
+        }
+      }
+    },
+    "webhookRoute": {
+      "type": "object",
+      "description": "Which communities a delivery belongs to: a value in its body or in one of its headers, matched against one field of a static connection as each community's connect stored it. Exactly one of 'path' and 'header'.",
+      "required": [
+        "connection",
+        "field"
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "pattern": "^[\\-.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz]+$",
+          "description": "Where the value is in the JSON body, as keys joined by '.', such as 'installation.id'."
+        },
+        "header": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[\\-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz]+$",
+          "description": "The header carrying the value, such as 'X-Shopify-Shop-Domain'."
+        },
+        "connection": {
+          "$ref": "#/$defs/identifier",
+          "description": "A static connection this plug-in declares."
+        },
+        "field": {
+          "$ref": "#/$defs/identifier",
+          "description": "A field that connection declares, whose stored value the body's value is matched against."
+        }
+      }
+    },
+    "schedule": {
+      "type": "object",
+      "description": "An interval at which Initiative calls the plug-in's schedule hook, once for each community that installed it, with when the call last succeeded there.",
+      "required": [
+        "id",
+        "every"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/identifier",
+          "description": "Unique within the manifest. The hook is told which schedule is due by it."
+        },
+        "every": {
+          "type": "string",
+          "maxLength": 5,
+          "pattern": "^[0-9]+[mh]$",
+          "description": "How often: a whole number of minutes ('15m') or hours ('6h'), at least 5 minutes and at most 1440 minutes."
+        }
+      }
+    },
+    "namespacedId": {
+      "type": "string",
+      "maxLength": 200,
+      "pattern": "^[\\-.0123456789_abcdefghijklmnopqrstuvwxyz]+$",
+      "description": "Namespaced under the plug-in's own service id — 'plugin.<public_id>.<name>'. The prefix is checked against the declaring registration at ingress."
+    },
+    "pluginScope": {
+      "type": "string",
+      "pattern": "^plugins:[\\-.0123456789_abcdefghijklmnopqrstuvwxyz]*\\.[\\-.0123456789_abcdefghijklmnopqrstuvwxyz]*$",
+      "description": "'plugins:<public_id>': permission to call another plug-in's public endpoints through the deployment, as this community or as one of its members. Not one of the fixed scopes: the family is open, one per plug-in, and the public id after the prefix is the plug-in being called. The deployment never lets a plug-in address another directly; the call goes through it, and the plug-in called is handed its own references for whoever the call is for."
+    },
+    "endpoint": {
+      "type": "object",
+      "required": [
+        "id",
+        "direction"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/namespacedId"
+        },
+        "label": {
+          "$ref": "#/$defs/localizedText",
+          "description": "What this endpoint IS, in words somebody picks it out of a list by. Every direction, and an emission most of all: it is the one thing here chosen without ever being called."
+        },
+        "description": {
+          "$ref": "#/$defs/localizedText",
+          "description": "A second line, where the label needs one."
+        },
+        "returns": {
+          "type": "array",
+          "maxItems": 24,
+          "items": {
+            "$ref": "#/$defs/endpointReturn"
+          },
+          "description": "What this hands back, by name and type — the response for a read or a write, the payload for an emission. Declared rather than discovered, because a consumer binds one of these before the endpoint has ever run and a bad binding has to be refusable when somebody arranges it."
+        },
+        "group": {
+          "$ref": "#/$defs/identifier",
+          "description": "Where a consumer that groups a plug-in's endpoints should file this one. Opaque here: the grouping is the consumer's, and an endpoint that says nothing sits in the flat list."
+        },
+        "needs_subject": {
+          "$ref": "#/$defs/identifier",
+          "description": "What a caller must already have in hand for this to mean anything. Opaque here — the vocabulary belongs to whoever consumes it; the automation service names the subjects a run can be about."
+        },
+        "direction": {
+          "enum": [
+            "emit",
+            "read",
+            "write"
+          ],
+          "description": "'read' and 'write' are called through the deployment and answer in place; 'emit' travels the other way — the plug-in posts it to a subscriber that registered a URL, so it carries no parameters and nothing to gate."
+        },
+        "params": {
+          "type": "array",
+          "maxItems": 12,
+          "items": {
+            "$ref": "#/$defs/endpointParam"
+          },
+          "description": "What a caller may send. Read and write only."
+        },
+        "actors": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 2,
+          "items": {
+            "enum": [
+              "installation",
+              "member"
+            ]
+          },
+          "description": "Whose credential the call runs on, best first. Read and write only. An endpoint offering only 'member' refuses when that member has connected nothing, rather than quietly acting as the plug-in instead."
+        },
+        "admin_only": {
+          "type": "boolean",
+          "default": false,
+          "description": "Only the community's admins read or call this endpoint — a figure for the community's settings page, say. Anyone who can see where it is used may otherwise."
+        },
+        "public": {
+          "type": "boolean",
+          "default": false,
+          "description": "Read and write only. Other plug-ins may call this endpoint through the deployment, when the community has let them use this plug-in ('plugins:<your public id>'). A caller acts as the community or as one of its members, and `actors` says which of the two this endpoint takes: one that names neither is not callable this way. A write endpoint is reachable only like this; a widget binds reads alone. Absent means only the deployment's own surfaces reach it."
+        },
+        "requires": {
+          "$ref": "#/$defs/requires"
+        },
+        "cache_ttl_seconds": {
+          "type": "integer",
+          "default": 0,
+          "description": "Read only. How long a response may be reused. Clamped into 0..86400 rather than refused, so a value outside that range is accepted and takes effect at the bound — which is why no range is asserted here."
+        },
+        "identity": {
+          "$ref": "#/$defs/endpointIdentity",
+          "description": "'write' and 'emit': what this touched, or what it is about. Read endpoints have none — they touched nothing, so there is no echo to suppress."
+        },
+        "unavailable": {
+          "type": "array",
+          "maxItems": 12,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/identifier"
+          },
+          "description": "Read and write only. The codes this endpoint may answer 'unavailable' with beyond Initiative's own (invalid, mapping-failed, not-authorized, not-found, range-too-large), so a consumer can put each into words."
+        },
+        "request": {
+          "$ref": "#/$defs/vendorRequest",
+          "description": "Declarative plug-ins: the one call that answers this endpoint. Not beside 'steps'."
+        },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 3,
+          "items": {
+            "$ref": "#/$defs/requestStep"
+          },
+          "description": "Declarative plug-ins: up to 3 calls made in order, each able to read the answers of the ones before it. Not beside 'request'."
+        },
+        "map": {
+          "$ref": "#/$defs/expression",
+          "description": "Declarative plug-ins: the endpoint's answer, from 'response' (the last call's answer) and 'steps': an object of its declared returns, or {\"unavailable\": \"<code>\"} naming one of its codes."
+        },
+        "errors": {
+          "type": "array",
+          "maxItems": 12,
+          "items": {
+            "$ref": "#/$defs/errorRule"
+          },
+          "description": "Declarative plug-ins: vendor answers this endpoint gives its own meaning, tried on every answer before the defaults. The defaults: 401 and 403 are not-authorized, 404 not-found, 400, 422 and any other 4xx invalid, and 429, 3xx and 5xx transient."
+        }
+      },
+      "additionalProperties": false
+    },
+    "widget": {
+      "type": "object",
+      "required": [
+        "id",
+        "meta",
+        "module_source"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/identifier"
+        },
+        "meta": {
+          "type": "object",
+          "description": "The widget's own name and description, as the picker shows them. Must name the widget in at least one language."
+        },
+        "module_source": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The widget's browser-side module. Stored as an opaque string and executed only inside the sandbox; the platform never parses it. Capped in UTF-8 bytes, which this schema cannot express."
+        },
+        "endpoints": {
+          "type": "array",
+          "maxItems": 8,
+          "items": {
+            "$ref": "#/$defs/namespacedId"
+          },
+          "description": "Read endpoint ids this manifest also declares. Only a read answers with something to draw."
+        },
+        "sample_data": {
+          "type": "object",
+          "description": "What each endpoint would answer with, keyed by declared read endpoint id, so a preview renders with no network call. Written in the endpoint's own returns and read through them exactly as a live answer is. Keys naming an undeclared endpoint are dropped."
+        },
+        "requires": {
+          "$ref": "#/$defs/requires"
+        }
+      }
+    },
+    "embed": {
+      "type": "object",
+      "required": [
+        "id",
+        "path",
+        "name"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/identifier"
+        },
+        "path": {
+          "$ref": "#/$defs/path"
+        },
+        "name": {
+          "$ref": "#/$defs/localizedText"
+        },
+        "scopes": {
+          "type": "array",
+          "maxItems": 2,
+          "items": {
+            "enum": [
+              "community",
+              "initiative"
+            ]
+          },
+          "default": [
+            "community"
+          ],
+          "description": "Where the surface renders. Declaring both gives it a community-wide entry and an entry inside each initiative."
+        },
+        "admin_only": {
+          "type": "boolean",
+          "default": false,
+          "description": "Only the community's admins open this surface, whatever roles a placement allows — a settings page, say. Who else may open a surface is chosen in the community, per initiative and per role, not declared here."
+        },
+        "capabilities": {
+          "type": "array",
+          "maxItems": 8,
+          "items": {
+            "enum": [
+              "camera",
+              "clipboard-read",
+              "clipboard-write",
+              "display-capture",
+              "fullscreen",
+              "geolocation",
+              "microphone"
+            ]
+          },
+          "description": "Browser features the frame is granted. A surface that names nothing is framed with all of them denied."
+        },
+        "requires": {
+          "$ref": "#/$defs/requires"
+        }
+      }
+    },
+    "bundledDashboard": {
+      "type": "object",
+      "required": [
+        "uid",
+        "public_id",
+        "name",
+        "widgets"
+      ],
+      "properties": {
+        "uid": {
+          "type": "string",
+          "minLength": 14,
+          "maxLength": 14,
+          "pattern": "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]+$",
+          "description": "This dashboard's own catalog id — publisher-assigned, immutable, never reused. It becomes a listing of its own, so this is a real catalog identity and not the plug-in's."
+        },
+        "public_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120,
+          "pattern": "^[\\-.0123456789_abcdefghijklmnopqrstuvwxyz]+$",
+          "description": "'<publisher>.<slug>', and not the plug-in's own — a bundled dashboard is a separate listing."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 500
+        },
+        "layout": {
+          "type": "object",
+          "properties": {
+            "columns": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 12
+            }
+          }
+        },
+        "widgets": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 50,
+          "items": {
+            "$ref": "#/$defs/bundledDashboardWidget"
+          }
+        }
+      }
+    },
+    "bundledDashboardWidget": {
+      "type": "object",
+      "required": [
+        "type",
+        "binding"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/identifier"
+        },
+        "type": {
+          "$ref": "#/$defs/identifier",
+          "description": "One of this manifest's own widget ids — bare, with no uid. The platform stamps the plug-in's uid on when it publishes, so the two can never disagree."
+        },
+        "title": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "grid": {
+          "type": "object",
+          "properties": {
+            "x": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 12
+            },
+            "y": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "w": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 12
+            },
+            "h": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        "binding": {
+          "type": "object",
+          "required": [
+            "endpoint_id"
+          ],
+          "properties": {
+            "endpoint_id": {
+              "$ref": "#/$defs/namespacedId",
+              "description": "One of this manifest's own read endpoint ids. Only a read answers with something to draw."
+            },
+            "params": {
+              "type": "object",
+              "maxProperties": 12,
+              "additionalProperties": {
+                "type": [
+                  "string",
+                  "integer",
+                  "boolean"
+                ],
+                "maxLength": 2000
+              }
+            }
+          }
+        }
+      }
+    },
+    "endpointIdentity": {
+      "type": "object",
+      "description": "Which of this endpoint's returns identify the thing it touched. A consumer keeps a change an automation made from firing that automation again, and for a plug-in there was no key — so guessing would silently drop a fire somebody was waiting on, and a rate cap was the only guard. Declare the SAME kind and key on the write and on the emission about it, and the two produce the same address.",
+      "required": [
+        "kind",
+        "key"
+      ],
+      "properties": {
+        "kind": {
+          "$ref": "#/$defs/identifier",
+          "description": "Your own word for what sort of thing this is ('issue'). Namespaced by your public id downstream, because two plug-ins declaring the same kind mean two different things."
+        },
+        "key": {
+          "type": "array",
+          "description": "Returns of this endpoint, in order, joined to form the address. Every one must be a single value rather than a list — half an address matches nothing, and one built from the parts that happened to be there matches the wrong thing.",
+          "minItems": 1,
+          "maxItems": 4,
+          "items": {
+            "$ref": "#/$defs/identifier"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "expression": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 16384,
+      "description": "A JSONata expression (https://jsonata.org): standard JSONata, with no functions added. It reads one document. On the way out that holds 'params', the call's parameters as the caller sent them; 'connection', the non-secret fields of the connection the request names; 'connections', on an endpoint's requests and map, each connection its 'requires' names that the call has, by its id, holding the same fields; 'now', the time of the call in ISO 8601, which $now() and $millis() also answer; and 'steps', each earlier step's answer by its name. On the way back it also holds 'response', the answer being read: {status, headers, body}, with header names in lowercase. Each evaluation is bounded: at most 1000 milliseconds, 500 levels of nesting and an answer of 1048576 bytes as JSON. An expression that fails or passes a bound answers 'unavailable: mapping-failed'."
+    },
+    "host": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 253,
+      "pattern": "^(\\*\\.)?[a-z0-9-]+(\\.[a-z0-9-]+)+$",
+      "description": "A host a declarative plug-in calls, in lowercase: exact ('api.github.com'), or with one leading '*.' that stands for exactly one label ('*.myshopify.com'). No scheme, port or path: every call is https on port 443, and goes only to a public address."
+    },
+    "headerName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[\\-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz]+$"
+    },
+    "queryName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[\\-.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]_abcdefghijklmnopqrstuvwxyz~]+$"
+    },
+    "vendorAuth": {
+      "type": "object",
+      "description": "How Initiative puts a connection's credential on a declarative plug-in's requests: one header, holding the prefix and the token joined by a space. Absent: 'Authorization: Bearer <token>'.",
+      "properties": {
+        "header": {
+          "$ref": "#/$defs/headerName",
+          "default": "Authorization"
+        },
+        "prefix": {
+          "type": "string",
+          "maxLength": 64,
+          "default": "Bearer",
+          "description": "Written before the token. Empty: the token alone."
+        }
+      },
+      "additionalProperties": false
+    },
+    "vendorRequest": {
+      "type": "object",
+      "description": "One call Initiative makes to the vendor for a declarative plug-in, rendered from expressions. Initiative adds the credential itself, as 'auth' says, and follows no redirect.",
+      "required": [
+        "method",
+        "url"
+      ],
+      "properties": {
+        "method": {
+          "enum": [
+            "DELETE",
+            "GET",
+            "PATCH",
+            "POST",
+            "PUT"
+          ]
+        },
+        "url": {
+          "$ref": "#/$defs/expression",
+          "description": "The address, as an expression answering a string: https, on one of the plug-in's hosts. Query parameters may be written into it or given in 'query'."
+        },
+        "query": {
+          "type": "object",
+          "maxProperties": 24,
+          "propertyNames": {
+            "$ref": "#/$defs/queryName"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/expression"
+          },
+          "description": "Query parameters by name, each an expression. One answering null or nothing is left out, and a list repeats the parameter once per value."
+        },
+        "headers": {
+          "type": "object",
+          "maxProperties": 12,
+          "propertyNames": {
+            "$ref": "#/$defs/headerName"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/expression"
+          },
+          "description": "Headers by name, each an expression answering a string; one answering null or nothing is left out. Never the credential's header, which Initiative sets."
+        },
+        "body": {
+          "$ref": "#/$defs/expression",
+          "description": "The JSON body, as an expression. Not beside 'graphql'."
+        },
+        "graphql": {
+          "$ref": "#/$defs/graphqlRequest"
+        },
+        "connection": {
+          "$ref": "#/$defs/identifier",
+          "description": "Which connection's credential the request carries: a static connection's is the community's, an interactive one's the acting member's. A call made as a member carries a static connection's credential only when the endpoint's 'requires' names that connection, and is refused otherwise. Required on an endpoint's requests. Absent on 'after_connect' and 'health', which carry the credential of the connection they belong to."
+        },
+        "paging": {
+          "$ref": "#/$defs/paging"
+        }
+      },
+      "additionalProperties": false
+    },
+    "graphqlRequest": {
+      "type": "object",
+      "description": "A GraphQL request, sent by POST as the JSON body {query, variables}.",
+      "required": [
+        "query"
+      ],
+      "properties": {
+        "query": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 16384,
+          "description": "The GraphQL document, as text. What varies goes in 'variables'."
+        },
+        "variables": {
+          "$ref": "#/$defs/expression",
+          "description": "The variables, as an expression answering an object."
+        }
+      },
+      "additionalProperties": false
+    },
+    "requestStep": {
+      "type": "object",
+      "required": [
+        "name",
+        "request"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/$defs/identifier",
+          "description": "Unique among its steps. Later steps, the map and the predicates beside it read this step's answer as 'steps.<name>'."
+        },
+        "request": {
+          "$ref": "#/$defs/vendorRequest"
+        }
+      },
+      "additionalProperties": false
+    },
+    "paging": {
+      "description": "How a request reads more than one page, one member per method, told apart by 'kind'. Every page is read before the answer is mapped: 'response.body' is then every page's items appended in order, and the status and headers are the last page's. 'max_pages' is how many pages may be read; finding more after that many truncates or refuses, as 'on_limit' says, and a refusal answers 'unavailable: range-too-large'.",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/pageNumberPaging"
+        },
+        {
+          "$ref": "#/$defs/linkHeaderPaging"
+        },
+        {
+          "$ref": "#/$defs/cursorPaging"
+        }
+      ]
+    },
+    "pageNumberPaging": {
+      "type": "object",
+      "description": "Numbered pages from 1, read until one holds fewer than 'per_page' items. Both parameters are added to the request's query.",
+      "required": [
+        "kind",
+        "page_param",
+        "per_page",
+        "max_pages",
+        "on_limit"
+      ],
+      "properties": {
+        "kind": {
+          "const": "page_number"
+        },
+        "page_param": {
+          "$ref": "#/$defs/queryName",
+          "description": "The parameter carrying the page number."
+        },
+        "per_page_param": {
+          "$ref": "#/$defs/queryName",
+          "description": "The parameter carrying 'per_page'. Absent: the vendor's page size is fixed, and 'per_page' says what it is."
+        },
+        "per_page": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100
+        },
+        "items": {
+          "$ref": "#/$defs/pageItems"
+        },
+        "max_pages": {
+          "$ref": "#/$defs/maxPages"
+        },
+        "on_limit": {
+          "enum": [
+            "refuse",
+            "truncate"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "linkHeaderPaging": {
+      "type": "object",
+      "description": "The address in the Link header's rel=\"next\", followed until there is none. It must be https on one of the plug-in's hosts.",
+      "required": [
+        "kind",
+        "max_pages",
+        "on_limit"
+      ],
+      "properties": {
+        "kind": {
+          "const": "link_header"
+        },
+        "items": {
+          "$ref": "#/$defs/pageItems"
+        },
+        "max_pages": {
+          "$ref": "#/$defs/maxPages"
+        },
+        "on_limit": {
+          "enum": [
+            "refuse",
+            "truncate"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "cursorPaging": {
+      "type": "object",
+      "description": "A cursor read from each page and sent with the next, while 'more' holds. Exactly one of 'param' and 'variable' says where it is sent.",
+      "required": [
+        "kind",
+        "next",
+        "more",
+        "max_pages",
+        "on_limit"
+      ],
+      "properties": {
+        "kind": {
+          "const": "cursor"
+        },
+        "next": {
+          "$ref": "#/$defs/expression",
+          "description": "The next page's cursor, from this page's 'response'."
+        },
+        "more": {
+          "$ref": "#/$defs/expression",
+          "description": "Whether there is a next page, from this page's 'response'."
+        },
+        "param": {
+          "$ref": "#/$defs/queryName",
+          "description": "The query parameter the cursor is sent in."
+        },
+        "variable": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[_A-Za-z][_0-9A-Za-z]*$",
+          "description": "The GraphQL variable the cursor is sent in."
+        },
+        "items": {
+          "$ref": "#/$defs/pageItems"
+        },
+        "max_pages": {
+          "$ref": "#/$defs/maxPages"
+        },
+        "on_limit": {
+          "enum": [
+            "refuse",
+            "truncate"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "pageItems": {
+      "$ref": "#/$defs/expression",
+      "description": "A page's items, from that page's 'response'. Absent: its body."
+    },
+    "maxPages": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 10
+    },
+    "statusMatch": {
+      "description": "An HTTP status: one code, or a range of a hundred ('4xx').",
+      "anyOf": [
+        {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 599
+        },
+        {
+          "enum": [
+            "2xx",
+            "3xx",
+            "4xx",
+            "5xx"
+          ]
+        }
+      ]
+    },
+    "errorRule": {
+      "type": "object",
+      "description": "A vendor answer an endpoint gives its own meaning. Rules are tried in order on every answer, a 2xx included, and the first that matches decides.",
+      "required": [
+        "status",
+        "code"
+      ],
+      "properties": {
+        "status": {
+          "$ref": "#/$defs/statusMatch"
+        },
+        "when": {
+          "$ref": "#/$defs/expression",
+          "description": "Also required to hold, over the answer as 'response'. Absent: the status alone matches."
+        },
+        "code": {
+          "$ref": "#/$defs/identifier",
+          "description": "What the call answers: one of the endpoint's 'unavailable' codes, one of Initiative's own (invalid, mapping-failed, not-authorized, not-found, range-too-large), or 'transient' for a passing failure such as a throttle, which is answered as one to retry."
+        }
+      },
+      "additionalProperties": false
+    },
+    "afterConnect": {
+      "type": "object",
+      "description": "A declarative plug-in's after_connect: a request, or up to 3 steps, made with the access token just obtained, and the answers mapped to what the hook would answer. 'params' holds the flow's own parameters, such as the installation_id an install page returned.",
+      "required": [
+        "map"
+      ],
+      "properties": {
+        "request": {
+          "$ref": "#/$defs/vendorRequest",
+          "description": "The one call. Not beside 'steps'."
+        },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 3,
+          "items": {
+            "$ref": "#/$defs/requestStep"
+          },
+          "description": "Up to 3 calls made in order, each able to read the answers of the ones before it. Not beside 'request'."
+        },
+        "map": {
+          "$ref": "#/$defs/expression",
+          "description": "The connection's managed values and its account label, from 'response' (the last call's answer) and 'steps': {\"values\": {…}, \"account_label\": \"…\"}."
+        },
+        "refuse_when": {
+          "$ref": "#/$defs/expression",
+          "description": "Refuses the connection when it holds. It reads the map's answer as 'result', beside 'response' and 'steps'."
+        },
+        "code": {
+          "$ref": "#/$defs/identifier",
+          "description": "What a refusal answers. Given exactly when 'refuse_when' is."
+        }
+      },
+      "oneOf": [
+        {
+          "required": [
+            "request"
+          ]
+        },
+        {
+          "required": [
+            "steps"
+          ]
+        }
+      ],
+      "additionalProperties": false
+    },
+    "connectionHealth": {
+      "type": "object",
+      "description": "Declarative plug-ins: a request Initiative makes on an interval, with this connection's credential, to learn whether the connection still works. A state other than 'ok' is reported once two answers in a row give it.",
+      "required": [
+        "request",
+        "every",
+        "states"
+      ],
+      "properties": {
+        "request": {
+          "$ref": "#/$defs/vendorRequest"
+        },
+        "every": {
+          "type": "string",
+          "maxLength": 5,
+          "pattern": "^[0-9]+[mh]$",
+          "description": "How often: a whole number of minutes ('15m') or hours ('6h'), at least 5 minutes and at most 1440 minutes."
+        },
+        "states": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 12,
+          "items": {
+            "$ref": "#/$defs/healthState"
+          },
+          "description": "Tried in order; the first that matches gives the state. An answer none matches is 'ok' when it is 2xx and 'unavailable' otherwise."
+        }
+      },
+      "additionalProperties": false
+    },
+    "healthState": {
+      "type": "object",
+      "description": "The answers one row matches, and the state they mean. A row naming neither 'status' nor 'when' matches any answer.",
+      "required": [
+        "state"
+      ],
+      "properties": {
+        "status": {
+          "$ref": "#/$defs/statusMatch"
+        },
+        "when": {
+          "$ref": "#/$defs/expression",
+          "description": "Also required to hold, over the answer as 'response'."
+        },
+        "state": {
+          "enum": [
+            "ok",
+            "removed",
+            "suspended",
+            "unavailable"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "webhookEvent": {
+      "type": "object",
+      "description": "One way a delivery becomes an event. Its expressions read 'headers' (names in lowercase), 'payload' (the parsed body), 'connection' (the routed connection's non-secret fields) and 'now'.",
+      "required": [
+        "when",
+        "emit",
+        "map"
+      ],
+      "properties": {
+        "when": {
+          "$ref": "#/$defs/expression",
+          "description": "Whether this row applies."
+        },
+        "emit": {
+          "$ref": "#/$defs/namespacedId",
+          "description": "An emit endpoint this manifest declares."
+        },
+        "map": {
+          "$ref": "#/$defs/expression",
+          "description": "The event's payload: an object of that endpoint's declared returns."
+        }
+      },
+      "additionalProperties": false
+    },
+    "webhookStatus": {
+      "type": "object",
+      "description": "A delivery that says what state a connection is in, read as an event's expressions are.",
+      "required": [
+        "when",
+        "connection",
+        "state"
+      ],
+      "properties": {
+        "when": {
+          "$ref": "#/$defs/expression",
+          "description": "Whether this row applies."
+        },
+        "connection": {
+          "$ref": "#/$defs/identifier",
+          "description": "A connection this plug-in declares."
+        },
+        "state": {
+          "enum": [
+            "ok",
+            "removed",
+            "suspended",
+            "unavailable"
+          ],
+          "description": "'ok', 'suspended' or 'removed'."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}