# File format (.flow)

> Structure and key fields of the .flow JSON format for Flow workflows.

A Flow workflow is stored as a `.flow` file — a JSON document that describes the workflow's nodes, the edges that connect them, the node definitions they reference, and the variables that carry data between them.

## Overview

The `.flow` format is designed to be human-readable, diffable in version control, and portable between environments. The visual editor serializes the canvas to this format on save, and parses it back when you open a workflow.

## Top-level structure

```json
{
  "id": "EmailTriage",
  "version": "1.0",
  "name": "Email triage",
  "runtime": "maestro",
  "nodes": [],
  "edges": [],
  "definitions": [],
  "variables": {},
  "bindings": [],
  "layout": {}
}
```

## Key fields

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique workflow identifier. |
| `version` | string | Workflow format version (for example, `1.0`). Drives the migration system that upgrades older files when they are opened. |
| `name` | string | Display name of the workflow. |
| `description` | string | Optional workflow description. |
| `runtime` | string | Execution runtime the workflow targets (for example, `maestro`). |
| `nodes` | array | The workflow's nodes. Each node has an `id`, a `type` that resolves to an entry in `definitions`, a `typeVersion`, a `display` block, and its configured `inputs` (and `outputs` where applicable). |
| `edges` | array | The connections between nodes. Each edge links a source node's output port to a target node's input port. |
| `definitions` | array | The node definitions (manifests) referenced by the nodes in this workflow. Each node's `type` and `typeVersion` resolve to one of these. |
| `variables` | object | The workflow's data: inputs, outputs, and the intermediate values produced by nodes. Node outputs are exposed here so downstream nodes can reference them with `$vars`. |
| `bindings` | array | Bindings that connect the workflow to platform resources (for example, published processes, agents, or connections) it invokes. |
| `subflows` | object | Optional. Nested subflow content, keyed by subflow id; each entry holds its own `nodes`, `edges`, and `variables`. |
| `layout` | object | Canvas layout (node positions and visual arrangement). Stored separately from the nodes so the logical workflow stays diff-friendly. |
| `solutionId`, `projectId` | string | Optional. Identify the Studio Web solution and project backing the workflow when it is part of a solution. |

## Node entry

Each entry in `nodes` follows this shape:

```json
{
  "id": "listInboxEmails1",
  "type": "uipath.connector.uipath-microsoft-outlook365.get-email-list",
  "typeVersion": "1.0.0",
  "display": { "label": "List inbox emails" },
  "inputs": {}
}
```

- `type` is the node's type identifier. It points to a matching `nodeType` in the `definitions` array, which carries the node's configuration form, input definition, and output definition.
- `typeVersion` pins the node to a specific definition version so migrations can upgrade it safely.

## Edge entry

Each entry in `edges` connects two nodes by port:

```json
{
  "id": "weeklyTrigger1-output-process1-input",
  "sourceNodeId": "weeklyTrigger1",
  "sourcePort": "output",
  "targetNodeId": "process1",
  "targetPort": "input"
}
```

## Notes

- The `.flow` file is the canonical source of truth for a workflow. Edits made in the visual editor are serialized to this format on save.
- Manual edits to `.flow` files are intended only for bulk migrations or tooling integrations. Invalid JSON or schema violations prevent the workflow from loading.
- The format evolves across Flow versions. Older files are upgraded automatically by the migration system when opened, based on their `version` and each node's `typeVersion`.
