Yardrail Extensions
Yardrail extends CWL v1.2 with custom step classes, an input type, and a requirement, all
under the yr: namespace (https://yardrail.com/cwl#). The extension schema is defined in
pkg/workflows/schema/yardrail-ext.yml.
Step Classes
Typed Connector Classes
Each connector's API operations are generated as individual CWL Process classes under a
per-connector namespace (e.g. https://yardrail.com/cwl/slack#,
https://yardrail.com/cwl/notion#). The class name matches the oapi-codegen operation name
from the connector's OpenAPI spec.
Namespace convention: https://yardrail.com/cwl/<connector>#
Examples:
slack:ChatPostMessageWithFormdataBodynotion:RetrieveADatabasecanva:CreateDesign
Inputs/Outputs: derived from the connector function's request/response schema. Declare
them as standard CWL inputs/outputs on the step's run: block.
Execution flow:
- The class IRI is resolved to a
{connectorID, function}pair via the generated class registry - Step inputs are JSON-marshaled as arguments
- Calls
Host.CallConnector(ctx, stepID, "connector.function", argsJSON) - In the worker, this becomes a Temporal Activity that fetches credentials via interlink and dispatches to the connector handler
- The JSON response is unmarshaled as step outputs
Example:
$namespaces:
yr: "https://yardrail.com/cwl#"
slack: "https://yardrail.com/cwl/slack#"
steps:
send:
run:
class: slack:ChatPostMessageWithFormdataBody
inputs:
channel: string
text: string
outputs:
ts: string
channel: string
in:
channel: channel
text: message
out: [ts, channel]
yr:HumanApproval
Suspends workflow execution until a person approves it in the UI, or the timeout elapses.
Class-level fields:
| Field | Type | Required | Description |
|---|---|---|---|
eventType | string | yes | Event type of the approval (e.g. "order.review"); the API's resume call selects the open pause by it |
timeout | string | yes | ISO-8601 duration before the approval times out (e.g. "PT48H"); a timeout fails the run |
instructions | string | no | Markdown shown to the reviewer |
The step's label is the title shown to the reviewer; without one, the step ID is used.
Inputs: the step's own inputs are the review items shown to the reviewer, each named by
its input label. Wire them with in: like any other step input.
Outputs:
| Output | Type | Description |
|---|---|---|
decision | string | "approved" once a reviewer approves |
decision is the only output a HumanApproval step may declare; any other declared output
fails the step.
Example:
steps:
approve:
label: "Review the order summary"
run:
class: yr:HumanApproval
eventType: "order.review"
timeout: "PT48H"
instructions: |
Check the order count matches the shop dashboard, then approve.
inputs:
summary:
type: string
label: "Order summary"
outputs:
decision: string
in:
summary: draft/summary
out: [decision]
after:
run:
class: ExpressionTool
requirements:
InlineJavascriptRequirement: {}
inputs:
decision: string
outputs:
out: string
expression: '${return {"out": "decision: " + inputs.decision};}'
in:
decision: approve/decision
out: [out]
yr:Log
Emits a message to the workflow run's journal. No outputs.
Inputs:
| Input | Type | Description |
|---|---|---|
message | string | The message to log |
Execution: Calls Host.Log(ctx, message) → published as a run event via interlink →
visible in the run journal and SSE stream.
Example:
steps:
log_message:
run:
class: yr:Log
inputs:
message: string
outputs: []
in:
message: message
out: []
yr:Agent
A multi-turn agentic LLM step with optional tool calling. Sends a prompt to the org's configured inference backend, optionally dispatching tool calls to connectors in a loop.
Class-level fields:
| Field | Type | Required | Description |
|---|---|---|---|
system | string | yes | LLM system instructions |
tools | AgentTool[] | no | Tools the agent can call during its reasoning loop |
maxTurns | int | no | Maximum tool-call loop iterations (default: 20) |
outputSchema | JSON Schema | no | Schema the final answer must match. The step outputs the raw answer as text and the parsed object as output, and fails if the answer does not match |
The CWL loader reads the property names name and id inside outputSchema as CWL identifiers
and rejects the document; use other property names.
AgentTool can be defined two ways:
-
Typed class reference — just the
classfield. Name, description, connector, function, and parameters are derived from the connector schema automatically:tools:- class: slack:ChatPostMessageWithFormdataBody -
Manual definition — explicit
name,description,connector,function, andparameters(JSON Schema object):tools:- name: retrieve-a-databasedescription: "Get metadata of a Notion database"connector: notionfunction: retrieve-a-databaseparameters:properties:databaseId: { type: string }required: [databaseId]
Inputs: standard CWL inputs forwarded to the model as the user message.
Output: {"text": "..."} — the model's final response text.
Requires: a configured inference backend in the org.
yr:PublishToSite
Publishes the current run's file outputs to a Site, creating a new live version.
Inputs:
| Input | Type | Description |
|---|---|---|
site_id | string | The site to publish to |
Outputs:
| Output | Type | Description |
|---|---|---|
version_id | string | The created version's ID |
Execution: Calls Host.PublishToSite(ctx, siteID).
Example:
steps:
publish:
run:
class: yr:PublishToSite
inputs:
site_id: string
outputs:
version_id: string
in:
site_id: target_site
out: [version_id]
Input Types
yr:Connector
A connector port input — resolved at install/bind time, not supplied by the trigger caller.
ExtractInputFields() filters these out so the trigger-input modal only shows user-facing
inputs.
inputs:
slack:
type: yr:Connector
message:
type: string
In the example above, only message appears in the trigger modal.
Requirements
yr:TriggerRequirement
Declares what can start a workflow run.
Fields:
| Field | Type | Description |
|---|---|---|
triggers | Trigger[] | Array of trigger definitions |
Each Trigger has:
| Field | Type | Required | Description |
|---|---|---|---|
kind | enum | yes | yr:connector_event, yr:schedule, yr:webhook, or yr:manual |
connector | string | for connector_event | Connector ID that emits the event |
eventType | string | no | Event type to match |
schedule | string | for schedule | Cron expression or interval |
Example:
requirements:
yr:TriggerRequirement:
triggers:
- kind: yr:webhook
- kind: yr:schedule
schedule: "0 9 * * MON-FRI"
- kind: yr:manual
Host Interface
The workflow runtime delegates side effects to a Host interface implemented by the worker:
| Method | Purpose |
|---|---|
CallConnector(ctx, stepID, funcName, inputsJSON) | Dispatches a connector function call |
Log(ctx, message) | Emits a journal message |
Now(ctx) | Replay-safe current time |
NewID(ctx) | Replay-safe unique ID generation |
InferenceClient() | LLM backend for yr:Agent |
AgentStore() | SGP session store for yr:Agent |
RunID() | Current run's unique ID |
PublishToSite(ctx, siteID) | Publishes run outputs to a site, returns version ID |