Workflow structure

The JSON format for FlowDrop workflows — top-level fields, metadata, and how nodes and edges fit together.

A workflow is the top-level JSON document that FlowDrop reads and writes. It contains an array of nodes, an array of edges connecting them, and a metadata object.

Schema

interface Workflow {
  id: string;
  name: string;
  description?: string;
  nodes: WorkflowNode[];
  edges: WorkflowEdge[];
  metadata: WorkflowMetadata;
}

Field	Type	Required	Description
id	string	Yes	Unique identifier for the workflow (typically a UUID).
name	string	Yes	Human-readable name displayed in the editor navbar.
description	string	No	Brief summary of the workflow’s purpose.
nodes	WorkflowNode[]	Yes	Array of node instances placed on the canvas. See Node Structure.
edges	WorkflowEdge[]	Yes	Array of connections between nodes. See Edge Structure.
metadata	object	Yes	Version tracking and authoring information.

Metadata

interface WorkflowMetadata {
  schemaVersion: string; // Document-format version (not the workflow's own revision)
  createdAt: string; // ISO 8601 timestamp
  updatedAt: string; // ISO 8601 timestamp
  author?: string;
  tags?: string[];
  versionId?: string; // UUID for this specific version
  updateNumber?: number; // Incrementing revision counter
  format?: WorkflowFormat; // "flowdrop" | "agentspec" | custom string
}

schemaVersion, createdAt, and updatedAt are required on the metadata object. schemaVersion identifies the document format — not the workflow’s own revision history.

The format field determines which nodes appear in the sidebar and how the workflow is exported. The default is "flowdrop". Set it to "agentspec" for workflows compatible with the Oracle Open Agent Spec.

Minimal Example

The smallest valid workflow — an empty canvas ready for editing:

{
  "id": "my-workflow",
  "name": "My Workflow",
  "nodes": [],
  "edges": [],
  "metadata": {
    "schemaVersion": "1.0.0",
    "createdAt": "2025-11-12T21:29:32.473Z",
    "updatedAt": "2025-11-12T21:29:32.473Z"
  }
}

Full Example

A workflow with two connected nodes and complete metadata:

{
  "id": "content-pipeline",
  "name": "Content Processing Pipeline",
  "description": "Load articles and analyze them with AI",
  "nodes": [
    {
      "id": "content_loader.1",
      "type": "universalNode",
      "position": { "x": 0, "y": 100 },
      "data": {
        "label": "Content Loader",
        "config": {
          "contentType": "article",
          "limit": 50
        },
        "metadata": {
          "id": "content_loader",
          "name": "Content Loader",
          "type": "tool",
          "description": "Load content for batch processing",
          "category": "content",
          "icon": "mdi:database-import",
          "version": "1.0.0",
          "inputs": [],
          "outputs": [
            {
              "id": "items",
              "name": "Items",
              "type": "output",
              "dataType": "array"
            }
          ]
        }
      }
    },
    {
      "id": "analyzer.1",
      "type": "universalNode",
      "position": { "x": 400, "y": 100 },
      "data": {
        "label": "AI Analyzer",
        "config": {
          "confidenceThreshold": 0.8
        },
        "metadata": {
          "id": "ai_analyzer",
          "name": "AI Analyzer",
          "type": "tool",
          "description": "AI-powered content analysis",
          "category": "ai",
          "icon": "mdi:brain",
          "version": "1.0.0",
          "inputs": [
            {
              "id": "content",
              "name": "Content",
              "type": "input",
              "dataType": "array"
            }
          ],
          "outputs": [
            {
              "id": "results",
              "name": "Results",
              "type": "output",
              "dataType": "json"
            }
          ]
        }
      }
    }
  ],
  "edges": [
    {
      "id": "e-loader-analyzer",
      "source": "content_loader.1",
      "target": "analyzer.1",
      "sourceHandle": "content_loader.1-output-items",
      "targetHandle": "analyzer.1-input-content"
    }
  ],
  "metadata": {
    "schemaVersion": "1.0.0",
    "createdAt": "2025-11-12T21:29:32.473Z",
    "updatedAt": "2025-11-12T21:29:32.473Z",
    "author": "demo",
    "tags": ["ai", "content"],
    "format": "flowdrop"
  }
}

Import and Export

For programmatic access to workflows, see Creating Workflows — Import and Export.

Next Steps

• Node Structure — anatomy of each node in the nodes array
• Edge Structure — how connections in the edges array work
• Configuration Schema — JSON Schema that powers node config forms