Manifest and configuration
extension.yaml is the canonical declarative source of an extension package. It describes the identity and capabilities exposed by the package without executing partner behavior or containing credentials.
Resource Extension
The manifest follows a stable envelope:
apiVersion: ormuz.io/v1alpha1 kind: Extension metadata: name: acme_pay title: Acme Pay spec: version: 1.0.0 platformApiVersion: "1" defaultLocale: en-US supportedLocales: - en-US - fr-FR runtime: api: ./api/index.cjs extensionKind: provider_integration cardinality: multi activation: when: on_connection_test capabilities: - payment_processing integrationMechanisms: - rest_api channels: [] contributes: nodes: [] tools: []
apiVersion, kind, metadata.name and the required fields of spec are validated before the package can be loaded. Runtime projections of the manifest are generated from this source; they are not competing editable files.
Identity and namespaces
metadata.name is the extension's stable identifier. It uses lowercase snake_case, starts with a letter, and must be unique on the platform.
This identity also carries the namespace of contributions. For example, the extension stripe can contribute stripe.ensure_customer. The ormuz namespace is reserved for Core executables and cannot be used as an extension identifier.
Technical identifiers must not be renamed for presentation purposes. Use metadata.title and localized resources for user-facing labels.
Declarative contract
| Champ | Contrat actuel |
|---|---|
spec.version | Declared package version. |
spec.platformApiVersion | Target platform contract version. |
spec.defaultLocale / supportedLocales | Locales available for localized extension surfaces. |
spec.runtime | Runtimes actually provided by the package, for example API, node execution, or User Journey actions. |
spec.extensionKind | provider_integration, host_connector, or bundle. |
spec.cardinality | singleton or multi. |
spec.activation.when | on_install, on_connection_test, or manual. |
spec.capabilities | Business capabilities declared for discovery; they do not amount to permission. |
spec.integrationMechanisms | Technical mechanisms actually used, for example REST API or webhook. |
spec.channels | Supported API and event exchanges. |
spec.contributes | Contributions declared by the package, including nodes and Agent Tools. |
Cardinality describes how many configurations a merchant may create. Use singleton when only one configuration makes sense within a merchant scope, and multi when several distinct connections must be able to coexist.
Activation describes the condition under which the extension becomes operational. It represents neither a certification level, nor a commercial status, nor a data permission.
Runtime contracts and configuration
Not every public contract of an extension is necessarily serialized in extension.yaml. The manifest contains the package's structural facts; contracts that require code remain attached to the appropriate runtime.
The configSchema describes values specific to the merchant installation. Secrets provided by the merchant are declared there as secret and must never be copied into the manifest's public metadata.
- a configuration requests only the values required by the enabled channels and capabilities;
- secrets issued by Ormuz are not modeled as fields supplied by the merchant;
- a field referenced by a channel must be compatible with its use, for example a URL for a target
event_out; - execution, validation, normalization functions and provider clients remain runtime behavior, never declarative YAML.
Discovery metadata
The metadata spec.marketplace is used to present the extension and its prerequisites. It changes neither its authority nor its runtime behavior.
The current contract notably distinguishes an availability status (available, beta, coming_soon), an estimated setup effort, sandbox availability, publisher, highlights, use cases, prerequisites, and documentation resources.
Design rules
- Edit
extension.yaml, not its generated projections. - Declare current reality, not the roadmap.
- Do not duplicate a capability solely to improve the marketing of the listing.
- A capability is not a permission and creates no implicit access.
- A new contribution must enter contract validation before being documented as supported.
- After a structural change, regenerate projections and then run the preflight.