{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "JSON-RPC Flow Schema", "description": "A schema for defining JSON-RPC workflows as a series of composable, nestable operations. Each flow consists of a sequence of steps that can be executed based on their data dependencies and control flow structures.", "type": "object", "properties": { "name": { "type": "string", "description": "A unique identifier for the flow. Should be descriptive and follow kebab-case naming convention." }, "description": { "type": "string", "description": "A detailed description of what the flow does, its purpose, and expected outcomes." }, "policies": { "type": "object", "description": "Policies for the flow. The global policy applies to the workflow as whole. The step policy applies to the steps who do not have their own policy.", "properties": { "global": { "$ref": "#/definitions/Policies" }, "step": { "$ref": "#/definitions/Policies" } } }, "context": { "type": "object", "description": "Optional global context variables available throughout the flow execution.", "additionalProperties": true }, "steps": { "type": "array", "description": "An ordered sequence of steps to execute. While the order provides a visual guide, actual execution order is determined by data dependencies between steps.", "items": { "$ref": "#/definitions/Step" }, "minItems": 1 } }, "definitions": { "Step": { "type": "object", "description": "A single step in the flow. Each step must have exactly one of the primitive operations: request, transform, loop, or condition.", "required": ["name"], "properties": { "name": { "type": "string", "description": "A unique identifier for the step within the flow. Used for referencing step results in expressions.", "pattern": "^[a-zA-Z][a-zA-Z0-9]*$" }, "policies": { "$ref": "#/definitions/Policies" } }, "oneOf": [ { "$ref": "#/definitions/RequestStep" }, { "$ref": "#/definitions/TransformStep" }, { "$ref": "#/definitions/LoopStep" }, { "$ref": "#/definitions/ConditionStep" }, { "$ref": "#/definitions/StopStep" } ] }, "Policies": { "type": "object", "description": "Optional policies for the step. If not provided, the default policies will be used.", "properties": { "retryPolicy": { "type": "object", "description": "Optional retry policy. If not provided, the default retry policy will be used.", "properties": { "maxAttempts": { "type": "number", "description": "The maximum number of attempts to retry the step. if the step type has a more specific maxAttempts, the default will be overridden, however, if set, it will override both the default and the step type specific maxAttempts. 0 means unlimited attempts (until timeout)", "default": 3, "minimum": 0, "maximum": 100 }, "backoff": { "type": "object", "description": "The backoff policy for the step. If not provided, the default backoff policy will be used.", "properties": { "strategy": { "type": "string", "description": "The strategy to use for the backoff. If not provided, the default backoff strategy will be used.", "default": "exponential", "enum": ["exponential", "linear"] }, "initial": { "type": "number", "description": "The initial delay in milliseconds." }, "multiplier": { "type": "number", "description": "The multiplier/exponent for the backoff." }, "maxDelay": { "type": "number", "description": "The maximum delay in milliseconds.", "default": 5000, "minimum": 0, "maximum": 3600000 } } }, "retryableErrors": { "type": "array", "description": "An array of error codes that are retryable.", "items": { "type": "string", "enum": [ "VALIDATION_ERROR", "INVALID_INPUT", "SCHEMA_VALIDATION", "TYPE_ERROR", "EXECUTION_ERROR", "RUNTIME_ERROR", "NETWORK_ERROR", "RESOURCE_ERROR", "MAX_RETRIES_EXCEEDED", "TIMEOUT_ERROR", "OPERATION_TIMEOUT", "DEADLINE_EXCEEDED", "STATE_ERROR", "INVALID_STATE", "MISSING_DEPENDENCY", "INTERNAL_ERROR", "CONFIG_ERROR" ] } } } }, "timeout": { "type": "object", "description": "Timeout policy. If not provided, the default timeout policy will be used.", "properties": { "timeout": { "type": "number", "description": "Optional timeout for the step in milliseconds. If not provided, the default timeout will be used.", "default": 10000, "minimum": 0, "maximum": 3600000 }, "expressionEval": { "type": "number", "description": "Optional timeout for expression evaluation in milliseconds. If not provided, the default expression timeout will be used.", "default": 1000, "minimum": 0, "maximum": 3600000 } } } } }, "RequestStep": { "type": "object", "description": "A step that makes a JSON-RPC request. This is the primary mechanism for external interactions.", "required": ["name", "request"], "properties": { "request": { "type": "object", "required": ["method", "params"], "properties": { "method": { "type": "string", "description": "The JSON-RPC method to call." }, "params": { "type": "object", "description": "Parameters for the JSON-RPC method. Values can contain template expressions using ${...} syntax to reference other step results or context variables.", "additionalProperties": true } } } } }, "TransformStep": { "type": "object", "description": "A step that performs data transformations using a series of operations.", "required": ["name", "transform"], "properties": { "transform": { "type": "object", "required": ["input", "operations"], "properties": { "input": { "oneOf": [ { "type": "string", "description": "Expression that evaluates to the input data for transformation." }, { "type": "array", "description": "Array literal to use as input for transformation.", "items": {} } ] }, "operations": { "type": "array", "description": "Sequence of operations to apply to the input data.", "items": { "type": "object", "required": ["type", "using"], "properties": { "type": { "type": "string", "enum": [ "map", "filter", "reduce", "flatten", "sort", "unique", "group", "join" ], "description": "The type of transformation operation to perform." }, "using": { "type": "string", "description": "Expression defining the operation. For map/filter, this is evaluated for each item. For reduce, this combines items." }, "as": { "type": "string", "description": "Optional variable name for the current item in the operation expression." }, "initial": { "description": "Initial value for reduce operations." } } }, "minItems": 1 } } } } }, "LoopStep": { "type": "object", "description": "A step that iterates over a collection and executes a nested step for each item.", "required": ["name", "loop"], "properties": { "loop": { "type": "object", "required": ["over", "as"], "properties": { "over": { "type": "string", "description": "Expression that evaluates to the array to iterate over." }, "as": { "type": "string", "description": "Variable name to use for the current item in the iteration.", "pattern": "^[a-zA-Z][a-zA-Z0-9]*$" }, "condition": { "type": "string", "description": "Optional condition to determine whether to execute the step for each item." }, "maxIterations": { "type": "number", "description": "Optional maximum number of iterations to perform." }, "step": { "$ref": "#/definitions/Step", "description": "The step to execute for each item in the iteration. Can be any primitive step type." }, "steps": { "type": "array", "description": "An array of steps to execute for each item in the iteration.", "items": { "$ref": "#/definitions/Step" } } } } } }, "ConditionStep": { "type": "object", "description": "A step that conditionally executes one of two possible steps based on a condition.", "required": ["name", "condition"], "properties": { "condition": { "type": "object", "required": ["if", "then"], "properties": { "if": { "type": "string", "description": "Expression that evaluates to a boolean determining which step to execute." }, "then": { "$ref": "#/definitions/Step", "description": "Step to execute if the condition is true." }, "else": { "$ref": "#/definitions/Step", "description": "Optional step to execute if the condition is false." } } } } }, "StopStep": { "type": "object", "description": "A step that signals to end the workflow, with options to end the entire workflow or just the current branch.", "required": ["name", "stop"], "properties": { "name": { "type": "string", "description": "A unique identifier for the step within the flow. Used for referencing step results in expressions.", "pattern": "^[a-zA-Z][a-zA-Z0-9]*$" }, "stop": { "type": "object", "required": ["endWorkflow"], "properties": { "endWorkflow": { "type": "boolean", "description": "Indicates whether to end the entire workflow (true) or just the current branch (false).", "default": true } } } } } } }