IntentSchema — Spec

A public registry of action types that AI agents take on a user's behalf, and the service-specific variants of each action.

Agents, orchestrators, signing, and execution sit downstream of this; the registry only describes what the actions are and how they vary by service.

Intent identifier

<authority>.<sector>.<domain>.<object>.<action>.v<N>

Segments MUST be lowercase ASCII; objects MUST be singular nouns; verbs MUST be present tense.

URL forms

Every published file is served at two URL shapes; implementations choose.

Hash = sha256(JCS(file)) (RFC 8785 canonicalization). The hash-pinned URL returns the matching bytes or 404; it MUST NOT redirect on mismatch. @sha256-<base64> accepted as an SRI-style alias.

Use bare URLs for documentation and browsing. Use hash-pinned URLs in signed payloads, approval surfaces, and any context where schema substitution must be impossible.

The registry root also publishes /index.json — a machine-readable catalog of every intent, profile, and common schema with its bare URL, hash-pinned URL, and current sha256. Consumers fetch this once to enumerate the catalog instead of crawling.

Intent file

{
  "$id": "https://intentschema.org/intents/communication/email/message/send/v1.json",
  "fqdn": "org.intentschema.communication.email.message.send.v1",
  "title": "Send email message",
  "description": "Sends an email message to one or more recipients.",
  "payload": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "...": "..." },
  "result":  { "type": "object", "...": "..." },
  "examples": [
    { "name": "basic send", "value": { "...": "..." } }
  ]
}

Conventions

Target — every payload declares a target identifying where the action happens. Shared shape at common/target/v1.json:

{ "system": "gmail", "external_id": "msg_abc123", "etag": "W/\"xyz\"" }

system is a lowercase provider id; external_id is required for update/delete/reply intents and omitted for create-in-default-container; etag is an optional optimistic-concurrency token.

Attachments and blobs — carried by reference (common/blob-ref/v1.json). Required: url and sha256. Executors verify the hash before passing bytes to the provider.

Idempotency — mutating intents MAY include idempotency_key (opaque string, typically ULID or UUIDv7). Executors use it to deduplicate retries against the provider.

Update semantics — an update-style intent picks either full object replace or an RFC 6902 JSON patch array, declared in the payload schema. Merge patch is not used.

Result schema — every intent MAY declare a result block (JSON Schema) describing what the executor returns on success.

Read verbs (list, read, get) — three verbs for fetching data, each with a distinct role:

The send/read pairing is natural for messaging (you send a message, you read a message). The create/get pairing is natural for records (you create an event, you get an event).

availability.set mode — under productivity.calendar.availability.set, the object.mode field selects which availability concept is being set (working_hours, focus, ooo). Avoids exploding into separate intents per mode.

Examples — each intent SHOULD include an inline examples array. Each entry has name and value; value MUST validate against the intent's payload. CI validates every entry.

Provider-specific fields — provider-specific request and response fields live at the payload top level under a key matching target.system. A Gmail payload targeting system: "gmail" carries its extras under a gmail object; a Microsoft Graph payload under ms_graph; a Google Calendar payload under google_calendar. Profiles narrow what goes in that key. There is no separate extensions slot.

Payload reuse — where a mature vocabulary exists, reuse it: JMAP for email, jCal for calendar, jCard for contacts, FHIR for health, ISO 20022 for payments.

Profile file

A profile pins one core intent and narrows its payload for a specific service.

{
  "$id": "https://intentschema.org/profiles/com.google.gmail/communication.email.message.send.v1.json",
  "id": "org.intentschema.communication.email.message.send.v1@com.google.gmail.v1",
  "pins": "https://intentschema.org/intents/communication/email/message/send/v1.json",
  "title": "Gmail email send profile",
  "description": "Gmail-specific constraints and extensions.",
  "constraints": { "...": "JSON Schema differential applied on top of the core" }
}

Rules:

Versioning

Future considerations

Deliberately out of scope for the first cut. Listed so contributors don't over-engineer the core.

Prior art