Build an extension
An Ormuz extension is a public contract made of declared contributions. Start from the business responsibilities and required exchanges, then expose only the primitives that serve a durable use case.
An extension's surfaces
| Surface | Role |
|---|---|
| Manifest | Describes the extension's identity, type, cardinality, activation, capabilities, and contributions. |
| Configuration | Declares the values a merchant must provide and the secrets it owns. |
| Channels | Declares the supported API or event exchanges in each direction. |
| External objects | Exposes typed representations of the partner system without confusing them with platform objects. |
| Nodes | Exposes explicit operations intended to be composed in a process. |
| Agent tools | Exposes agent-facing capabilities designed independently from the node catalog. |
| Events | Exposes external occurrences that can be used as process triggers or context. |
| User Journey actions | Provides participant-facing UI or a provider redirect that is loaded only when the action becomes current. |
| Process templates | Separately distributes a reusable process composition that declares the extensions and configurations it depends on. |
An extension does not need to fill every one of these surfaces. Each additional contribution increases its maintenance contract, documentation, and review surface. Process templates are marketplace artifacts associated with extensions through their prerequisites; they are not embedded contributions in spec.contributes.
Recommended design order
Define the extension's role
Identify the system or service connected to Ormuz, the facts it owns, and the expected business outcomes.
Declare the manifest
Choose the type, cardinality, activation, integration mechanisms, and contributions that are actually supported.
Choose the channels
Determine who initiates each exchange and who owns the contract: outbound API, inbound API, inbound event, or outbound event.
Model the data
Separate external objects, platform objects, drafts, and mappings before defining mutations.
Add the required contributions
Introduce only the nodes, Tools, events, or User Journey actions that justify a maintained contract and whose responsibilities can be verified explicitly.
Boundaries to preserve
- The manifest describes capabilities; it must not carry secrets.
- An external object is not automatically a platform object.
- A mapping does not create new business authority.
- A node does not grant a permission simply because it exists in the catalog.
- A Tool is not automatically derived from a node or an API endpoint.