Edge structure

The JSON format for workflow edges — connections between nodes, handle IDs, and edge categories.

Every item in a workflow’s edges array is a WorkflowEdge. It represents a connection between an output port on one node and an input port on another.

Schema

interface WorkflowEdge {
  id: string;
  source: string;
  target: string;
  sourceHandle?: string;
  targetHandle?: string;
  type?: ConnectionLineType;
  selectable?: boolean;
  deletable?: boolean;
  data?: {
    label?: string;
    condition?: string;
    metadata?: {
      edgeType?: EdgeCategory;
      sourcePortDataType?: string;
    };
  };
}

Field	Type	Required	Description
id	string	Yes	Unique edge identifier (e.g., "e-loader-analyzer").
source	string	Yes	ID of the source node.
target	string	Yes	ID of the target node.
sourceHandle	string	No	ID of the specific output port. See Handle IDs.
targetHandle	string	No	ID of the specific input port. See Handle IDs.
selectable	boolean	No	Whether the edge can be selected in the editor.
deletable	boolean	No	Whether the edge can be deleted by the user.
data.label	string	No	Display label on the edge.
data.condition	string	No	Condition expression (used with gateway branches).
data.metadata.edgeType	EdgeCategory	No	Visual styling category.
data.metadata.sourcePortDataType	string	No	Data type of the source output port.

Handle IDs

Port handles follow a deterministic naming pattern:

{nodeId}-{direction}-{portId}

For example:

• content_loader.1-output-items — the “items” output port on node content_loader.1
• analyzer.1-input-content — the “content” input port on node analyzer.1
• router.1-output-high — the “high” branch output on a gateway node

This format lets FlowDrop map edges back to specific ports during rendering and execution.

Edge Categories

The edgeType field controls the visual style of the edge on the canvas:

Category	Visual Style	When Used
data	Solid gray line	Default — general data flow between nodes.
trigger	Solid line with trigger color	Control flow connections (port dataType: "trigger").
tool	Dashed amber line	Tool interface connections (port dataType: "tool").
loopback	Dashed gray line	Loop iteration connections (targets a loop_back port).

The editor sets edgeType automatically based on the source port’s data type. You generally don’t need to set it manually in JSON.

Examples

Data Edge

A simple data connection between two ports:

{
  "id": "e-loader-analyzer",
  "source": "content_loader.1",
  "target": "analyzer.1",
  "sourceHandle": "content_loader.1-output-items",
  "targetHandle": "analyzer.1-input-content"
}

Trigger Edge

A control-flow connection that triggers execution:

{
  "id": "e-start-loader",
  "source": "start.1",
  "target": "content_loader.1",
  "sourceHandle": "start.1-output-trigger",
  "targetHandle": "content_loader.1-input-trigger",
  "data": {
    "metadata": {
      "edgeType": "trigger",
      "sourcePortDataType": "trigger"
    }
  }
}

Tool Edge

A dashed connection linking an agent to a tool:

{
  "id": "e-agent-tool",
  "source": "search_tool.1",
  "target": "agent.1",
  "sourceHandle": "search_tool.1-output-tool",
  "targetHandle": "agent.1-input-tool",
  "data": {
    "metadata": {
      "edgeType": "tool",
      "sourcePortDataType": "tool"
    }
  }
}

Gateway Branch Edge

A conditional edge from a gateway branch:

{
  "id": "e-router-high",
  "source": "router.1",
  "target": "urgent_handler.1",
  "sourceHandle": "router.1-output-high",
  "targetHandle": "urgent_handler.1-input-input",
  "data": {
    "condition": "priority > 8",
    "metadata": {
      "edgeType": "data"
    }
  }
}

Connection Validation

The editor validates connections automatically before creating edges:

• Type compatibility — only compatible port data types can connect
• Cycle detection — prevents circular dependencies (O(V+E) algorithm)
• Loopback prevention — nodes cannot connect to themselves

For more on data type compatibility rules, see Port System & Data Types.

Next Steps

• Node Structure — the nodes that edges connect
• Port System & Data Types — port definitions and compatibility rules
• Workflow Structure — the top-level document containing edges