Flow Schema
- Schema Viewer
- Schema Source
Loading ....
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "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"
]
},
"schemas": {
"description": "Consolidated schema information for the flow.\nContains input/output schemas, step output schemas, and shared `$defs`.",
"$ref": "#/$defs/FlowSchema"
},
"steps": {
"description": "The steps to execute for the flow.",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/Step"
}
},
"output": {
"description": "The outputs of the flow, mapping output names to their values.",
"$ref": "#/$defs/ValueExpr"
},
"test": {
"description": "Test configuration for the flow.",
"oneOf": [
{
"$ref": "#/$defs/TestConfig"
},
{
"type": "null"
}
]
},
"examples": {
"description": "Example inputs for the workflow that can be used for testing and UI dropdowns.",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/ExampleInput"
}
},
"metadata": {
"description": "Extensible metadata for the flow that can be used by tools and frameworks.",
"type": [
"object",
"null"
],
"additionalProperties": true
}
},
"$defs": {
"FlowSchema": {
"description": "A JSON Schema object describing the flow's type information. Contains input/output schemas, variable schemas, and step output schemas wrapped in standard JSON Schema format with type, properties, and $defs.",
"type": "object",
"additionalProperties": true
},
"Step": {
"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.",
"type": "object",
"properties": {
"id": {
"description": "Identifier for the step",
"type": "string"
},
"component": {
"description": "The component to execute in this step",
"$ref": "#/$defs/Component"
},
"onError": {
"oneOf": [
{
"$ref": "#/$defs/ErrorAction"
},
{
"type": "null"
}
]
},
"input": {
"description": "Arguments to pass to the component for this step",
"$ref": "#/$defs/ValueExpr"
},
"mustExecute": {
"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).",
"type": [
"boolean",
"null"
]
},
"metadata": {
"description": "Extensible metadata for the step that can be used by tools and frameworks.",
"type": [
"object",
"null"
],
"additionalProperties": true
}
},
"required": [
"id",
"component"
]
},
"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"
]
},
"ErrorAction": {
"description": "Error action determines what happens when a step fails.",
"oneOf": [
{
"$ref": "#/$defs/OnErrorFail"
},
{
"$ref": "#/$defs/OnErrorDefault"
},
{
"$ref": "#/$defs/OnErrorRetry"
}
],
"discriminator": {
"propertyName": "action",
"mapping": {
"fail": "#/$defs/OnErrorFail",
"useDefault": "#/$defs/OnErrorDefault",
"retry": "#/$defs/OnErrorRetry"
}
}
},
"ValueExpr": {
"description": "A value expression: any JSON value (null, boolean, number, string, array, or object). Objects with reserved $-prefixed keys are interpreted as expression references: {\"$step\": \"id\", \"path\"?: \"...\"}, {\"$input\": \"path\"}, {\"$variable\": \"path\", \"default\"?: ValueExpr}, {\"$literal\": value}, {\"$if\": cond, \"then\": expr, \"else\"?: expr}, {\"$coalesce\": [expr, ...]}. See https://stepflow.org/docs/flows/expressions for details.",
"externalDocs": {
"description": "Expressions documentation",
"url": "https://stepflow.org/docs/flows/expressions"
}
},
"TestConfig": {
"description": "Configuration for testing a workflow.",
"type": "object",
"properties": {
"configFile": {
"description": "Path to an external stepflow config file for tests.\nRelative paths are resolved from the workflow file's directory.\nMutually exclusive with `config` - validated at runtime.",
"type": [
"string",
"null"
]
},
"config": {
"description": "Inline stepflow configuration for tests.\nMutually exclusive with `config_file` - validated at runtime."
},
"cases": {
"description": "Test cases for the workflow.",
"type": [
"array",
"null"
],
"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.",
"oneOf": [
{
"$ref": "#/$defs/FlowResult"
},
{
"type": "null"
}
]
}
},
"required": [
"name",
"input"
]
},
"Value": {
"description": "Any JSON value (object, array, string, number, boolean, or null)"
},
"FlowResult": {
"oneOf": [
{
"$ref": "#/$defs/FlowResultSuccess"
},
{
"$ref": "#/$defs/FlowResultFailed"
}
],
"discriminator": {
"propertyName": "outcome",
"mapping": {
"success": "#/$defs/FlowResultSuccess",
"failed": "#/$defs/FlowResultFailed"
}
}
},
"FlowResultSuccess": {
"description": "The step execution was successful.",
"type": "object",
"properties": {
"outcome": {
"type": "string",
"const": "success",
"default": "success"
},
"result": {
"$ref": "#/$defs/Value"
}
},
"required": [
"outcome",
"result"
]
},
"FlowResultFailed": {
"description": "The step failed with the given error.",
"type": "object",
"properties": {
"outcome": {
"type": "string",
"const": "failed",
"default": "failed"
},
"error": {
"$ref": "#/$defs/FlowError"
}
},
"required": [
"outcome",
"error"
]
},
"FlowError": {
"description": "An error reported from within a flow or step.",
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64"
},
"message": {
"type": "string"
},
"data": {
"oneOf": [
{
"$ref": "#/$defs/Value"
},
{
"type": "null"
}
]
}
},
"required": [
"code",
"message"
]
},
"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"
]
},
"OnErrorFail": {
"title": "OnErrorFail",
"description": "If the step fails, the flow will fail.",
"type": "object",
"properties": {
"action": {
"type": "string",
"const": "fail",
"default": "fail"
}
},
"required": [
"action"
]
},
"OnErrorDefault": {
"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.",
"type": "object",
"properties": {
"defaultValue": true,
"action": {
"type": "string",
"const": "useDefault",
"default": "useDefault"
}
},
"required": [
"action"
]
},
"OnErrorRetry": {
"title": "OnErrorRetry",
"description": "If the step fails, retry it.\n\n`max_retries` limits retries due to component errors — cases where the\ncomponent ran and returned an error. Transport-level failures (subprocess\ncrashes, network errors) are retried separately according to the plugin's\nretry configuration and do not count against this budget.",
"type": "object",
"properties": {
"maxRetries": {
"description": "Maximum number of retries due to component errors (default: 3).\n\nTotal attempts for component errors = max_retries + 1 (initial).",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0
},
"action": {
"type": "string",
"const": "retry",
"default": "retry"
}
},
"required": [
"action"
]
}
}
}