Flow Schema
- Schema Viewer
- Schema Source
Loading ....
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Flow",
"type": "object",
"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`.",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "The name of the flow."
},
"description": {
"type": [
"string",
"null"
],
"description": "The description of the flow."
},
"version": {
"type": [
"string",
"null"
],
"description": "The version of the flow."
},
"schemas": {
"$ref": "#/$defs/FlowSchema",
"description": "Consolidated schema information for the flow.\nContains input/output schemas, step output schemas, and shared `$defs`."
},
"steps": {
"type": "array",
"items": {
"$ref": "#/$defs/Step"
},
"description": "The steps to execute for the flow."
},
"output": {
"$ref": "#/$defs/ValueExpr",
"description": "The outputs of the flow, mapping output names to their values."
},
"test": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/TestConfig",
"description": "Test configuration for the flow."
}
]
},
"examples": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/ExampleInput"
},
"description": "Example inputs for the workflow that can be used for testing and UI dropdowns."
},
"metadata": {
"type": "object",
"description": "Extensible metadata for the flow that can be used by tools and frameworks.",
"additionalProperties": {},
"propertyNames": {
"type": "string"
}
}
},
"$defs": {
"FlowSchema": {
"type": "object",
"description": "Consolidated schema information for a flow.\n\nThis struct contains all schema/type information for the flow in a single location,\nallowing shared `$defs` across all schemas and avoiding duplication.\n\nSerializes as a valid JSON Schema with `type: \"object\"` and flow-specific\nproperties (`input`, `output`, `variables`, `steps`) under the `properties` key.",
"required": [
"defs",
"steps"
],
"properties": {
"defs": {
"type": "object",
"description": "Shared type definitions that can be referenced by other schemas.\nReferences use the format `#/schemas/$defs/TypeName`.",
"additionalProperties": {
"$ref": "#/$defs/Schema"
},
"propertyNames": {
"type": "string"
}
},
"input": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/Schema",
"description": "The input schema for the flow."
}
],
"default": null
},
"output": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/Schema",
"description": "The output schema for the flow."
}
],
"default": null
},
"variables": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/Schema",
"description": "Schema for workflow variables. This is a JSON Schema object where\nproperties define the available variables and their types."
}
],
"default": null
},
"steps": {
"type": "object",
"description": "Output schemas for each step, keyed by step ID.\nNote: Step input schemas are not included here as they are\ncomponent metadata, not flow-specific schemas.\nUses IndexMap to preserve insertion order for deterministic serialization.",
"additionalProperties": {
"$ref": "#/$defs/Schema"
},
"propertyNames": {
"type": "string"
}
}
}
},
"Step": {
"type": "object",
"description": "A step in a workflow that executes a component with specific arguments.\n\nNote: Step output schemas are stored in the flow's `types.steps` field,\nnot on individual steps. This allows for shared `$defs` and avoids duplication.",
"required": [
"id",
"component"
],
"properties": {
"id": {
"type": "string",
"description": "Identifier for the step"
},
"component": {
"$ref": "#/$defs/Component",
"description": "The component to execute in this step"
},
"onError": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/ErrorAction"
}
]
},
"input": {
"$ref": "#/$defs/ValueExpr",
"description": "Arguments to pass to the component for this step"
},
"mustExecute": {
"type": [
"boolean",
"null"
],
"description": "If true, this step must execute even if its output is not used by the workflow output.\nUseful for steps with side effects (e.g., writing to databases, sending notifications)."
},
"metadata": {
"type": "object",
"description": "Extensible metadata for the step that can be used by tools and frameworks.",
"additionalProperties": {},
"propertyNames": {
"type": "string"
}
}
}
},
"ValueExpr": {
"oneOf": [
{
"type": "object",
"title": "StepRef",
"description": "Step reference: { $step: \"step_id\", path?: \"...\" }",
"required": [
"$step"
],
"properties": {
"$step": {
"type": "string"
},
"path": {
"type": "string",
"description": "JSONPath expression"
}
},
"additionalProperties": false
},
{
"type": "object",
"title": "InputRef",
"description": "Workflow input reference: { $input: \"path\" }",
"required": [
"$input"
],
"properties": {
"$input": {
"type": "string",
"description": "JSONPath expression"
}
},
"additionalProperties": false
},
{
"type": "object",
"title": "VariableRef",
"description": "Variable reference: { $variable: \"path\", default?: ValueExpr }",
"required": [
"$variable"
],
"properties": {
"$variable": {
"type": "string",
"description": "JSONPath expression including variable name"
},
"default": {
"$ref": "#/$defs/ValueExpr"
}
},
"additionalProperties": false
},
{
"type": "object",
"title": "LiteralExpr",
"description": "Escaped literal: { $literal: any }",
"required": [
"$literal"
],
"properties": {
"$literal": {
"allOf": []
}
},
"additionalProperties": false
},
{
"type": "object",
"title": "If",
"description": "Conditional: { $if: condition, then: expr, else?: expr }",
"required": [
"$if",
"then"
],
"properties": {
"$if": {
"$ref": "#/$defs/ValueExpr"
},
"then": {
"$ref": "#/$defs/ValueExpr"
},
"else": {
"$ref": "#/$defs/ValueExpr"
}
},
"additionalProperties": false
},
{
"type": "object",
"title": "Coalesce",
"description": "Coalesce: { $coalesce: [expr1, expr2, ...] }",
"required": [
"$coalesce"
],
"properties": {
"$coalesce": {
"type": "array",
"items": {
"$ref": "#/$defs/ValueExpr"
}
}
},
"additionalProperties": false
},
{
"type": "array",
"title": "ArrayExpr",
"items": {
"$ref": "#/$defs/ValueExpr"
},
"description": "Array of expressions"
},
{
"type": "object",
"title": "ObjectExpr",
"description": "Object with expression values",
"additionalProperties": {
"$ref": "#/$defs/ValueExpr"
}
},
{
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
}
],
"title": "PrimitiveValue",
"description": "Literal primitive value"
}
],
"description": "A value expression that can contain literal data or references to other values"
},
"TestConfig": {
"type": "object",
"description": "Configuration for testing a workflow.",
"properties": {
"servers": {
"type": "object",
"description": "Test servers to start before running tests.\nKey is the server name, value is the server configuration.",
"additionalProperties": {
"$ref": "#/$defs/TestServerConfig"
},
"propertyNames": {
"type": "string"
}
},
"config": {
"description": "Stepflow configuration specific to tests.\nCan reference server URLs using placeholders like {server_name.url}."
},
"cases": {
"type": "array",
"items": {
"$ref": "#/$defs/TestCase"
},
"description": "Test cases for the workflow."
}
}
},
"ExampleInput": {
"type": "object",
"description": "An example input for a workflow that can be used in UI dropdowns.",
"required": [
"name",
"input"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the example input for display purposes."
},
"description": {
"type": [
"string",
"null"
],
"description": "Optional description of what this example demonstrates."
},
"input": {
"$ref": "#/$defs/Value",
"description": "The input data for this example."
}
}
},
"Schema": {
"type": "object",
"description": "A valid JSON Schema object."
},
"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"
]
},
"ErrorAction": {
"oneOf": [
{
"$ref": "#/$defs/OnErrorFail"
},
{
"$ref": "#/$defs/OnErrorDefault"
},
{
"$ref": "#/$defs/OnErrorRetry"
}
],
"description": "Error action determines what happens when a step fails.",
"discriminator": {
"propertyName": "action",
"mapping": {
"fail": "#/$defs/OnErrorFail",
"retry": "#/$defs/OnErrorRetry",
"useDefault": "#/$defs/OnErrorDefault"
}
}
},
"OnErrorFail": {
"type": "object",
"title": "OnErrorFail",
"description": "If the step fails, the flow will fail.",
"required": [
"action"
],
"properties": {
"action": {
"type": "string"
}
}
},
"OnErrorDefault": {
"type": "object",
"title": "OnErrorDefault",
"description": "If the step fails, use the `defaultValue` instead.\nIf `defaultValue` is not specified, the step returns null.\nThe default value must be a literal JSON value (not an expression).\nFor dynamic defaults, use `$coalesce` in the consuming expression instead.",
"required": [
"action"
],
"properties": {
"action": {
"type": "string"
},
"defaultValue": {
"allOf": []
}
}
},
"OnErrorRetry": {
"type": "object",
"title": "OnErrorRetry",
"description": "If the step fails, retry it.",
"required": [
"action"
],
"properties": {
"action": {
"type": "string"
}
}
},
"TestServerConfig": {
"type": "object",
"description": "Configuration for a test server.",
"required": [
"command"
],
"properties": {
"command": {
"type": "string",
"description": "Command to start the server."
},
"args": {
"type": "array",
"items": {
"type": "string"
},
"description": "Arguments for the server command."
},
"env": {
"type": "object",
"description": "Environment variables for the server process.\nValues can contain placeholders like {port} which will be substituted.",
"additionalProperties": {
"type": "string"
},
"propertyNames": {
"type": "string"
}
},
"workingDirectory": {
"type": [
"string",
"null"
],
"description": "Working directory for the server process."
},
"portRange": {
"type": [
"array",
"null"
],
"items": false,
"prefixItems": [
{
"type": "integer",
"format": "int32",
"minimum": 0
},
{
"type": "integer",
"format": "int32",
"minimum": 0
}
],
"description": "Port range for automatic port allocation.\nIf not specified, a random available port will be used."
},
"healthCheck": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/TestServerHealthCheck",
"description": "Health check configuration."
}
]
},
"startupTimeoutMs": {
"type": "integer",
"format": "int64",
"description": "Maximum time to wait for server startup (in milliseconds).",
"default": 10000,
"minimum": 0
},
"shutdownTimeoutMs": {
"type": "integer",
"format": "int64",
"description": "Maximum time to wait for server shutdown (in milliseconds).",
"default": 5000,
"minimum": 0
}
}
},
"TestCase": {
"type": "object",
"description": "A single test case for a workflow.",
"required": [
"name",
"input"
],
"properties": {
"name": {
"type": "string",
"description": "Unique identifier for the test case."
},
"description": {
"type": [
"string",
"null"
],
"description": "Optional description of what this test case verifies."
},
"input": {
"$ref": "#/$defs/Value",
"description": "Input data for the workflow in this test case."
},
"output": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/$defs/FlowResult",
"description": "Expected output from the workflow for this test case."
}
]
}
}
},
"TestServerHealthCheck": {
"type": "object",
"description": "Health check configuration for test servers.",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"description": "Path for health check endpoint (e.g., \"/health\")."
},
"timeoutMs": {
"type": "integer",
"format": "int64",
"description": "Timeout for health check requests (in milliseconds).",
"default": 5000,
"minimum": 0
},
"retryAttempts": {
"type": "integer",
"format": "int32",
"description": "Number of retry attempts for health checks.",
"default": 3,
"minimum": 0
},
"retryDelayMs": {
"type": "integer",
"format": "int64",
"description": "Delay between retry attempts (in milliseconds).",
"default": 1000,
"minimum": 0
}
}
},
"Value": {
"allOf": [],
"description": "Any JSON value (object, array, string, number, boolean, or null)"
},
"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"
}
}
}
}
}