Protocol Schema
- Schema Viewer
- Schema Source
Loading ....
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Message",
"description": "The messages supported by the Stepflow protocol. These correspond to JSON-RPC 2.0 messages.\n\nNote that this defines a superset containing both client-sent and server-sent messages.",
"oneOf": [
{
"$ref": "#/$defs/MethodRequest"
},
{
"$ref": "#/$defs/MethodSuccess"
},
{
"$ref": "#/$defs/MethodError"
},
{
"$ref": "#/$defs/Notification"
}
],
"$defs": {
"MethodRequest": {
"description": "Request to execute a method.",
"type": "object",
"properties": {
"jsonrpc": {
"$ref": "#/$defs/JsonRpc",
"default": "2.0"
},
"id": {
"$ref": "#/$defs/RequestId"
},
"method": {
"description": "The method being called.",
"$ref": "#/$defs/Method"
},
"params": {
"title": "MethodParams",
"description": "The parameters for the method call. Set on method requests.",
"oneOf": [
{
"$ref": "#/$defs/InitializeParams"
},
{
"$ref": "#/$defs/ComponentExecuteParams"
},
{
"$ref": "#/$defs/ComponentInfoParams"
},
{
"$ref": "#/$defs/ComponentListParams"
},
{
"$ref": "#/$defs/GetBlobParams"
},
{
"$ref": "#/$defs/PutBlobParams"
},
{
"$ref": "#/$defs/EvaluateFlowParams"
},
{
"$ref": "#/$defs/GetFlowMetadataParams"
},
{
"$ref": "#/$defs/SubmitBatchParams"
},
{
"$ref": "#/$defs/GetBatchParams"
}
]
}
},
"required": [
"id",
"method",
"params"
]
},
"JsonRpc": {
"description": "The version of the JSON-RPC protocol.",
"type": "string",
"const": "2.0",
"default": "2.0"
},
"RequestId": {
"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.",
"anyOf": [
{
"type": "string"
},
{
"type": "integer",
"format": "int64"
}
]
},
"Method": {
"type": "string",
"enum": [
"initialize",
"initialized",
"components/list",
"components/info",
"components/execute",
"blobs/put",
"blobs/get",
"flows/evaluate",
"flows/get_metadata",
"flows/submit_batch",
"flows/get_batch"
]
},
"InitializeParams": {
"description": "Sent from Stepflow to the component server to begin the initialization process.",
"type": "object",
"properties": {
"runtime_protocol_version": {
"description": "Maximum version of the protocol being used by the Stepflow runtime.",
"type": "integer",
"format": "uint32",
"minimum": 0
},
"observability": {
"description": "Observability context for tracing initialization (trace context only, no flow/run).",
"anyOf": [
{
"$ref": "#/$defs/ObservabilityContext"
},
{
"type": "null"
}
]
}
},
"required": [
"runtime_protocol_version"
]
},
"ObservabilityContext": {
"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",
"type": "object",
"properties": {
"trace_id": {
"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.",
"type": [
"string",
"null"
]
},
"span_id": {
"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.",
"type": [
"string",
"null"
]
},
"run_id": {
"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.",
"type": [
"string",
"null"
]
},
"flow_id": {
"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.",
"anyOf": [
{
"$ref": "#/$defs/BlobId"
},
{
"type": "null"
}
]
},
"step_id": {
"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.",
"type": [
"string",
"null"
]
}
}
},
"BlobId": {
"description": "A SHA-256 hash of the blob content, represented as a hexadecimal string.",
"type": "string"
},
"ComponentExecuteParams": {
"description": "Sent from Stepflow to the component server to execute a specific component with the provided input.",
"type": "object",
"properties": {
"component": {
"description": "The component to execute.",
"$ref": "#/$defs/Component"
},
"input": {
"description": "The input to the component.",
"$ref": "#/$defs/Value"
},
"attempt": {
"description": "The attempt number for this execution (1-based, for retry logic).",
"type": "integer",
"format": "uint32",
"minimum": 0
},
"observability": {
"description": "Observability context for tracing and logging.",
"$ref": "#/$defs/ObservabilityContext"
}
},
"required": [
"component",
"input",
"attempt",
"observability"
]
},
"Component": {
"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').",
"type": "string",
"examples": [
"/builtin/eval",
"/mcpfs/list_files",
"/python/udf"
]
},
"Value": {
"description": "Any JSON value (object, array, string, number, boolean, or null)"
},
"ComponentInfoParams": {
"description": "Sent from Stepflow to the component server to request information about a specific component.",
"type": "object",
"properties": {
"component": {
"description": "The component to get information about.",
"$ref": "#/$defs/Component"
}
},
"required": [
"component"
]
},
"ComponentListParams": {
"description": "Sent from Stepflow to the component server to request a list of all available components.",
"type": "object"
},
"GetBlobParams": {
"description": "Sent from the component server to the Stepflow to retrieve the content of a specific blob.",
"type": "object",
"properties": {
"blob_id": {
"description": "The ID of the blob to retrieve.",
"$ref": "#/$defs/BlobId"
},
"observability": {
"description": "Observability context for tracing bidirectional calls.",
"anyOf": [
{
"$ref": "#/$defs/ObservabilityContext"
},
{
"type": "null"
}
]
}
},
"required": [
"blob_id"
]
},
"PutBlobParams": {
"description": "Sent from the component server to the Stepflow to store a blob with the provided content.",
"type": "object",
"properties": {
"data": {
"$ref": "#/$defs/Value"
},
"blob_type": {
"$ref": "#/$defs/BlobType"
},
"observability": {
"description": "Observability context for tracing bidirectional calls.",
"anyOf": [
{
"$ref": "#/$defs/ObservabilityContext"
},
{
"type": "null"
}
]
}
},
"required": [
"data",
"blob_type"
]
},
"BlobType": {
"description": "Type of blob stored in the blob store",
"type": "string",
"enum": [
"flow",
"data"
]
},
"EvaluateFlowParams": {
"description": "Sent from the component server to the Stepflow to evaluate a flow with the provided input.",
"type": "object",
"properties": {
"flow_id": {
"description": "The ID of the flow to evaluate (blob ID of the flow).",
"$ref": "#/$defs/BlobId"
},
"input": {
"description": "The input to provide to the flow.",
"$ref": "#/$defs/Value"
},
"observability": {
"description": "Observability context for tracing nested flow execution.",
"anyOf": [
{
"$ref": "#/$defs/ObservabilityContext"
},
{
"type": "null"
}
]
}
},
"required": [
"flow_id",
"input"
]
},
"GetFlowMetadataParams": {
"description": "Sent from the component server to Stepflow to get flow and step metadata.\n\nThis request allows components to access workflow-level metadata and step-specific metadata\nduring execution. The metadata can contain arbitrary JSON values defined in the workflow\nYAML/JSON.",
"type": "object",
"properties": {
"flow_id": {
"description": "The flow to retrieve metadata for.",
"$ref": "#/$defs/BlobId"
},
"step_id": {
"description": "The ID of the step to get metadata for (optional).\n\nIf not provided, only flow-level metadata is returned.\nIf provided, both flow metadata and the specified step's metadata are returned.\nIf the step_id doesn't exist, step_metadata will be None in the response.",
"type": [
"string",
"null"
]
},
"observability": {
"description": "Observability context for tracing metadata requests.",
"anyOf": [
{
"$ref": "#/$defs/ObservabilityContext"
},
{
"type": "null"
}
]
}
},
"required": [
"flow_id"
]
},
"SubmitBatchParams": {
"description": "Sent from the component server to Stepflow to submit a batch execution.",
"type": "object",
"properties": {
"flow_id": {
"description": "The ID of the flow to evaluate (blob ID of the flow).",
"$ref": "#/$defs/BlobId"
},
"inputs": {
"description": "The inputs to provide to the flow for each run.",
"type": "array",
"items": {
"$ref": "#/$defs/Value"
}
},
"max_concurrency": {
"description": "Maximum number of concurrent executions (defaults to number of inputs if not specified).",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 0
},
"observability": {
"description": "Observability context for tracing batch submission.",
"anyOf": [
{
"$ref": "#/$defs/ObservabilityContext"
},
{
"type": "null"
}
]
}
},
"required": [
"flow_id",
"inputs"
]
},
"GetBatchParams": {
"description": "Sent from the component server to Stepflow to get batch status and optionally results.",
"type": "object",
"properties": {
"batch_id": {
"description": "The batch ID to query.",
"type": "string"
},
"wait": {
"description": "If true, wait for batch completion before returning.",
"type": "boolean",
"default": false
},
"include_results": {
"description": "If true, include full outputs in response.",
"type": "boolean",
"default": false
},
"observability": {
"description": "Observability context for tracing batch queries.",
"anyOf": [
{
"$ref": "#/$defs/ObservabilityContext"
},
{
"type": "null"
}
]
}
},
"required": [
"batch_id"
]
},
"MethodResponse": {
"description": "Response to a method request.",
"anyOf": [
{
"$ref": "#/$defs/MethodSuccess"
},
{
"$ref": "#/$defs/MethodError"
}
]
},
"MethodSuccess": {
"description": "The result of a successful method execution.",
"type": "object",
"properties": {
"jsonrpc": {
"$ref": "#/$defs/JsonRpc",
"default": "2.0"
},
"id": {
"$ref": "#/$defs/RequestId"
},
"result": {
"title": "MethodResult",
"description": "The result of a successful method execution.",
"oneOf": [
{
"$ref": "#/$defs/InitializeResult"
},
{
"$ref": "#/$defs/ComponentExecuteResult"
},
{
"$ref": "#/$defs/ComponentInfoResult"
},
{
"$ref": "#/$defs/ListComponentsResult"
},
{
"$ref": "#/$defs/GetBlobResult"
},
{
"$ref": "#/$defs/PutBlobResult"
},
{
"$ref": "#/$defs/EvaluateFlowResult"
},
{
"$ref": "#/$defs/GetFlowMetadataResult"
},
{
"$ref": "#/$defs/SubmitBatchResult"
},
{
"$ref": "#/$defs/GetBatchResult"
}
]
}
},
"required": [
"id",
"result"
]
},
"InitializeResult": {
"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.",
"type": "object",
"properties": {
"server_protocol_version": {
"description": "Version of the protocol being used by the component server.",
"type": "integer",
"format": "uint32",
"minimum": 0
}
},
"required": [
"server_protocol_version"
]
},
"ComponentExecuteResult": {
"description": "Sent from the component server back to Stepflow with the result of the component execution.",
"type": "object",
"properties": {
"output": {
"description": "The result of the component execution.",
"$ref": "#/$defs/Value"
}
},
"required": [
"output"
]
},
"ComponentInfoResult": {
"description": "Sent from the component server back to Stepflow with information about the requested component.",
"type": "object",
"properties": {
"info": {
"description": "Information about the component.",
"$ref": "#/$defs/ComponentInfo"
}
},
"required": [
"info"
]
},
"ComponentInfo": {
"type": "object",
"properties": {
"component": {
"description": "The component ID.",
"$ref": "#/$defs/Component"
},
"description": {
"description": "Optional description of the component.",
"type": [
"string",
"null"
]
},
"input_schema": {
"description": "The input schema for the component.\n\nCan be any valid JSON schema (object, primitive, array, etc.).",
"anyOf": [
{
"$ref": "#/$defs/Schema"
},
{
"type": "null"
}
]
},
"output_schema": {
"description": "The output schema for the component.\n\nCan be any valid JSON schema (object, primitive, array, etc.).",
"anyOf": [
{
"$ref": "#/$defs/Schema"
},
{
"type": "null"
}
]
}
},
"required": [
"component"
]
},
"Schema": {
"description": "A JSON schema describing allowed JSON values.",
"type": "object",
"additionalProperties": true,
"example": "\n {\n \"type\": \"object\",\n \"properties\": {\n \"item\": {\n \"type\": \"object\",\n \"properties\": {\n \"label\": {\"type\": \"string\"},\n },\n \"required\": [\"label\"]\n }\n },\n \"required\": [\"item\"]\n }\n "
},
"ListComponentsResult": {
"description": "Sent from the component server back to Stepflow with a list of all available components.",
"type": "object",
"properties": {
"components": {
"description": "A list of all available components.",
"type": "array",
"items": {
"$ref": "#/$defs/ComponentInfo"
}
}
},
"required": [
"components"
]
},
"GetBlobResult": {
"description": "Sent from the Stepflow back to the component server with the blob data and metadata.",
"type": "object",
"properties": {
"data": {
"$ref": "#/$defs/Value"
},
"blob_type": {
"$ref": "#/$defs/BlobType"
}
},
"required": [
"data",
"blob_type"
]
},
"PutBlobResult": {
"description": "Sent from the Stepflow back to the component server with the ID of the stored blob.",
"type": "object",
"properties": {
"blob_id": {
"$ref": "#/$defs/BlobId"
}
},
"required": [
"blob_id"
]
},
"EvaluateFlowResult": {
"description": "Sent from the Stepflow back to the component server with the result of the flow evaluation.",
"type": "object",
"properties": {
"result": {
"description": "The result of the flow evaluation.",
"$ref": "#/$defs/FlowResult"
}
},
"required": [
"result"
]
},
"FlowResult": {
"title": "FlowResult",
"description": "The results of a step execution.",
"oneOf": [
{
"$ref": "#/$defs/FlowResultSuccess"
},
{
"$ref": "#/$defs/FlowResultSkipped"
},
{
"$ref": "#/$defs/FlowResultFailed"
}
],
"discriminator": {
"propertyName": "outcome",
"mapping": {
"success": "#/$defs/FlowResultSuccess",
"skipped": "#/$defs/FlowResultSkipped",
"failed": "#/$defs/FlowResultFailed"
}
}
},
"FlowError": {
"description": "An error reported from within a flow or step.",
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64"
},
"message": {
"type": "string"
},
"data": {
"anyOf": [
{
"$ref": "#/$defs/Value"
},
{
"type": "null"
}
]
}
},
"required": [
"code",
"message"
]
},
"FlowResultSuccess": {
"type": "object",
"properties": {
"outcome": {
"title": "FlowOutcome",
"const": "success",
"default": "success"
},
"result": {
"$ref": "#/$defs/Value"
}
},
"required": [
"outcome",
"result"
]
},
"FlowResultSkipped": {
"type": "object",
"properties": {
"outcome": {
"title": "FlowOutcome",
"const": "skipped",
"default": "skipped"
},
"reason": {
"description": "Optional reason for why the step was skipped.",
"type": "string"
}
},
"required": [
"outcome"
]
},
"FlowResultFailed": {
"type": "object",
"properties": {
"outcome": {
"title": "FlowOutcome",
"const": "failed",
"default": "failed"
},
"error": {
"$ref": "#/$defs/FlowError"
}
},
"required": [
"outcome",
"error"
]
},
"GetFlowMetadataResult": {
"description": "Sent from Stepflow back to the component server with the requested metadata.\n\nContains the flow metadata and step metadata if a specific step was requested.\nThe metadata values are arbitrary JSON objects that can be accessed by components during\nworkflow execution.",
"type": "object",
"properties": {
"flow_metadata": {
"description": "Metadata for the current flow.\n\nThis always contains the flow-level metadata defined in the workflow file.\nCommon fields include name, description, version, but can contain any\narbitrary JSON structure defined by the workflow author.",
"type": "object",
"additionalProperties": true
},
"step_metadata": {
"description": "Metadata for the specified step (only present if step_id was provided and found).\n\nThis contains step-specific metadata defined in the workflow file.\nWill be None if no step_id was provided in the request",
"type": [
"object",
"null"
],
"additionalProperties": true
}
},
"required": [
"flow_metadata"
]
},
"SubmitBatchResult": {
"description": "Sent from Stepflow back to the component server with the batch submission result.",
"type": "object",
"properties": {
"batch_id": {
"description": "The batch ID (UUID).",
"type": "string"
},
"total_runs": {
"description": "Total number of runs in the batch.",
"type": "integer",
"format": "uint",
"minimum": 0
}
},
"required": [
"batch_id",
"total_runs"
]
},
"GetBatchResult": {
"description": "Sent from Stepflow back to the component server with batch details and optional outputs.",
"type": "object",
"properties": {
"details": {
"description": "Always included: batch details with metadata and statistics.",
"$ref": "#/$defs/BatchDetails"
},
"outputs": {
"description": "Only included if include_results=true.",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/BatchOutputInfo"
}
}
},
"required": [
"details"
]
},
"BatchDetails": {
"description": "Batch details including metadata and statistics.",
"type": "object",
"properties": {
"batch_id": {
"description": "The batch ID.",
"type": "string"
},
"flow_id": {
"description": "The flow ID.",
"$ref": "#/$defs/BlobId"
},
"flow_name": {
"description": "The flow name (optional).",
"type": [
"string",
"null"
]
},
"total_runs": {
"description": "Total number of runs in the batch.",
"type": "integer",
"format": "uint",
"minimum": 0
},
"status": {
"description": "Batch status (running | cancelled).",
"type": "string"
},
"created_at": {
"description": "Timestamp when the batch was created.",
"type": "string"
},
"completed_runs": {
"description": "Statistics for the batch.",
"type": "integer",
"format": "uint",
"minimum": 0
},
"running_runs": {
"type": "integer",
"format": "uint",
"minimum": 0
},
"failed_runs": {
"type": "integer",
"format": "uint",
"minimum": 0
},
"cancelled_runs": {
"type": "integer",
"format": "uint",
"minimum": 0
},
"paused_runs": {
"type": "integer",
"format": "uint",
"minimum": 0
},
"completed_at": {
"description": "Completion timestamp (if all runs complete).",
"type": [
"string",
"null"
]
}
},
"required": [
"batch_id",
"flow_id",
"total_runs",
"status",
"created_at",
"completed_runs",
"running_runs",
"failed_runs",
"cancelled_runs",
"paused_runs"
]
},
"BatchOutputInfo": {
"description": "Output information for a single run in a batch.",
"type": "object",
"properties": {
"batch_input_index": {
"description": "Position in the batch input array.",
"type": "integer",
"format": "uint",
"minimum": 0
},
"status": {
"description": "The execution status.",
"type": "string"
},
"result": {
"description": "The flow result (if completed).",
"anyOf": [
{
"$ref": "#/$defs/FlowResult"
},
{
"type": "null"
}
]
}
},
"required": [
"batch_input_index",
"status"
]
},
"MethodError": {
"type": "object",
"properties": {
"jsonrpc": {
"$ref": "#/$defs/JsonRpc",
"default": "2.0"
},
"id": {
"$ref": "#/$defs/RequestId"
},
"error": {
"description": "An error that occurred during method execution.",
"$ref": "#/$defs/Error"
}
},
"required": [
"id",
"error"
]
},
"Error": {
"description": "An error returned from a method execution.",
"type": "object",
"properties": {
"code": {
"description": "A numeric code indicating the error type.",
"type": "integer",
"format": "int64"
},
"message": {
"description": "Concise, single-sentence description of the error.",
"type": "string"
},
"data": {
"description": "Primitive or structured value that contains additional information about the error.",
"anyOf": [
{
"$ref": "#/$defs/Value"
},
{
"type": "null"
}
]
}
},
"required": [
"code",
"message"
]
},
"Notification": {
"description": "Notification.",
"type": "object",
"properties": {
"jsonrpc": {
"$ref": "#/$defs/JsonRpc",
"default": "2.0"
},
"method": {
"description": "The notification method being called.",
"$ref": "#/$defs/Method"
},
"params": {
"title": "NotificationParams",
"description": "The parameters for the notification.",
"oneOf": [
{
"$ref": "#/$defs/Initialized"
}
]
}
},
"required": [
"method",
"params"
]
},
"Initialized": {
"description": "Sent from Stepflow to the component server after initialization is complete.",
"type": "object"
}
}
}