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"
}
]
}
},
"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"
]
},
"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
}
},
"required": [
"runtime_protocol_version"
]
},
"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"
},
"step_id": {
"description": "The ID of the step being executed.",
"type": "string"
},
"run_id": {
"description": "The ID of the workflow run.",
"type": "string"
},
"flow_id": {
"description": "The ID of the flow being executed.",
"$ref": "#/$defs/BlobId"
}
},
"required": [
"component",
"input",
"step_id",
"run_id",
"flow_id"
]
},
"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)"
},
"BlobId": {
"description": "A SHA-256 hash of the blob content, represented as a hexadecimal string.",
"type": "string"
},
"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"
}
},
"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"
}
},
"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"
}
},
"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"
]
}
},
"required": [
"flow_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"
}
]
}
},
"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"
}
},
"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"
]
},
"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"
}
}
}