Variable Schemas

Every step node carries an input_schema and an output_schema. They have the same shape on every node type, regardless of handler_class. process says how a step does its work. The schemas say what it takes in and hands on. A node needs both. Use this page when building nodes for Create a Workflow or Update a Workflow.

Schema

object

required

The variables, keyed by variable ID. Each value is a Variable Definition.

boolean

default:"true"

Whether new variables may be added to this schema later.

Variable Definition

string

required

Variable ID. Must match the key this definition is stored under.

string

required

The name your code and prompts refer to

string

Human-readable label. Defaults to an empty string.

array

required

The types this variable may hold — at least one. Each entry is an Allowed Type.

string

Which of allowed_types is currently active.When set it must name a type present in allowed_types, or the request is rejected. When omitted, the first entry in allowed_types is used.

any

Value used when none is supplied

string

What this variable holds

boolean

default:"false"

Whether the variable may be null

array

Permitted values, when the variable is a fixed choice. Defaults to empty.

array

Extra key/value context, each { variable_name, value, description }. Defaults to empty.

string[]

Fields that may not be edited later. Values are field names such as variable_name, display_name, description, is_nullable, tags, options, allowed_types.

boolean

default:"true"

Whether the variable may be removed

Allowed Type

string

required

One of the supported data types. Defaults to str.

object

The inner shape, for types that have one. What it holds depends on type:

object — a map of variable name to a nested variable definition
array — a single nested variable definition, describing every element
date — a date format string

Leave it unset for scalar types.

boolean

default:"false"

Whether type_definition is enforced at runtime

string[]

Functions the executor applies to resolve the value at runtime. Currently now is supported, for date variables.

Supported Data Types

Type	Description	Example Value
`str`	Text string	`"Hello World"`
`int`	Whole number	`42`
`float`	Decimal number	`45.8`
`bool`	Boolean	`true` or `false`
`date`	Date string — pair with a date format	`"2025-11-09"`
`file`	A single file	`"https://files.opus.com/..."`
`array`	List of values — describe elements with `type_definition`	`["item1", "item2"]`
`object`	Nested object — describe fields with `type_definition`	`{"key": "value"}`
`json_string`	JSON encoded as a string	`"{\"key\":\"value\"}"`
`binary`	Binary data	—
`node`	A reference to another node	—

There is no array_files type. Multiple files are an array whose type_definition is a variable definition with a single allowed type of file.

Date Formats

When type is date, type_definition names the format:

Format	Example
`%Y-%m-%d`	2025-07-23
`%Y-%m-%dT%H:%M`	2025-07-23T15:30
`%m/%d/%Y`	07/23/2025
`%m-%d-%Y`	07-23-2025
`%m.%d.%Y`	07.23.2025
`%d/%m/%Y`	23/07/2025
`%d-%m-%Y`	23-07-2025
`%d.%m.%Y`	23.07.2025
`%B %d, %Y`	July 23, 2025
`%b %d, %Y`	Jul 23, 2025
`%d %B %Y`	23 July 2025
`%Y.%m.%d`	2025.07.23
`%Y-%j`	2025-204 (day of year)
`%Y年%m月%d日`	2025年07月23日
`UNIX`	172169280

Connecting Variables Between Nodes

An edge says two nodes are connected. A mapping says which variable flows across it. Mappings live on the node’s mappings field, keyed by the receiving variable’s ID.

string

default:"output"

Where the value comes from. One of input, output, env or node.

string

ID of the node the value comes from

string

Path to the value within the origin — use dotted notation to reach into an object

object

Fallback mappings, keyed the same way, used when the primary does not resolve

mappings

"mappings": {
  "{RECEIVING_VARIABLE_ID}": {
    "origin": "output",
    "origin_id": "{UPSTREAM_NODE_ID}",
    "variable_path": "summary"
  }
}

Fixed Values

To pin a variable to a constant rather than map it from another node, use set_values:

object

Fixed input values, keyed by variable ID. Each is { value, type }.

object

Fixed output values, keyed by variable ID. Each is { value, type }.

Example

A node taking one string input and returning an array of objects:

{
  "input_schema": {
    "schema": {
      "{VAR_ID_1}": {
        "id": "{VAR_ID_1}",
        "variable_name": "report_text",
        "display_name": "Report Text",
        "description": "The full quarterly report",
        "allowed_types": [{ "type": "str" }],
        "is_nullable": false
      }
    },
    "variable_addition_allowed": true
  },
  "output_schema": {
    "schema": {
      "{VAR_ID_2}": {
        "id": "{VAR_ID_2}",
        "variable_name": "findings",
        "display_name": "Findings",
        "allowed_types": [
          {
            "type": "array",
            "type_definition": {
              "id": "{VAR_ID_3}",
              "variable_name": "finding",
              "allowed_types": [
                {
                  "type": "object",
                  "type_definition": {
                    "title": {
                      "id": "{VAR_ID_4}",
                      "variable_name": "title",
                      "allowed_types": [{ "type": "str" }]
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    },
    "variable_addition_allowed": true
  }
}

Get Started

Workflows

Cases

Files

Business Process Discovery

Integrations

Agents

Deprecated

Schema

Variable Definition

Allowed Type

Supported Data Types

Date Formats

Connecting Variables Between Nodes

Fixed Values

Example

​Schema

​Variable Definition

​Allowed Type

​Supported Data Types

​Date Formats

​Connecting Variables Between Nodes

​Fixed Values

​Example

Schema

Variable Definition

Allowed Type

Supported Data Types

Date Formats

Connecting Variables Between Nodes

Fixed Values

Example