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 toworkflows/, or via the storage serviceGET/PUT /internal/triggerswhen the orchestrator usesORCH_RUNTIME_STORE=http. - Each trigger document has at least:
name,target_workflow(workflow name), andinvocation(same structure as the workflow’sinvocationblock). - Many triggers may share the same
target_workflow(e.g. one HTTP entry and one schedule entry for the same flow). The orchestrator merges theirinvocationvalues at load (union of types and HTTP methods, first-wins for other fields). - The matching workflow file should omit top-level
invocationwhen all start behaviour is defined in trigger documents (otherwise inlineinvocationis overridden with a warning).
UI Ownership Rules (Important)¶
To keep responsibilities separated:
- Icons must be owned by service/capability metadata.
- Descriptions must be owned by service/capability metadata.
- Dashboard should only render metadata and apply neutral fallback values.
- Dashboard must not infer product-specific icon choices from capability names.
Recommended UI fallback order for icon:
metadata.designer.icon/metadata.designer.icon_emoji- capability
icon/icon_emoji - capability
metadata.icon/metadata.icon_emoji - service
icon/icon_emoji - service
metadata.icon/metadata.icon_emoji - neutral fallback (for example
⚡)
Recommended UI fallback order for description:
metadata.designer.description- capability
description - capability
summary - capability
metadata.description - service
description - service
summary - service
metadata.description - 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
descriptionfor service and each capability. - Provide icon metadata (
iconoricon_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_typeorvariants[]. - Provide
form_fieldsandyaml_pathfor 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.
Related Documents¶
- Integration end-to-end
- Add a Capability Provider (Python / Go / C#)
- Capability provider deploy integration
- Capability registry and extensibility (historisch)
- Capability registry implementation plan (historisch)
- Workflow YAML
- Internal template (historical):
internal/capability-provider-template.md