Protocol Schema
- Schema Viewer
- Schema Source
Loading ....
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Message",
"oneOf": [
{
"$ref": "#/$defs/MethodRequest"
},
{
"$ref": "#/$defs/MethodSuccess"
},
{
"$ref": "#/$defs/MethodError"
},
{
"$ref": "#/$defs/Notification"
}
],
"description": "The messages supported by the Stepflow protocol. These correspond to JSON-RPC 2.0 messages.",
"$defs": {
"JsonRpc": {
"type": "string",
"description": "The version of the JSON-RPC protocol.",
"default": "2.0",
"const": "2.0"
},
"RequestId": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer",
"format": "int64"
}
],
"description": "The identifier for a JSON-RPC request. Can be either a string or an integer.\nThe RequestId is used to match method responses to corresponding requests.\nIt should not be set on notifications."
},
"Method": {
"type": "string",
"enum": [
"initialize",
"initialized",
"components/list",
"components/info",
"components/execute",
"components/infer_schema",
"blobs/put",
"blobs/get",
"runs/submit",
"runs/get"
]
},
"Value": {
"allOf": [],
"description": "Any JSON value (object, array, string, number, boolean, or null)"
},
"MethodRequest": {
"type": "object",
"description": "Request to execute a method.",
"required": [
"id",
"method"
],
"properties": {
"jsonrpc": {
"$ref": "#/$defs/JsonRpc"
},
"id": {
"$ref": "#/$defs/RequestId"
},
"method": {
"$ref": "#/$defs/Method",
"description": "The method being called."
},
"params": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/Value",
"description": "The parameters for the method call. Set on method requests."
}
]
}
}
},
"Error": {
"type": "object",
"description": "An error returned from a method execution.",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "A numeric code indicating the error type."
},
"message": {
"type": "string",
"description": "Concise, single-sentence description of the error."
},
"data": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/Value",
"description": "Primitive or structured value that contains additional information about the error."
}
]
}
}
},
"MethodError": {
"type": "object",
"required": [
"id",
"error"
],
"properties": {
"jsonrpc": {
"$ref": "#/$defs/JsonRpc"
},
"id": {
"$ref": "#/$defs/RequestId"
},
"error": {
"$ref": "#/$defs/Error",
"description": "An error that occurred during method execution."
}
}
},
"MethodResponse": {
"oneOf": [
{
"$ref": "#/$defs/MethodSuccess"
},
{
"$ref": "#/$defs/MethodError"
}
],
"description": "Response to a method request. This is an untagged union - success responses have a 'result' field while error responses have an 'error' field."
},
"MethodSuccess": {
"type": "object",
"description": "The result of a successful method execution.",
"required": [
"id",
"result"
],
"properties": {
"jsonrpc": {
"$ref": "#/$defs/JsonRpc"
},
"id": {
"$ref": "#/$defs/RequestId"
},
"result": {
"$ref": "#/$defs/Value",
"description": "The result of a successful method execution."
}
}
},
"Notification": {
"type": "object",
"description": "A JSON-RPC notification message. Unlike requests, notifications do not have an 'id' field and do not expect a response. They are used for one-way communication.",
"required": [
"method"
],
"properties": {
"jsonrpc": {
"type": "string",
"description": "The version of the JSON-RPC protocol.",
"default": "2.0",
"const": "2.0"
},
"method": {
"description": "The notification method being called."
},
"params": {
"oneOf": [
{
"type": "null"
},
{
"allOf": [],
"description": "Any JSON value (object, array, string, number, boolean, or null)"
}
],
"description": "The parameters for the notification."
}
}
},
"ObservabilityContext": {
"type": "object",
"description": "Observability context for distributed tracing and logging.\n\nThis context is passed with protocol requests to enable trace correlation\nand structured logging across the Stepflow runtime and component servers.\n\n# Field Presence\n\n- `trace_id` and `span_id`: Present when tracing is enabled, None otherwise\n- `run_id` and `flow_id`: Present for workflow execution requests, None for init/discovery\n- `step_id`: Present for step-level execution, None for workflow-level operations",
"properties": {
"trace_id": {
"type": [
"string",
"null"
],
"description": "OpenTelemetry trace ID (128-bit, hex encoded).\n\nPresent when tracing is enabled, None otherwise.\nUsed to correlate all operations within a single trace."
},
"span_id": {
"type": [
"string",
"null"
],
"description": "OpenTelemetry span ID (64-bit, hex encoded).\n\nUsed to establish parent-child span relationships.\nComponent servers should use this as the parent span when creating their spans."
},
"run_id": {
"type": [
"string",
"null"
],
"description": "The ID of the workflow run.\n\nPresent for workflow execution requests, None for initialization/discovery.\nUsed for filtering logs and associating operations with specific workflow runs."
},
"flow_id": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/BlobId",
"description": "The ID of the flow being executed.\n\nPresent for workflow execution requests, None for initialization/discovery.\nUsed for filtering logs and understanding which workflow is being executed."
}
]
},
"step_id": {
"type": [
"string",
"null"
],
"description": "The ID of the step being executed.\n\nPresent for step-level execution, None for workflow-level operations.\nUsed for filtering logs and associating operations with specific workflow steps."
}
}
},
"BlobId": {
"type": "string",
"description": "A SHA-256 hash of the blob content, represented as a hexadecimal string."
},
"InitializeParams": {
"type": "object",
"description": "Sent from Stepflow to the component server to begin the initialization process.",
"required": [
"runtime_protocol_version"
],
"properties": {
"runtime_protocol_version": {
"type": "integer",
"format": "int32",
"description": "Maximum version of the protocol being used by the Stepflow runtime.",
"minimum": 0
},
"observability": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/ObservabilityContext",
"description": "Observability context for tracing initialization (trace context only, no flow/run)."
}
]
}
}
},
"InitializeResult": {
"type": "object",
"description": "Sent from the component server back to Stepflow with the result of initialization.\nThe component server will not be initialized until it receives the `initialized` notification.",
"required": [
"server_protocol_version"
],
"properties": {
"server_protocol_version": {
"type": "integer",
"format": "int32",
"description": "Version of the protocol being used by the component server.",
"minimum": 0
}
}
},
"Initialized": {
"type": "object",
"description": "Sent from Stepflow to the component server after initialization is complete."
},
"Component": {
"type": "string",
"description": "Identifies a specific plugin and atomic functionality to execute. Use component name for builtins (e.g., 'eval') or path format for plugins (e.g., '/python/udf').",
"examples": [
"/builtin/eval",
"/mcpfs/list_files",
"/python/udf"
]
},
"ComponentExecuteParams": {
"type": "object",
"description": "Sent from Stepflow to the component server to execute a specific component with the provided input.",
"required": [
"component",
"input",
"attempt",
"observability"
],
"properties": {
"component": {
"$ref": "#/$defs/Component",
"description": "The component to execute."
},
"input": {
"$ref": "#/$defs/Value",
"description": "The input to the component."
},
"attempt": {
"type": "integer",
"format": "int32",
"description": "The attempt number for this execution (1-based, for retry logic).",
"minimum": 0
},
"observability": {
"$ref": "#/$defs/ObservabilityContext",
"description": "Observability context for tracing and logging."
}
}
},
"ComponentExecuteResult": {
"type": "object",
"description": "Sent from the component server back to Stepflow with the result of the component execution.",
"required": [
"output"
],
"properties": {
"output": {
"$ref": "#/$defs/Value",
"description": "The result of the component execution."
}
}
},
"ComponentInfoParams": {
"type": "object",
"description": "Sent from Stepflow to the component server to request information about a specific component.",
"required": [
"component"
],
"properties": {
"component": {
"$ref": "#/$defs/Component",
"description": "The component to get information about."
}
}
},
"ComponentInfo": {
"type": "object",
"required": [
"component"
],
"properties": {
"component": {
"$ref": "#/$defs/Component",
"description": "The component ID."
},
"description": {
"type": [
"string",
"null"
],
"description": "Optional description of the component."
},
"input_schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/Schema",
"description": "The input schema for the component.\n\nCan be any valid JSON schema (object, primitive, array, etc.)."
}
]
},
"output_schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/Schema",
"description": "The output schema for the component.\n\nCan be any valid JSON schema (object, primitive, array, etc.)."
}
]
}
}
},
"Schema": {
"type": "object",
"description": "A valid JSON Schema object."
},
"ComponentInfoResult": {
"type": "object",
"description": "Sent from the component server back to Stepflow with information about the requested component.",
"required": [
"info"
],
"properties": {
"info": {
"$ref": "#/$defs/ComponentInfo",
"description": "Information about the component."
}
}
},
"ComponentListParams": {
"type": "object",
"description": "Sent from Stepflow to the component server to request a list of all available components."
},
"ListComponentsResult": {
"type": "object",
"description": "Sent from the component server back to Stepflow with a list of all available components.",
"required": [
"components"
],
"properties": {
"components": {
"type": "array",
"items": {
"$ref": "#/$defs/ComponentInfo"
},
"description": "A list of all available components."
}
}
},
"ComponentInferSchemaParams": {
"type": "object",
"description": "Sent from Stepflow to the component server to infer the output schema for a component\ngiven an input schema. This enables static type checking of workflows.",
"required": [
"component",
"input_schema"
],
"properties": {
"component": {
"$ref": "#/$defs/Component",
"description": "The component to infer the schema for."
},
"input_schema": {
"$ref": "#/$defs/Schema",
"description": "The schema of the input that will be provided to the component."
}
}
},
"ComponentInferSchemaResult": {
"type": "object",
"description": "Sent from the component server back to Stepflow with the inferred output schema.",
"properties": {
"output_schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/Schema",
"description": "The inferred output schema, or None if the component cannot determine it."
}
]
}
}
},
"GetBlobParams": {
"type": "object",
"description": "Sent from the component server to the Stepflow to retrieve the content of a specific blob.",
"required": [
"blob_id"
],
"properties": {
"blob_id": {
"$ref": "#/$defs/BlobId",
"description": "The ID of the blob to retrieve."
},
"observability": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/ObservabilityContext",
"description": "Observability context for tracing bidirectional calls."
}
]
}
}
},
"BlobType": {
"type": "string",
"description": "Type of blob stored in the blob store.",
"enum": [
"flow",
"data"
]
},
"GetBlobResult": {
"type": "object",
"description": "Sent from the Stepflow back to the component server with the blob data and metadata.",
"required": [
"data",
"blob_type"
],
"properties": {
"data": {
"$ref": "#/$defs/Value"
},
"blob_type": {
"$ref": "#/$defs/BlobType"
}
}
},
"PutBlobParams": {
"type": "object",
"description": "Sent from the component server to the Stepflow to store a blob with the provided content.",
"required": [
"data",
"blob_type"
],
"properties": {
"data": {
"$ref": "#/$defs/Value"
},
"blob_type": {
"$ref": "#/$defs/BlobType"
},
"observability": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/ObservabilityContext",
"description": "Observability context for tracing bidirectional calls."
}
]
}
}
},
"PutBlobResult": {
"type": "object",
"description": "Sent from the Stepflow back to the component server with the ID of the stored blob.",
"required": [
"blob_id"
],
"properties": {
"blob_id": {
"$ref": "#/$defs/BlobId"
}
}
},
"WorkflowOverrides": {
"type": "object",
"description": "Workflow overrides that can be applied to modify step behavior at runtime.\n\nOverrides are keyed by step ID and contain merge patches or other transformation\nspecifications to modify step properties before execution.",
"required": [
"steps"
],
"properties": {
"steps": {
"type": "object",
"description": "Map of step ID to override specification",
"additionalProperties": {
"$ref": "#/$defs/StepOverride"
},
"propertyNames": {
"type": "string"
}
}
}
},
"StepOverride": {
"type": "object",
"description": "Override specification for a single step.\n\nContains the override type (merge patch, json patch, etc.) and the value\nto apply. The type field uses `$type` to avoid collisions with step properties.",
"required": [
"value"
],
"properties": {
"$type": {
"$ref": "#/$defs/OverrideType",
"description": "The type of override to apply. Defaults to \"merge_patch\" if not specified."
},
"value": {
"description": "The override value to apply, interpreted based on the override type."
}
}
},
"OverrideType": {
"type": "string",
"description": "The type of override operation to perform.",
"enum": [
"merge_patch",
"json_patch"
]
},
"SubmitRunProtocolParams": {
"type": "object",
"description": "Parameters for submitting a run via the protocol.",
"required": [
"flowId",
"inputs"
],
"properties": {
"flowId": {
"$ref": "#/$defs/BlobId",
"description": "The ID of the flow to execute (blob ID)."
},
"inputs": {
"type": "array",
"items": {
"$ref": "#/$defs/Value"
},
"description": "Input values for each item in the run."
},
"wait": {
"type": "boolean",
"description": "If true, wait for completion before returning."
},
"maxConcurrency": {
"type": [
"integer",
"null"
],
"description": "Maximum number of concurrent executions.",
"minimum": 0
},
"overrides": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/WorkflowOverrides",
"description": "Optional workflow overrides to apply."
}
]
},
"observability": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/ObservabilityContext",
"description": "Observability context for tracing."
}
]
}
}
},
"ResultOrder": {
"type": "string",
"description": "Order in which to return results.",
"enum": [
"by_index",
"by_completion"
]
},
"GetRunProtocolParams": {
"type": "object",
"description": "Parameters for getting a run via the protocol.",
"required": [
"runId"
],
"properties": {
"runId": {
"type": "string",
"description": "The run ID to query."
},
"wait": {
"type": "boolean",
"description": "If true, wait for run completion before returning."
},
"includeResults": {
"type": "boolean",
"description": "If true, include item results in the response."
},
"resultOrder": {
"$ref": "#/$defs/ResultOrder",
"description": "Order of results (byIndex or byCompletion)."
},
"observability": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/ObservabilityContext",
"description": "Observability context for tracing."
}
]
}
}
},
"ItemStatistics": {
"type": "object",
"description": "Statistics about items in a run.",
"required": [
"total",
"completed",
"running",
"failed",
"cancelled"
],
"properties": {
"total": {
"type": "integer",
"description": "Total number of items in this run.",
"minimum": 0
},
"completed": {
"type": "integer",
"description": "Number of completed items.",
"minimum": 0
},
"running": {
"type": "integer",
"description": "Number of currently running items.",
"minimum": 0
},
"failed": {
"type": "integer",
"description": "Number of failed items.",
"minimum": 0
},
"cancelled": {
"type": "integer",
"description": "Number of cancelled items.",
"minimum": 0
}
}
},
"ItemResult": {
"type": "object",
"description": "Result for an individual item in a multi-item run.",
"required": [
"itemIndex",
"status"
],
"properties": {
"itemIndex": {
"type": "integer",
"description": "Index of this item in the input array (0-based).",
"minimum": 0
},
"status": {
"$ref": "#/$defs/ExecutionStatus",
"description": "Execution status of this item."
},
"result": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/FlowResult",
"description": "Result of this item, if completed."
}
]
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When this item completed (if completed)."
}
}
},
"ExecutionStatus": {
"type": "string",
"description": "Status of a workflow execution",
"enum": [
"running",
"completed",
"failed",
"cancelled",
"paused"
]
},
"FlowResult": {
"oneOf": [
{
"$ref": "#/$defs/FlowResultSuccess"
},
{
"$ref": "#/$defs/FlowResultFailed"
}
],
"title": "FlowResult",
"description": "The results of a step execution.",
"discriminator": {
"propertyName": "outcome",
"mapping": {
"failed": "#/$defs/FlowResultFailed",
"success": "#/$defs/FlowResultSuccess"
}
}
},
"FlowError": {
"type": "object",
"description": "An error reported from within a flow or step.",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"format": "int64"
},
"message": {
"type": "string"
},
"data": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/Value"
}
]
}
}
},
"FlowResultSuccess": {
"type": "object",
"title": "FlowResultSuccess",
"description": "The step execution was successful.",
"required": [
"outcome",
"result"
],
"properties": {
"outcome": {
"type": "string",
"title": "FlowOutcome",
"default": "success",
"const": "success"
},
"result": {
"$ref": "#/$defs/Value"
}
}
},
"FlowResultFailed": {
"type": "object",
"title": "FlowResultFailed",
"description": "The step failed with the given error.",
"required": [
"outcome",
"error"
],
"properties": {
"outcome": {
"type": "string",
"title": "FlowOutcome",
"default": "failed",
"const": "failed"
},
"error": {
"$ref": "#/$defs/FlowError"
}
}
},
"RunStatusProtocol": {
"type": "object",
"description": "Run status returned by the protocol (serializable version of RunStatus).",
"required": [
"runId",
"flowId",
"status",
"items",
"createdAt"
],
"properties": {
"runId": {
"type": "string"
},
"flowId": {
"$ref": "#/$defs/BlobId"
},
"flowName": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"items": {
"$ref": "#/$defs/ItemStatistics"
},
"createdAt": {
"type": "string"
},
"completedAt": {
"type": [
"string",
"null"
]
},
"results": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/ItemResult"
}
}
}
},
"Message": {
"oneOf": [
{
"$ref": "#/$defs/MethodRequest"
},
{
"$ref": "#/$defs/MethodSuccess"
},
{
"$ref": "#/$defs/MethodError"
},
{
"$ref": "#/$defs/Notification"
}
],
"description": "The messages supported by the Stepflow protocol. These correspond to JSON-RPC 2.0 messages."
}
}
}