Orb Authoring Guide

An Orb is a self-contained capability unit: a manifest that declares what a provider does, what inputs it expects, what outputs it produces, and how to execute it via HTTP.

Orb manifest structure

Orb manifests are JSON files stored in manifests/ within an Operon deployment.

{
  "orb_id": "myorg.send-sms@1.0.0",
  "provider": "twilio",
  "description": "Send an SMS via Twilio",
  "inputs": {
    "to": { "type": "string", "required": true },
    "body": { "type": "string", "required": true },
    "from": { "type": "string", "required": false, "default": "{{orbiset.secrets.TWILIO_FROM}}" }
  },
  "outputs": {
    "message_sid": { "type": "string" },
    "status": { "type": "string" }
  },
  "execution": {
    "type": "http",
    "method": "POST",
    "url": "https://api.twilio.com/2010-04-01/Accounts/{{orbiset.secrets.TWILIO_ACCOUNT_SID}}/Messages.json",
    "headers": {
      "Content-Type": "application/x-www-form-urlencoded",
      "Authorization": "Basic {{orbiset.secrets.TWILIO_AUTH_TOKEN_B64}}"
    },
    "body_template": "To={{inputs.to}}&From={{inputs.from}}&Body={{inputs.body}}"
  },
  "swap_config": {
    "primary": "twilio",
    "fallbacks": ["vonage"],
    "strategy": "latency"
  }
}

Key fields

Field	Required	Description
orb_id	Yes	Unique identifier: {org}.{name}@{semver}
provider	Yes	The external service provider
inputs	Yes	Input parameter schema
outputs	Yes	Output parameter schema
execution	Yes	HTTP execution configuration
swap_config	No	Hot-swap configuration

Secret interpolation

Use {{orbiset.secrets.KEY_NAME}} in any execution field to reference secrets stored in the Tenant Secrets Vault.

Hot-swap configuration

See the Hot-Swap Guide for configuring zero-downtime provider swapping.

Publishing to the Marketplace

1. Validate your manifest against the CORO ontology
2. Run the full test suite
3. Submit via POST /marketplace/orbs/publish with your Orb manifest and test results

Your Orb will receive a certification tier badge based on its reputation score.