x-aidy
A host publishes an OpenAPI 3.1 document. An operation joins the aidy catalog when it carries an x-aidy object; operations without one are invisible to aidy. Unknown keys are rejected. For the ideas behind the catalog, see Catalog and Operations.
"post": { "operationId": "stopVm", "x-aidy": { "name": "stop_vm", "title": "Stop server", "description": "Stop a running cloud server (VM).", "open": "/console/instance/{vm_id}", "confirmation": { "title": "Stop server {resource_name}?", "lookup": { "path": "/api/vm/{vm_id}", "labelPath": "name" } } }}Schema
Section titled “Schema”This table is generated at build time from spec/schemas/x-aidy.schema.json, so it always matches the contract.
| Field | Type | Constraint | Required |
|---|---|---|---|
name | string | pattern ^[a-z][a-z0-9_]{0,63}$ | yes |
title | string | ≤ 80 chars | |
description | string | ≤ 500 chars | |
effect | "read" | "create" | "update" | "delete" | "external" | ||
approval | "never" | "always" | ||
role | "identity" | "search" | "form" | ||
surfaces | "agent" | "mcp" | "cli"[] | ||
confirmation | object | ||
confirmation.title | string | ≤ 200 chars | yes |
confirmation.target | string | ≤ 200 chars | |
confirmation.fields | object[] | ||
confirmation.fields[].key | string | yes | |
confirmation.fields[].label | string | yes | |
confirmation.fields[].values | map<string, string> | ||
confirmation.lookup | object | ||
confirmation.lookup.path | string | pattern ^\/(?!\/) | yes |
confirmation.lookup.labelPath | string | yes | |
confirmation.risk | "low" | "medium" | "high" | ||
confirmation.costHint | string | ≤ 200 chars | |
form | string | pattern ^[a-z][a-z0-9_]{0,63}$ | |
resolve | map<string, object> | ||
resolve.<name>.op | string | pattern ^[a-z][a-z0-9_]{0,63}$ | yes |
resolve.<name>.key | string | ||
next | object | ||
next.op | string | pattern ^[a-z][a-z0-9_]{0,63}$ | yes |
next.arguments | map<string, string> | ||
next.argumentsFrom | string | ||
next.when | map<string, any> | ||
open | string | pattern ^\/(?!\/) | |
redact | string[] | ||
repeatable | boolean | ||
timeoutSeconds | number | > 0, ≤ 3600 | |
cli | object | ||
cli.command | string | pattern ^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)*$ | yes |
cli.args | string[] |
Generated from spec/schemas/x-aidy.schema.json at build time; any other key is rejected.
Fields
Section titled “Fields”| Key | Type | Meaning |
|---|---|---|
name |
^[a-z][a-z0-9_]{0,63}$ |
Required. Stable tool name, unique in the catalog. Also the MCP tool name and the CLI command (stop_vm → stop-vm). |
title |
string ≤ 80 | Human label for approval cards, activity rows and CLI help. Defaults to the OpenAPI summary, then name. |
description |
string ≤ 500 | Model-facing description. Name the resource and its common synonyms. Defaults to the OpenAPI summary. |
effect |
read create update delete external |
What the call does. Defaults from the method: GET/HEAD read, POST create, PUT/PATCH update, DELETE delete. external means it reaches outside the product (mail, payment). |
approval |
never always |
Whether the user confirms each call. Defaults to never for read and always otherwise. |
role |
identity search form |
A special operation, see Roles. |
surfaces |
array of agent mcp cli |
Where the operation appears. Defaults: read → all three; other effects → agent, cli. Listing mcp for a write exposes it only to MCP clients that support confirmation. Role operations have no surfaces. |
confirmation |
object | The approval card, see Confirmation. |
form |
operation name | A role: form operation that supplies the input form before approval or execution. |
resolve |
{argument: {op, key?}} |
Name-or-id lookup: before approval, a string argument that is not the key (default id) of an item listed by op is matched against item names. One match replaces it; none or several fail the call with unresolved_reference. |
next |
object | A follow-up call run after success before the model speaks, see Chains. |
open |
path template | Product page shown after success, filled from arguments and the result ({vm_id}). Must start with /. |
redact |
array of field names | Result fields removed before the model or MCP client sees them (for example ip). |
repeatable |
boolean | Allows identical successful writes within one run. Default false: an identical write is answered from the first result. |
timeoutSeconds |
number ≤ 3600 | Call timeout. Default 120; for a role: search operation default 2 and at most 10 (a larger value is a catalog error). |
cli |
{command, args?} |
CLI spelling: command is space-separated words (vm stop), args the positional arguments in order. Default: name with - and no positionals. |
Confirmation
Section titled “Confirmation”{ "title": "Stop server {resource_name}?", "target": "{resource_name}", "fields": [{ "key": "forced", "label": "Force", "values": { "true": "Yes", "false": "No" } }], "lookup": { "path": "/api/vm/{vm_id}", "labelPath": "name" }, "risk": "medium", "costHint": "Billing continues for disks."}Templates take {argument} placeholders and {resource_name}. With lookup, aidy performs an authenticated GET (as the user) before showing approval and reads labelPath from the response as {resource_name}. The lookup path must be served by a GET operation in the catalog, because every call aidy makes names the operation it calls (delegation). A failed lookup aborts the call before approval; nothing runs.
| Key | Constraint | Meaning |
|---|---|---|
title |
required, ≤ 200 | Card heading. |
target |
≤ 200 | The thing acted on, shown prominently. |
fields |
[{key, label, values?}] |
Arguments shown on the card; values maps raw values to labels. |
lookup |
{path, labelPath} |
Authenticated GET that supplies {resource_name}. |
risk |
low medium high |
Shown on the card. |
costHint |
≤ 200 | A line about cost. |
See Approvals.
Chains
Section titled “Chains”"next": { "op": "commit_vm_draft", "arguments": { "draft_id": "id", "revision": "revision" }, "when": { "status": "prepared" }}arguments maps the next call’s arguments to paths in this call’s result. argumentsFrom names a result path whose object becomes the whole input (prepared configurations); arguments may then add path parameters but never overwrite it. when must match the result or the chain stops. The next operation’s own approval still applies. See Chains.
| Role | Shape | Use |
|---|---|---|
identity |
GET, no parameters, read. Exactly one per catalog. |
Answers the Identity of the credential it is called with. |
search |
GET, a required q query parameter, optional limit, read, timeoutSeconds ≤ 10. |
One search source, see Search. |
form |
POST, read, approval: never. |
Receives the target call’s arguments and answers a Form. Never offered to the model. |
Identity
Section titled “Identity”{ "subject": "u_123", "tenant": "t_9", "name": "Ada Lovelace", "locale": "zh-CN", "scopes": ["aidy:admin"]}subject is required; the rest is optional. aidy:admin lets the user change aidy settings (the model chain). Sessions belong to (subject, tenant). See Identity.
Derived operation
Section titled “Derived operation”aidy normalizes each annotated operation into one input schema, which the model, MCP, and CLI all see:
- Path and query parameters become top-level properties.
- An object request body is flattened into top-level properties. Any other body becomes one
bodyproperty. - A name that appears twice (a path parameter and a body field, say) is a catalog error.
$refs into#/components/schemasare kept as$defsreferences, so recursive schemas remain valid.
Validation failures
Section titled “Validation failures”The catalog fails validation when:
- a name is duplicated;
- a
form,resolve, ornextreference names no operation, or names one of the wrong role or effect; - a role operation has the wrong method or shape;
- a confirmation
lookup.pathis not served by a GET operation; openorlookup.pathdoes not start with a single/.
Run aidy check --openapi openapi.json to list every issue; see the CLI reference.