ToDiagram Format

Build architecture diagrams, system designs, and process flows with full control over nodes and edges using the ToDiagram format (.todiagram). The format is JSON-based and saved as .todiagram files.

JSON Schema

The canonical JSON Schema for this format is available at:

https://todiagram.com/schemas/todiagram.json

Example

{
  "nodes": [
    {
      "id": "client",
      "label": "Mobile App",
      "imageUrl": "https://cdn-icons-png.flaticon.com/512/149/149071.png"
    },
    {
      "id": "api-gateway",
      "label": "API Gateway",
      "fields": {
        "port": 443,
        "protocol": "HTTPS",
        "requests_per_sec": 1500
      }
    },
    {
      "id": "backend",
      "label": "Backend Services",
      "nodes": [
        {
          "id": "auth-service",
          "label": "Auth Service",
          "fields": {
            "status": "healthy",
            "uptime": 99.9
          }
        },
        {
          "id": "data-service",
          "label": "Data Service",
          "fields": {
            "instances": 3,
            "load_balanced": true
          }
        }
      ]
    },
    {
      "id": "database",
      "label": "PostgreSQL",
      "imageUrl": "https://cdn-icons-png.flaticon.com/512/5968/5968342.png"
    }
  ],
  "edges": [
    { "from": "client", "to": "api-gateway", "label": "HTTPS Request" },
    { "from": "api-gateway", "to": "auth-service", "label": "Authenticate" },
    { "from": "api-gateway", "to": "data-service", "label": "Fetch Data" },
    { "from": "auth-service", "to": "database", "label": "Verify User" },
    { "from": "data-service", "to": "database", "label": "Query" }
  ]
}

Open Live Example: System Architecture Diagram

Custom Theming

You can add a custom_theme field to any node to fully customize its appearance using a custom theme. This allows you to override default styles, colors, and more for individual nodes or groups. See the Custom Theme Guide for details and examples.

Example:

{
  "id": "api-gateway",
  "label": "API Gateway",
  "custom_theme": {
    "NODE": {
      "NODE": "#1e293b",
    },
    "EDGE": {
      "EDGE": "#38bdf8",
      "LABEL": "#fff"
    },
    "TEXT": {
      "TEXT": "#fff"
    }
  }
}

Icons

You can use any of the 200,000+ icons available on iconify.design for imageUrl or iconUrl. The format is set:icon-name, for example fa:user or fa:desktop. Use valid Iconify names; invalid names will not render.

{
  "id": "server",
  "label": "Web Server",
  "imageUrl": "fa:desktop"
}

Structure

Nodes

Every node must have an id field. Use the fields object to add key-value pairs that are displayed as rows on the node card.

Prop

Type

Fields Example:

{
  "id": "server",
  "label": "API Server",
  "iconUrl": "fa:server",
  "fields": {
    "port": 3000,
    "status": "active",
    "uptime": 99.9,
    "ssl": true
  }
}

Deprecated: top-level extra properties

Top-level extra properties on a node are deprecated and may be removed in a future version. Always use the fields object for key-value display data.

Edges

Edges define connections between nodes.

Prop

Type

Configuration

You can include an optional configuration object at the root level to customize field mappings. This is useful when your data has field names that conflict with the defaults (e.g., a column named id or label).

Schema Field Mappings

The configuration.schema object lets you override which fields are used for node IDs, labels, edges, etc.

{
  "configuration": {
    "schema": {
      "keys": {
        "nodes": "nodes",
        "edges": "edges",
        "direction": "direction"
      },
      "node": {
        "id": "id",
        "label": "label",
        "imageUrl": "imageUrl",
        "iconUrl": "iconUrl",
        "customTheme": "custom_theme"
      },
      "edge": {
        "from": "from",
        "to": "to",
        "label": "label"
      }
    }
  },
  "nodes": [...],
  "edges": [...]
}

Example: Custom ID Field

If your data uses name as the unique identifier instead of id:

{
  "configuration": {
    "schema": {
      "node": { "id": "name" }
    }
  },
  "nodes": [
    { "name": "server-1", "fields": { "status": "running" } },
    { "name": "server-2", "fields": { "status": "stopped" } }
  ],
  "edges": [
    { "from": "server-1", "to": "server-2" }
  ]
}

Example: Database Schema Diagram

Column names like id or label can be used freely inside the fields object without conflicting with reserved node keys:

{
  "nodes": [
    {
      "id": "users",
      "label": "users",
      "iconUrl": "logos:postgresql",
      "fields": {
        "id": "🔑 uuid",
        "email": "varchar *",
        "name": "varchar"
      }
    },
    {
      "id": "posts",
      "label": "posts",
      "iconUrl": "logos:postgresql",
      "fields": {
        "id": "🔑 uuid",
        "user_id": "🔗 uuid",
        "title": "varchar *"
      }
    }
  ],
  "edges": [
    { "from": "posts", "to": "users", "label": "user_id" }
  ]
}

On this page