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"
}
]
}
},
"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"
]
},
"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
},
"protocol_prefix": {
"description": "The protocol prefix for components served by this plugin (e.g., \"python\", \"typescript\")",
"type": "string"
}
},
"required": [
"runtime_protocol_version",
"protocol_prefix"
]
},
"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"
}
},
"required": [
"component",
"input"
]
},
"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"
}
},
"required": [
"blob_id"
]
},
"BlobId": {
"description": "A SHA-256 hash of the blob content, represented as a hexadecimal string.",
"type": "string"
},
"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"
}
},
"required": [
"data"
]
},
"EvaluateFlowParams": {
"description": "Sent from the component server to the StepFlow to evaluate a flow with the provided input.",
"type": "object",
"properties": {
"flow": {
"description": "The flow to evaluate.",
"$ref": "#/$defs/Flow"
},
"input": {
"description": "The input to provide to the flow.",
"$ref": "#/$defs/Value"
}
},
"required": [
"flow",
"input"
]
},
"Flow": {
"description": "A workflow consisting of a sequence of steps and their outputs.\n\nA flow represents a complete workflow that can be executed. It contains:\n- A sequence of steps to execute\n- Named outputs that can reference step outputs\n\nFlows should not be cloned. They should generally be stored and passed as a\nreference or inside an `Arc`.",
"type": "object",
"properties": {
"name": {
"description": "The name of the flow.",
"type": [
"string",
"null"
]
},
"description": {
"description": "The description of the flow.",
"type": [
"string",
"null"
]
},
"version": {
"description": "The version of the flow.",
"type": [
"string",
"null"
]
},
"inputSchema": {
"description": "The input schema of the flow.",
"anyOf": [
{
"$ref": "#/$defs/Schema"
},
{
"type": "null"
}
]
},
"outputSchema": {
"description": "The output schema of the flow.",
"anyOf": [
{
"$ref": "#/$defs/Schema"
},
{
"type": "null"
}
]
},
"steps": {
"description": "The steps to execute for the flow.",
"type": "array",
"items": {
"$ref": "#/$defs/Step"
},
"default": []
},
"output": {
"description": "The outputs of the flow, mapping output names to their values.",
"$ref": "#/$defs/ValueTemplate"
},
"test": {
"description": "Test configuration for the flow.",
"anyOf": [
{
"$ref": "#/$defs/TestConfig"
},
{
"type": "null"
}
]
},
"examples": {
"description": "Example inputs for the workflow that can be used for testing and UI dropdowns.",
"type": "array",
"items": {
"$ref": "#/$defs/ExampleInput"
}
}
},
"required": [
"steps"
]
},
"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 "
},
"Step": {
"description": "A step in a workflow that executes a component with specific arguments.",
"type": "object",
"properties": {
"id": {
"description": "Identifier for the step",
"type": "string"
},
"component": {
"description": "The component to execute in this step",
"$ref": "#/$defs/Component"
},
"inputSchema": {
"description": "The input schema for this step.",
"anyOf": [
{
"$ref": "#/$defs/Schema"
},
{
"type": "null"
}
]
},
"outputSchema": {
"description": "The output schema for this step.",
"anyOf": [
{
"$ref": "#/$defs/Schema"
},
{
"type": "null"
}
]
},
"skipIf": {
"description": "If set and the referenced value is truthy, this step will be skipped.",
"anyOf": [
{
"$ref": "#/$defs/Expr"
},
{
"type": "null"
}
]
},
"onError": {
"$ref": "#/$defs/ErrorAction"
},
"input": {
"description": "Arguments to pass to the component for this step",
"$ref": "#/$defs/ValueTemplate"
}
},
"required": [
"id",
"component"
]
},
"Expr": {
"description": "An expression that can be either a literal value or a template expression.",
"anyOf": [
{
"title": "Reference",
"description": "Reference a value from a step, workflow, or other source.",
"type": "object",
"properties": {
"$from": {
"description": "The source of the reference.",
"$ref": "#/$defs/BaseRef"
},
"path": {
"description": "JSON path expression to apply to the referenced value.\n\nDefaults to `$` (the whole referenced value).\nMay also be a bare field name (without the leading $) if\nthe referenced value is an object.",
"$ref": "#/$defs/JsonPath"
},
"onSkip": {
"$ref": "#/$defs/SkipAction"
}
},
"required": [
"$from"
]
},
{
"title": "EscapedLiteral",
"description": "A literal value that was escaped.\n\nNo template expansion is performed within the value, allowing\nfor raw JSON values that include `$from` or other special characters.",
"type": "object",
"properties": {
"$literal": {
"description": "A literal value that should not be expanded for expressions.\nThis allows creating JSON values that contain `$from` without expansion.",
"$ref": "#/$defs/Value"
}
},
"required": [
"$literal"
]
},
{
"title": "Literal",
"description": "A direct literal value that serializes naturally without special syntax",
"$ref": "#/$defs/Value"
}
]
},
"BaseRef": {
"description": "An expression that can be either a literal value or a template expression.",
"anyOf": [
{
"title": "WorkflowReference",
"description": "Reference properties of the workflow.",
"type": "object",
"properties": {
"workflow": {
"$ref": "#/$defs/WorkflowRef"
}
},
"required": [
"workflow"
],
"additionalProperties": false
},
{
"title": "StepReference",
"description": "Reference the output of a step.",
"type": "object",
"properties": {
"step": {
"type": "string"
}
},
"required": [
"step"
]
}
]
},
"WorkflowRef": {
"type": "string",
"enum": [
"input"
]
},
"JsonPath": {
"description": "JSON path expression to apply to the referenced value. May use `$` to reference the whole value. May also be a bare field name (without the leading $) if the referenced value is an object.",
"type": "string",
"examples": [
"field",
"$.field",
"$[\"field\"]",
"$[0]",
"$.field[0].nested"
]
},
"SkipAction": {
"oneOf": [
{
"title": "OnSkipSkip",
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "skip"
}
},
"required": [
"action"
]
},
{
"title": "OnSkipDefault",
"type": "object",
"properties": {
"defaultValue": {
"anyOf": [
{
"$ref": "#/$defs/Value"
},
{
"type": "null"
}
]
},
"action": {
"type": "string",
"const": "useDefault"
}
},
"required": [
"action"
]
}
]
},
"ErrorAction": {
"oneOf": [
{
"title": "OnErrorFail",
"description": "If the step fails, the flow will fail.",
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "fail"
}
},
"required": [
"action"
]
},
{
"title": "OnErrorSkip",
"description": "If the step fails, mark it as skipped. This allows down-stream steps to handle the skipped step.",
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "skip"
}
},
"required": [
"action"
]
},
{
"title": "OnErrorDefault",
"description": "If the step fails, use the `defaultValue` instead.",
"type": "object",
"properties": {
"defaultValue": {
"anyOf": [
{
"$ref": "#/$defs/ValueTemplate"
},
{
"type": "null"
}
]
},
"action": {
"type": "string",
"const": "useDefault"
}
},
"required": [
"action"
]
},
{
"title": "OnErrorRetry",
"description": "If the step fails, retry it.",
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "retry"
}
},
"required": [
"action"
]
}
]
},
"ValueTemplate": {
"description": "A value that can be either a literal JSON value or an expression that references other values using the $from syntax",
"anyOf": [
{
"description": "An expression with `$from` syntax for referencing other values",
"$ref": "#/$defs/Expr"
},
{
"description": "JSON null value",
"type": "null"
},
{
"description": "JSON boolean value",
"type": "boolean"
},
{
"description": "JSON numeric value",
"type": "number"
},
{
"description": "JSON string value",
"type": "string"
},
{
"description": "JSON array where each element can be a template",
"type": "array",
"items": {
"$ref": "#/$defs/ValueTemplate"
}
},
{
"description": "JSON object where each value can be a template",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/ValueTemplate"
}
}
]
},
"TestConfig": {
"description": "Configuration for testing a workflow.",
"type": "object",
"properties": {
"stepflowConfig": {
"description": "Stepflow configuration specific to tests."
},
"cases": {
"description": "Test cases for the workflow.",
"type": "array",
"items": {
"$ref": "#/$defs/TestCase"
}
}
}
},
"TestCase": {
"description": "A single test case for a workflow.",
"type": "object",
"properties": {
"name": {
"description": "Unique identifier for the test case.",
"type": "string"
},
"description": {
"description": "Optional description of what this test case verifies.",
"type": [
"string",
"null"
]
},
"input": {
"description": "Input data for the workflow in this test case.",
"$ref": "#/$defs/Value"
},
"output": {
"description": "Expected output from the workflow for this test case.",
"anyOf": [
{
"$ref": "#/$defs/FlowResult"
},
{
"type": "null"
}
]
}
},
"required": [
"name",
"input"
]
},
"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"
]
},
"ExampleInput": {
"description": "An example input for a workflow that can be used in UI dropdowns.",
"type": "object",
"properties": {
"name": {
"description": "Name of the example input for display purposes.",
"type": "string"
},
"description": {
"description": "Optional description of what this example demonstrates.",
"type": [
"string",
"null"
]
},
"input": {
"description": "The input data for this example.",
"$ref": "#/$defs/Value"
}
},
"required": [
"name",
"input"
]
},
"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"
}
]
}
},
"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"
]
},
"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 content of the requested blob.",
"type": "object",
"properties": {
"data": {
"$ref": "#/$defs/Value"
}
},
"required": [
"data"
]
},
"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"
]
},
"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"
}
}
}