> ## Documentation Index
> Fetch the complete documentation index at: https://developer.opus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variable Schemas

> How a node declares the variables it takes in and hands on

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](/api-reference/v1-workflow-generation/create-workflow) or [Update a Workflow](/api-reference/v1-workflow-generation/update-workflow).

## Schema

<ParamField body="schema" type="object" required>
  The variables, keyed by variable ID. Each value is a [Variable Definition](#variable-definition).
</ParamField>

<ParamField body="variable_addition_allowed" type="boolean" default="true">
  Whether new variables may be added to this schema later.
</ParamField>

## Variable Definition

<ParamField body="id" type="string" required>
  Variable ID. Must match the key this definition is stored under.
</ParamField>

<ParamField body="variable_name" type="string" required>
  The name your code and prompts refer to
</ParamField>

<ParamField body="display_name" type="string">
  Human-readable label. Defaults to an empty string.
</ParamField>

<ParamField body="allowed_types" type="array" required>
  The types this variable may hold — **at least one**. Each entry is an [Allowed Type](#allowed-type).
</ParamField>

<ParamField body="current_type" 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.
</ParamField>

<ParamField body="default" type="any">
  Value used when none is supplied
</ParamField>

<ParamField body="description" type="string">
  What this variable holds
</ParamField>

<ParamField body="is_nullable" type="boolean" default="false">
  Whether the variable may be null
</ParamField>

<ParamField body="options" type="array">
  Permitted values, when the variable is a fixed choice. Defaults to empty.
</ParamField>

<ParamField body="tags" type="array">
  Extra key/value context, each `{ variable_name, value, description }`. Defaults to empty.
</ParamField>

<ParamField body="non_editable_fields" type="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`.
</ParamField>

<ParamField body="can_delete" type="boolean" default="true">
  Whether the variable may be removed
</ParamField>

## Allowed Type

<ParamField body="type" type="string" required>
  One of the [supported data types](#supported-data-types). Defaults to `str`.
</ParamField>

<ParamField body="type_definition" type="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](#date-formats) string

  Leave it unset for scalar types.
</ParamField>

<ParamField body="type_definition_enforced" type="boolean" default="false">
  Whether `type_definition` is enforced at runtime
</ParamField>

<ParamField body="functions" type="string[]">
  Functions the executor applies to resolve the value at runtime. Currently `now` is supported, for date variables.
</ParamField>

## 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](#date-formats) | `"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 | — |

<Note>
  **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`.
</Note>

### 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.

<ParamField body="origin" type="string" default="output">
  Where the value comes from. One of `input`, `output`, `env` or `node`.
</ParamField>

<ParamField body="origin_id" type="string">
  ID of the node the value comes from
</ParamField>

<ParamField body="variable_path" type="string">
  Path to the value within the origin — use dotted notation to reach into an `object`
</ParamField>

<ParamField body="alternative_mappings" type="object">
  Fallback mappings, keyed the same way, used when the primary does not resolve
</ParamField>

```json mappings theme={null}
"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`:

<ParamField body="input_set_values" type="object">
  Fixed input values, keyed by variable ID. Each is `{ value, type }`.
</ParamField>

<ParamField body="output_set_values" type="object">
  Fixed output values, keyed by variable ID. Each is `{ value, type }`.
</ParamField>

## Example

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

```json theme={null}
{
  "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
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.