JFDG Specification v1.0

JsonFiddle Diagram Graph — a JSON-native format for node-edge diagrams.

Overview

JFDG is an open diagram format that uses plain JSON to describe nodes, edges, and visual properties. Unlike text-based formats (Mermaid, DOT) or XML-heavy formats (GraphML), JFDG is designed to be:

• Human-readable — write and edit diagrams in any text editor
• JSON-native — no compilation step, no custom syntax to learn
• IDE-friendly — full autocomplete and validation via JSON Schema
• Metadata-rich — attach arbitrary key-value data to any node
• Visually complete — positions, icons, themes, and grouping are part of the format

File Extension & MIME Type

Quick Example

{
  "$schema": "https://jsonfiddle.com/schemas/jfdg-1.0.json",
  "nodes": [
    { "id": "api", "label": "API Gateway", "iconUrl": "mdi:shield-check", "position": { "x": 0, "y": 100 } },
    { "id": "auth", "label": "Auth Service", "iconUrl": "mdi:lock", "position": { "x": 300, "y": 0 } },
    { "id": "db", "label": "PostgreSQL", "iconUrl": "mdi:database", "position": { "x": 300, "y": 200 } }
  ],
  "edges": [
    { "from": "api", "to": "auth", "label": "verify token" },
    { "from": "api", "to": "db", "label": "query" }
  ]
}

Document Structure

A JFDG document is a JSON object with three top-level keys:

{
  "nodes": [...],        // Required — list of nodes
  "edges": [...],        // Required — list of edges
  "configuration": {...} // Optional — layout and theme settings
}

Nodes

Each node is an object with a required id and optional visual/structural properties.

Required Properties

Optional Properties

Metadata (Additional Properties)

Any property not in the reserved list above is treated as metadata and displayed in the node's detail panel. This is a core JFDG feature — it allows diagrams to carry structured data.

{
  "id": "users-table",
  "label": "Users",
  "iconUrl": "mdi:database",
  "email": "string",
  "name": "string",
  "created_at": "timestamp",
  "role": "enum(admin, user, guest)"
}

The metadata fields (email, name, created_at, role) are displayed inside the node card, making JFDG useful for ER diagrams, API documentation, infrastructure maps, and any diagram where nodes carry data.

Group Nodes

A node with a nodes array becomes a group — a visual container for child nodes.

{
  "id": "vpc",
  "label": "VPC",
  "position": { "x": 100, "y": 50 },
  "width": 500,
  "height": 300,
  "nodes": [
    { "id": "web", "label": "Web Server", "position": { "x": 30, "y": 40 } },
    { "id": "db", "label": "Database", "position": { "x": 250, "y": 40 } }
  ]
}

Child node positions are stored in absolute canvas coordinates, the same as top-level nodes. A renderer may convert them to parent-relative coordinates internally, but the source JSON should keep absolute positions so moving nodes between groups does not require coordinate translation.

Groups can be nested by placing a group node inside another group's nodes array:

{
  "id": "vpc",
  "label": "VPC",
  "position": { "x": 100, "y": 50 },
  "width": 600,
  "height": 500,
  "nodes": [
    {
      "id": "workflow",
      "label": "Workflow",
      "position": { "x": 160, "y": 180 },
      "width": 360,
      "height": 240,
      "nodes": [
        { "id": "validate", "label": "Validate Request", "position": { "x": 220, "y": 230 } },
        { "id": "fetch", "label": "Fetch", "position": { "x": 240, "y": 330 } }
      ]
    }
  ]
}

Groups render as dashed-border containers with a floating label. Node IDs must remain globally unique across all nesting levels.

Nested group bounds should fit inside their parent group. If a nested group is larger than, or positioned outside, its parent, renderers may treat it as a top-level visual group to keep both groups selectable on the canvas.

Edges

Each edge connects two nodes by their id.

Direction

Controls where arrowheads appear:

Animation

When animated is true, dashes march along the edge indicating active flow. The animation always moves from source to target regardless of the direction setting — arrowheads communicate directionality, animation communicates liveness.

{ "from": "api", "to": "db", "label": "queries", "style": "dashed", "direction": "both", "animated": true }

Bidirectional animated edges can choose a bidiEffect:

Edges can connect nodes across group boundaries. Handle selection (which side the edge connects from/to) is computed automatically based on relative node positions.

Manual Waypoints

By default, edges use generated routing. Select an edge in the editor to reveal two draggable waypoints; moving either point stores a two-point waypoints route for that edge:

{
  "from": "client",
  "to": "gateway",
  "label": "HTTPS",
  "waypoints": [
    { "x": 180, "y": 80 },
    { "x": 360, "y": 80 }
  ]
}

Removing waypoints returns the edge to generated routing. Older files with more than two waypoints still load, but the editor presents them as two draggable control points.

Configuration

Optional global settings.

{
  "configuration": {
    "layout": "auto",
    "theme": "azure",
    "schema": {
      "users-table": {
        "email": "string",
        "role": "enum"
      }
    }
  }
}

Layout Modes

Auto Layout

When layout is "auto" (or when no nodes have position values), the ELK algorithm arranges nodes automatically. This is ideal for quickly visualizing data without manually positioning.

Manual Layout

When any node has explicit position coordinates, the layout defaults to manual. Positions are preserved exactly as specified, and users can drag nodes on the canvas.

Theming

JFDG supports both global themes (via configuration.theme) and per-node overrides (via custom_theme).

Theme Object Structure

{
  "NODE": { "NODE": "#f0f7ff", "HEADER": "#dbeafe" },
  "EDGE": { "EDGE": "#60a5fa", "LABEL": "#3b82f6" },
  "TEXT": { "TEXT": "#1e3a5f", "ROW_KEY": "#2563eb" }
}

Built-in Presets

Format Comparison

Icons

JFDG uses Iconify notation for icons, giving access to 200,000+ icons from 150+ icon sets:

• Material Design: mdi:database, mdi:server, mdi:lock
• Simple Icons (logos): simple-icons:aws, simple-icons:docker
• Logos: logos:react, logos:kubernetes

Any valid Iconify identifier works. Alternatively, iconUrl can be a direct URL to an image.

Validation

A JFDG document is valid if:

1. It is valid JSON
2. It has a nodes array and an edges array at the top level
3. Every node has a unique id matching ^[a-zA-Z][a-zA-Z0-9_-]*$
4. Every edge references existing node ids in from and to
5. No circular group nesting (a node cannot be its own ancestor)

Versioning

The schema URL includes the version number: jfdg-1.0.json. Future versions will maintain backward compatibility — new fields will be additive, existing fields will not change semantics.