# Modly Workflow JSON Structure: Complete Schema and Field Reference

> Explore the Modly workflow JSON structure. Understand the complete schema and field reference for defining your workflows with nodes and edges.

- Repository: [lightningpixel/modly](https://github.com/lightningpixel/modly)
- Tags: api-reference
- Published: 2026-08-21

---

**A Modly workflow is stored as a plain JSON object that conforms to the `Workflow` interface, containing metadata fields and two primary collections—`nodes` (`WFNode[]`) and `edges` (`WFEdge[]`)—that define the visual execution graph.**

The `lightningpixel/modly` repository uses a React-Flow-based visual editor where workflows are serialized to JSON for persistence and version control. Understanding the **Modly workflow JSON structure** is essential for importing, exporting, or programmatically generating automation pipelines that the runtime can execute.

## Core Workflow Schema

The root object follows the `Workflow` interface declared in [`src/shared/types/electron.d.ts`](https://github.com/lightningpixel/modly/blob/main/src/shared/types/electron.d.ts). It balances descriptive metadata with the structural data required to render the node graph.

### Required Metadata Fields

Every workflow must include these top-level properties:

- `id`: Unique string identifier for the workflow
- `name`: Human-readable title displayed in the UI
- `description`: Optional longer explanation of the workflow's purpose
- `nodes`: Array of `WFNode` objects representing extension instances
- `edges`: Array of `WFEdge` objects defining connections between nodes
- `createdAt`: ISO-8601 timestamp of creation
- `updatedAt`: ISO-8601 timestamp of last modification

### Organization and Bookmarking Fields

Optional fields control how the workflow appears in the browser:

- `folder`: String specifying the folder name; omit for root placement
- `bookmarked`: Boolean flag; when `true`, the workflow appears in the Bookmarks section

## Node Structure (WFNode)

Each element in the `nodes` array implements the `WFNode` interface, mapping directly to React-Flow's node specification while adding Modly-specific runtime data.

### Visual Positioning and Identity

The visual representation relies on:

- `id`: Unique node identifier referenced by edge `source` and `target` fields
- `type`: String identifying the node type, typically matching the extension's entry point
- `position`: Object with `x` and `y` number coordinates for canvas placement
- `parentId`: Optional string for grouping nodes into sub-flows
- `extent`: Optional string `'parent'` restricting movement within group boundaries
- `width` and `height`: Optional numbers defining group node dimensions
- `style`: Optional record for CSS overrides

### Runtime Configuration (WFNodeData)

The `data` field contains a `WFNodeData` object with execution parameters:

- `extensionId`: String linking to the specific extension implementation
- `enabled`: Boolean flag controlling whether the node executes during a run
- `params`: Free-form object storing extension-specific configuration values

## Edge Structure (WFEdge)

Connections between nodes follow the `WFEdge` interface:

- `id`: Unique edge identifier
- `source`: String ID of the originating node
- `target`: String ID of the terminating node
- `sourceHandle`: Optional string or `null` specifying the output slot
- `targetHandle`: Optional string or `null` specifying the input slot

## Complete Modly Workflow JSON Example

```json
{
  "id": "wf-01",
  "name": "Generate Hero",
  "description": "Creates a hero character mesh from a prompt",
  "folder": "Demo",
  "bookmarked": true,
  "nodes": [
    {
      "id": "node-1",
      "type": "text-prompt",
      "position": { "x": 0, "y": 0 },
      "data": {
        "extensionId": "ext-text-prompt",
        "enabled": true,
        "params": { "prompt": "A heroic knight in armor" }
      }
    },
    {
      "id": "node-2",
      "type": "mesh-generator",
      "position": { "x": 300, "y": 0 },
      "data": {
        "extensionId": "ext-mesh-gen",
        "enabled": true,
        "params": { "size": 1.0 }
      }
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "source": "node-1",
      "target": "node-2",
      "sourceHandle": null,
      "targetHandle": null
    }
  ],
  "createdAt": "2024-01-15T12:00:00Z",
  "updatedAt": "2024-01-20T09:34:21Z"
}

```

This example demonstrates a workflow with two nodes—a text prompt feeding into a mesh generator—connected by a single edge, organized under the "Demo" folder and flagged for bookmarks.

## Type Definitions and Implementation Files

The schema is enforced across several key files in the `lightningpixel/modly` codebase:

- [`src/shared/types/electron.d.ts`](https://github.com/lightningpixel/modly/blob/main/src/shared/types/electron.d.ts): Declares the `Workflow`, `WFNode`, and `WFEdge` interfaces used throughout the application
- [`src/areas/workflows/workflowRunStore.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/workflowRunStore.ts): Implements runtime loading, validation, and execution of workflow JSON objects
- [`src/shared/stores/workflowsStore.ts`](https://github.com/lightningpixel/modly/blob/main/src/shared/stores/workflowsStore.ts): Handles persistence operations including listing, saving, importing, and exporting workflows
- [`src/areas/workflows/preflight.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/preflight.ts): Performs static analysis on workflow JSON to detect missing inputs and circular dependencies
- [`src/areas/workflows/mockExtensions.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/mockExtensions.ts): Provides mock extension definitions for testing workflow structures

## Summary

- The **Modly workflow JSON structure** consists of a root `Workflow` object with metadata and two arrays: `nodes` and `edges`
- **Nodes** (`WFNode`) combine React-Flow visual properties (`position`, `type`) with runtime configuration (`extensionId`, `enabled`, `params`)
- **Edges** (`WFEdge`) connect node outputs to inputs using `source`, `target`, and optional handle identifiers
- Type definitions reside in [`src/shared/types/electron.d.ts`](https://github.com/lightningpixel/modly/blob/main/src/shared/types/electron.d.ts) and are validated by [`workflowRunStore.ts`](https://github.com/lightningpixel/modly/blob/main/workflowRunStore.ts) during execution
- All timestamps follow ISO-8601 format for version-control compatibility

## Frequently Asked Questions

### What is the minimum valid Modly workflow JSON?

A valid object requires `id`, `name`, `nodes` (empty array allowed), `edges` (empty array allowed), `createdAt`, and `updatedAt` fields conforming to the `Workflow` interface in [`src/shared/types/electron.d.ts`](https://github.com/lightningpixel/modly/blob/main/src/shared/types/electron.d.ts). The `description`, `folder`, and `bookmarked` fields are optional.

### How does Modly validate workflow JSON before execution?

The [`workflowRunStore.ts`](https://github.com/lightningpixel/modly/blob/main/workflowRunStore.ts) module loads and validates the JSON against the TypeScript interfaces, while [`src/areas/workflows/preflight.ts`](https://github.com/lightningpixel/modly/blob/main/src/areas/workflows/preflight.ts) performs static analysis to check for missing inputs and circular dependencies before the runtime executes the graph.

### Can I manually edit the params object in a workflow JSON file?

Yes, the `params` field inside `WFNodeData` is a free-form object that accepts any extension-specific configuration values, making it safe to edit directly for batch updates or version control operations without breaking the schema.

### What determines a node's position on the canvas?

The `position` object with `x` and `y` number properties controls canvas placement, while optional `parentId` and `extent: 'parent'` fields constrain the node within group boundaries for nested layouts.