Skip to content

Capability Provider Contract

Canonical contract for services that register capabilities in MeshFlows. Platform engineers add providers; workflows call them through service_call — without hardcoding each integration into the Orchestrator.

Start here if you want working code: Add a Capability Provider (Python, Go, and C#). This page is the field-level spec (registration payload, designer metadata, UI ownership).

Use this when implementing or reviewing any provider that publishes trigger, workflow_step, or workflow_connection capabilities.

Scope

This contract defines:

  • service registration payload shape
  • capability metadata conventions
  • dashboard designer metadata (metadata.designer)
  • icon and description ownership (provider-owned)

Out of scope:

  • transport/runtime details of each capability implementation
  • orchestration semantics for built-in step types
  • language-specific scaffolding — see the examples howto

Service Registration Contract

Providers register through the capability registry endpoint:

  • POST /v1/registry/services/register

Minimum service-level fields:

Field Required Type Notes
service_name yes string Stable service identifier
service_type yes string Usually provider
service_url yes string Base URL reachable by internal consumers
capabilities yes array At least one capability

Recommended service-level optional fields:

Field Required Type Notes
description no string Short service description for UI and catalog
icon no string Provider-owned icon (URL, emoji, or agreed token)
icon_emoji no string Optional explicit emoji icon
metadata.description no string Fallback description
metadata.icon no string Fallback icon
metadata.icon_emoji no string Fallback icon emoji
metadata.cluster_health no object Dashboard Cluster Health options (see below)

Cluster Health (metadata.cluster_health)

Service-level metadata read by the dashboard Cluster Health panel:

Field Default Notes
check_version true Set false for external providers not on MeshFlows image pins
required false When true, failure marks overall cluster health unhealthy
health_path /healthz Override probe path
ready_path /readyz Override probe path

Registering with a reachable service_url is enough for visibility. Providers outside the MeshFlows build/product pin should normally use "check_version": false. Alternatives and env extras: Dashboard — Cluster Health, Deploy integration.

Capability Contract

Each capability in capabilities[]:

Field Required Type Notes
name yes string Unique capability name, e.g. gateway.http_trigger
version yes string Semver
kind yes string trigger, workflow_step, workflow_connection, or other kinds (Engine egress services often use egress for step capabilities). service_call resolves by name + version; kind is for catalog/filters
description yes string Human-readable short description
metadata no object Extension bucket for schemas, routes, designer metadata

Recommended capability optional fields:

Field Required Type Notes
summary no string Additional short text used by UI fallback
icon no string Capability-specific icon
icon_emoji no string Capability-specific icon emoji
metadata.icon no string Fallback icon
metadata.icon_emoji no string Fallback icon emoji
metadata.description no string Fallback description

Designer Metadata Contract (metadata.designer)

For capabilities shown in dashboard wizard/pickers, provide metadata.designer.

Common fields:

Field Required Type Notes
display_name yes string Label shown in picker cards
category no string Grouping label in picker
description recommended string Short description shown in picker cards
icon recommended string Designer-specific icon override
icon_emoji recommended string Designer-specific icon emoji override
form_fields conditional array Dynamic fields for trigger/step configuration

Trigger-only fields:

Field Required Type Notes
invocation_type yes string Value for workflow invocation.type

Workflow-step-only fields:

Field Required Type Notes
step_type yes* string Value for YAML step.type
variants optional array Alternative to single step_type; each variant defines step_type, display_name, and optionally description, icon, icon_emoji, form_fields

*Required when variants is not used.

Workflow scoped declarations (metadata.designer.scoped_declarations)

For providers that materialize workflow-level variable slots (scoped_context.variables in workflow YAML), the service may publish a machine-readable declaration schema so the dashboard designer can render tables or forms without hard-coding field lists (ADR 0001).

Field Required Type Notes
schema_version recommended integer Increment when the shape of variable_row or provider_block changes
description no string Human-readable purpose
aligns_with no string Free-text pointer (e.g. Pydantic model name or doc anchor)
variable_row yes object JSON-Schema-shaped description of one scoped_context.variables[] element (name, type, optional init)
provider_block no object JSON-Schema-shaped description of scoped_context.provider

Consumers (dashboard) should treat unknown keys as forward-compatible. Version negotiation is schema_version plus provider semver on the registering service.

Example (conceptual):

{
  "metadata": {
    "designer": {
      "scoped_declarations": {
        "schema_version": 1,
        "description": "Variable rows for workflow scoped_context when backed by variables.service",
        "variable_row": {
          "type": "object",
          "required": ["name", "type"],
          "properties": {
            "name": { "type": "string" },
            "type": { "type": "string" },
            "init": {
              "type": "object",
              "properties": { "value": {} }
            }
          }
        },
        "provider_block": {
          "type": "object",
          "required": ["service_name"],
          "properties": {
            "service_name": { "type": "string" },
            "capability_hint": { "type": "string" },
            "version": { "type": "string" }
          }
        }
      }
    }
  }
}

Publish scoped_declarations on the service registration payload (metadata.designer) unless your product convention attaches it to a specific capability (both are acceptable if documented).

form_fields Contract

Each form field object:

Key Required Type Notes
name yes string Unique key in form
label yes string Visible label
type yes string text, textarea, number, boolean, select, code, keyvalue, connection
required no boolean Required flag
default no any Default value
options select only array[string] Allowed options
placeholder no string Input hint
yaml_path recommended string Dot path on the workflow step object (flat first-class field)
body_key no string JSON key in the provider POST body when it differs from yaml_path (e.g. YAML request_timeout_seconds → body timeout_seconds)
help no string Explains what the field/option does in the provider

Designer compose hints (metadata.designer)

Key Notes
compose_payload_from_fields false = dashboard writes flat yaml_path fields on the step; orchestrator builds the POST JSON from those fields
compose_mode fields (default), script_execute (SES envelope), or smtp (email list + attachment encoding)
payload_from_body_key Where payload_from is merged (body, message, input, xml, …)

The orchestrator does not declare provider-specific fields on ServiceCallWorkflowStep. Flat YAML keys are kept as model extras and composed via this registry metadata.

Runtime trigger documents (orchestrator)

This is not the same object as a capability registry entry: it is the runtime start contract that points at a workflow.

  • Triggers are stored as separate YAML/JSON files in a triggers/ directory next to workflows/, or via the storage service GET/PUT /internal/triggers when the orchestrator uses ORCH_RUNTIME_STORE=http.
  • Each trigger document has at least: name, target_workflow (workflow name), and invocation (same structure as the workflow’s invocation block).
  • Many triggers may share the same target_workflow (e.g. one HTTP entry and one schedule entry for the same flow). The orchestrator merges their invocation values at load (union of types and HTTP methods, first-wins for other fields).
  • The matching workflow file should omit top-level invocation when all start behaviour is defined in trigger documents (otherwise inline invocation is overridden with a warning).

UI Ownership Rules (Important)

To keep responsibilities separated:

  1. Icons must be owned by service/capability metadata.
  2. Descriptions must be owned by service/capability metadata.
  3. Dashboard should only render metadata and apply neutral fallback values.
  4. Dashboard must not infer product-specific icon choices from capability names.

Recommended UI fallback order for icon:

  1. metadata.designer.icon / metadata.designer.icon_emoji
  2. capability icon / icon_emoji
  3. capability metadata.icon / metadata.icon_emoji
  4. service icon / icon_emoji
  5. service metadata.icon / metadata.icon_emoji
  6. neutral fallback (for example ⚡)

Recommended UI fallback order for description:

  1. metadata.designer.description
  2. capability description
  3. capability summary
  4. capability metadata.description
  5. service description
  6. service summary
  7. service metadata.description
  8. neutral fallback (No description available.)

Example: Trigger Capability

{
  "service_name": "gateway",
  "service_type": "provider",
  "service_url": "http://gateway:8080",
  "description": "Gateway entrypoint capabilities.",
  "icon_emoji": "🌐",
  "capabilities": [
    {
      "name": "gateway.http_trigger",
      "version": "1.0.0",
      "kind": "trigger",
      "description": "HTTP trigger template for workflow entrypoints via gateway.",
      "metadata": {
        "designer": {
          "display_name": "Gateway HTTP Trigger",
          "category": "gateway",
          "invocation_type": "http",
          "description": "Receive HTTP requests and start the workflow.",
          "icon_emoji": "🌐",
          "form_fields": [
            { "name": "http_method", "label": "HTTP Method", "type": "select", "options": ["GET", "POST"], "default": "POST", "yaml_path": "http_method" }
          ]
        }
      }
    }
  ]
}

Example: Workflow connection capability

Providers that need credentials register a workflow_connection capability. The Dashboard uses metadata.designer.connection_type and form_fields; Orchestrator validates connection documents against registered connection types. Ship a matching file under flows/connections/ (see Connections reference).

{
  "name": "acme.connection",
  "version": "1.0.0",
  "kind": "workflow_connection",
  "summary": "Acme API key connection.",
  "description": "Declare under flows/connections or workflow connections[]; steps use connection: <name>.",
  "metadata": {
    "designer": {
      "category": "connections",
      "display_name": "Acme connection",
      "connection_type": "acme",
      "icon_emoji": "🔑",
      "yaml_scope": "workflow.connections[]",
      "connection_test": { "path": "/test", "method": "POST" },
      "form_fields": [
        { "name": "name", "label": "Connection id", "type": "text", "required": true, "yaml_path": "name" },
        {
          "name": "api_key",
          "label": "API key",
          "type": "password",
          "required": true,
          "secret": true,
          "yaml_path": "api_key",
          "placeholder": "$secret:acme-api-key"
        }
      ]
    }
  }
}

Matching connection document:

name: acme
type: acme
api_key: "$secret:acme-api-key"

End-to-end wiring: Integration end-to-end. Production-shaped reference: Egress Weatherstack (weatherstack.connection).

Example: Workflow Step Capability with Variants

{
  "name": "script.execute",
  "version": "1.2.0",
  "kind": "workflow_step",
  "description": "Execute scripts in supported runtimes.",
  "metadata": {
    "designer": {
      "category": "compute",
      "variants": [
        {
          "step_type": "script_js",
          "display_name": "Execute JavaScript",
          "description": "Run a JavaScript snippet in the JS runtime.",
          "icon_emoji": "🧩",
          "form_fields": [
            { "name": "script", "label": "Script", "type": "code", "required": true, "yaml_path": "script" }
          ]
        },
        {
          "step_type": "script_py",
          "display_name": "Execute Python",
          "description": "Run Python code in an isolated runtime.",
          "icon_emoji": "🐍",
          "form_fields": [
            { "name": "script", "label": "Script", "type": "code", "required": true, "yaml_path": "script" }
          ]
        }
      ]
    }
  }
}

Provider Implementation Checklist

  • Provide description for service and each capability.
  • Provide icon metadata (icon or icon_emoji) at least at one stable level (designer/capability/service).
  • For designer-exposed capabilities, provide metadata.designer.display_name.
  • For triggers, provide metadata.designer.invocation_type.
  • For workflow steps, provide metadata.designer.step_type or variants[].
  • Provide form_fields and yaml_path for all non-trivial inputs.
  • Keep semver in version.
  • Keep heartbeat and re-registration behavior compliant with registry expectations.

Egress deploy integration (registry-driven providers)

For standalone egress microservices discovered via service_call (no orchestrator EGRESS_*_URL env), follow Capability provider deploy integration.