Canonical verbs

What it is

Every vendor names the same operation differently: "create ticket", "add incident", "new service request", POST /tickets. A canonical verb gives that operation one name in three parts: a domain (service, finance, crm), an object (ticket, invoice, contact) and an operation (create, list, get, update, delete, and others).

The idea is related to resource-oriented API design. Google's AIP-121 says a small number of standard methods (Get, List, Create, Update, Delete) provide the semantics for most common operations. Canonical verbs apply that idea across vendors instead of within one API.

Why it matters

An agent that knows service.ticket.create can open a ticket in whichever help desk is connected without learning each vendor's vocabulary. It also lets a platform answer "which connected systems can do this?" and lets permissions be written once: allow service.ticket.create, not twenty-two vendor-specific names.

How it works

1. Each action in each connector is tagged with a verb from a shared registry.
2. An agent searches by verb, or by plain language, to find matching actions.
3. A write must name the system it goes to. A read can be sent to every connected system that implements it at once.
4. Each action keeps its vendor's own input schema; the verb names the operation, not the fields.

Example

crm.contact.list with no service named runs against every connected CRM that implements it and returns the results grouped by service. service.ticket.create with service: "halopsa" creates one ticket in HaloPSA.

Common pitfalls

• Same name, different inputs. A canonical verb does not mean identical arguments; read the action's schema before calling.
• Fanning out writes. Creating an invoice in every connected system at once is never what anyone wants.
• Verbs too broad to mean anything. do.thing helps nobody; a verb needs an object and an operation a person recognises.

How actionlake handles it

The actionlake registry defines 8,083 verbs. Connectors use 4,936 of them, and 3,353 are shared by two or more connectors. One name reaches many systems: service.ticket.create 54 connectors, finance.invoice.list 101, finance.invoice.create 74, crm.company.list 162 and crm.contact.list 177 (counted from our service files, 24 October 2026). find_actions filters by verb. A read verb with no service named fans out to every connected system that implements it, as one grouped run with one intent; writes are never fanned out. Keys can allow a verb rather than a vendor action. See the connectors.