Schema and types#

A provider’s schema is its contract with Orchard. It describes what configuration the provider accepts, what action types it handles, and what each action’s attributes and outputs look like. Orchard uses the schema to type-check scenarios at plan time before a single action runs.

ProviderSchema#

{
  "name": "stripe",
  "version": "0.3.0",
  "protocol": "1",
  "config": {
    "api_key": { "type": "string", "required": true, "description": "..." }
  },
  "actions": {
    "charge": { ... },
    "refund": { ... }
  }
}

ActionSchema#

{
  "description": "Execute a SQL statement and capture the first row",
  "attrs": {
    "query": { "type": "string", "required": true }
  },
  "outputs": { "type": "any" }
}

AttrSchema#

{
  "type": "string",
  "required": true,
  "default": "\"GET\"",
  "description": "HTTP method"
}

Type expressions#

Types are written as cty type expressions in string form:

Examples:

string
number
list(string)
map(number)
object({ id = number, name = string })
object({ status = number, body = string, headers = map(string) })
any

Omitting type entirely is equivalent to any.

Authoring the schema in HCL#

Orchard provides a schema authoring format in HCL so you don’t hand-write JSON. Save it as schema.hcl, parse it with protocol.ParseHCLSchema, and emit it as JSON from your schema subcommand.

provider "stripe" {
  version  = "0.3.0"
  protocol = "1"
  description = "Stripe payments provider"

  config {
    attribute "api_key" {
      type        = string
      required    = true
      description = "Stripe secret key"
    }
    attribute "api_version" {
      type        = string
      default     = "2023-10-16"
      description = "Stripe API version header"
    }
  }

  action "charge" {
    description = "Create a charge against a customer"

    attribute "amount" {
      type     = number
      required = true
    }
    attribute "currency" {
      type     = string
      required = true
    }
    attribute "customer" {
      type     = string
      required = true
    }

    output {
      type = object({
        id     = string,
        status = string,
        amount = number,
      })
    }
  }
}

The HCL form is equivalent to the JSON form and round-trips through the same ProviderSchema struct.

Cty values on the wire#

Attributes and outputs are sent as JSON-encoded cty values, not raw JSON. The difference matters for types that don’t have a direct JSON analog (numbers preserve full precision, null is distinct from missing, object attributes are declared rather than inferred).

For most providers the distinction is invisible — strings encode as JSON strings, numbers as JSON numbers, booleans as JSON booleans. But when you need a canonical representation — especially for numbers or when round-tripping values — use pkg/protocol/ctyjson.go in Go, or mirror its behavior in other languages.

Wire example#

Given this action body:

action "charge" "test" {
  amount   = 1000
  currency = "usd"
  customer = "cus_123"
}

Orchard sends:

{
  "id": 3,
  "method": "execute",
  "params": {
    "action": "charge",
    "attrs": {
      "amount":   "1000",
      "currency": "\"usd\"",
      "customer": "\"cus_123\""
    }
  }
}

Each value in attrs is a separately JSON-encoded cty value. The provider decodes them back into typed values using the declared schema types.

Defaults and coercion#

When a scenario omits an attribute that has a default, Orchard fills in the default before calling execute. The provider sees the value every time; it doesn’t need default-handling logic.

Coercion also happens before dispatch. If the schema declares type = number and the scenario passes a string-typed variable, Orchard attempts coercion and fails at plan time if the value can’t be converted. The provider receives well-typed values.

Outputs#

The outputs field of an action schema declares the shape of the object the action returns. Actions always produce objects at runtime (keyed by attribute name), so the declared output type must be either any or a concrete object({...}). List, scalar, and map declarations are rejected at schema load.

Prefer a concrete object({...}) whenever the shape is fixed — scenario authors get plan-time errors on typos instead of runtime failures.

Validation#

ProviderSchema.Validate() in pkg/protocol/schema.go checks the schema for self-consistency. Non-Go providers should implement equivalent checks before serving their schema, or Orchard will reject them at handshake time:

• name, version, and protocol are non-empty.
• protocol matches the Orchard ProtocolVersion.
• At least one action is declared.
• Every type expression in config, action attrs, and outputs parses as a valid cty type.