skills/matthewyin_diagram-generator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
matthewyin_diagram-generator/references/json-schema-guide.md

12 KiB
Raw Permalink Blame History

JSON Schema Guide

Complete schema for diagram specification passed to mcp-diagram-generator MCP server.

Root Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["format", "elements"],
  "properties": {
    "format": {
      "type": "string",
      "enum": ["drawio", "mermaid", "excalidraw"],
      "description": "Target diagram format"
    },
    "title": {
      "type": "string",
      "description": "Diagram title (used as page name in drawio, or header in other formats)"
    },
    "elements": {
      "type": "array",
      "items": {"$ref": "#/definitions/element"},
      "description": "All diagram elements (containers, nodes, edges)"
    }
  },
  "definitions": {
    "element": {
      "oneOf": [
        {"$ref": "#/definitions/container"},
        {"$ref": "#/definitions/node"},
        {"$ref": "#/definitions/edge"}
      ]
    },
    "container": {
      "type": "object",
      "required": ["id", "type", "name"],
      "properties": {
        "id": {"type": "string", "pattern": "^[a-zA-Z0-9_-]+$"},
        "type": {"const": "container"},
        "name": {"type": "string"},
        "level": {
          "type": "string",
          "enum": ["environment", "datacenter", "zone", "other"],
          "description": "Hierarchy level (for network topology)"
        },
        "style": {"$ref": "#/definitions/style"},
        "geometry": {"$ref": "#/definitions/geometry"},
        "children": {
          "type": "array",
          "items": {"$ref": "#/definitions/element"}
        }
      }
    },
    "node": {
      "type": "object",
      "required": ["id", "type", "name"],
      "properties": {
        "id": {"type": "string", "pattern": "^[a-zA-Z0-9_-]+$"},
        "type": {"const": "node"},
        "name": {"type": "string"},
        "deviceType": {
          "type": "string",
          "enum": ["router", "switch", "firewall", "server", "pc", "database", "cloud", "other"],
          "description": "Device type (for network topology styling)"
        },
        "shape": {
          "type": "string",
          "enum": ["rect", "ellipse", "diamond", "parallelogram", "rounded", "cylinder", "cloud", "other"],
          "description": "Node shape (for flowcharts)"
        },
        "style": {"$ref": "#/definitions/style"},
        "geometry": {"$ref": "#/definitions/geometry"}
      }
    },
    "edge": {
      "type": "object",
      "required": ["type", "source", "target"],
      "properties": {
        "id": {"type": "string", "pattern": "^[a-zA-Z0-9_-]+$"},
        "type": {"const": "edge"},
        "source": {"type": "string", "description": "Source node ID"},
        "target": {"type": "string", "description": "Target node ID"},
        "label": {"type": "string", "description": "Edge label"},
        "style": {"$ref": "#/definitions/edgeStyle"}
      }
    },
    "style": {
      "type": "object",
      "properties": {
        "fillColor": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"},
        "strokeColor": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"},
        "strokeWidth": {"type": "number", "minimum": 0},
        "fontColor": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"},
        "fontSize": {"type": "number", "minimum": 6},
        "fontStyle": {"type": "string", "enum": ["normal", "bold", "italic"]},
        "borderRadius": {"type": "number", "minimum": 0},
        "dashPattern": {"type": "string", "description": "e.g., '5,5' for dashed line"}
      }
    },
    "edgeStyle": {
      "type": "object",
      "properties": {
        "strokeColor": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"},
        "strokeWidth": {"type": "number", "minimum": 0},
        "endArrow": {"type": "string", "enum": ["none", "arrow", "circle", "diamond"]},
        "startArrow": {"type": "string", "enum": ["none", "arrow", "circle", "diamond"]},
        "dashPattern": {"type": "string", "description": "e.g., '5,5' for dashed line"},
        "lineStyle": {"type": "string", "enum": ["straight", "orthogonal", "curved"]}
      }
    },
    "geometry": {
      "type": "object",
      "required": ["x", "y"],
      "properties": {
        "x": {"type": "number"},
        "y": {"type": "number"},
        "width": {"type": "number", "minimum": 10},
        "height": {"type": "number", "minimum": 10}
      }
    }
  }
}

Common Element Types

Container (for nested structures)

Used for environments, datacenters, zones, or any grouping.

{
  "id": "env-1",
  "type": "container",
  "name": "省中心管理端",
  "level": "environment",
  "style": {
    "fillColor": "#e1d5e7",
    "strokeColor": "#9673a6",
    "fontSize": 14,
    "fontStyle": "bold"
  },
  "geometry": {
    "x": 220,
    "y": 750,
    "width": 520,
    "height": 450
  },
  "children": [...]
}

Node (individual elements)

Used for devices, components, steps, etc.

{
  "id": "device-1",
  "type": "node",
  "name": "路由器1",
  "deviceType": "router",
  "style": {
    "fillColor": "none",
    "strokeColor": "#607D8B",
    "strokeWidth": 2,
    "fontColor": "#455A64",
    "fontSize": 12,
    "fontStyle": "bold"
  },
  "geometry": {
    "x": 8,
    "y": 25,
    "width": 55,
    "height": 25
  }
}

Edge (connections)

Used to connect nodes.

{
  "id": "edge-1",
  "type": "edge",
  "source": "device-1",
  "target": "device-2",
  "label": "专线连接",
  "style": {
    "strokeColor": "#FF3333",
    "strokeWidth": 2,
    "endArrow": "arrow",
    "lineStyle": "straight"
  }
}

Network Topology Example

{
  "format": "drawio",
  "title": "新架构",
  "elements": [
    {
      "id": "env-1",
      "type": "container",
      "name": "省中心管理端",
      "level": "environment",
      "style": {
        "fillColor": "#e1d5e7",
        "strokeColor": "#9673a6",
        "fontSize": 14,
        "fontStyle": "bold"
      },
      "geometry": {"x": 220, "y": 750, "width": 520, "height": 450},
      "children": [
        {
          "id": "dc-1",
          "type": "container",
          "name": "省中心机房",
          "level": "datacenter",
          "style": {
            "fillColor": "#d5e8d4",
            "strokeColor": "#82b366",
            "fontSize": 12,
            "fontStyle": "bold"
          },
          "geometry": {"x": 15, "y": 30, "width": 485, "height": 400},
          "children": [
            {
              "id": "zone-1",
              "type": "container",
              "name": "上联区",
              "level": "zone",
              "style": {
                "fillColor": "#fff2cc",
                "strokeColor": "#d6b656",
                "fontSize": 10,
                "fontStyle": "bold"
              },
              "geometry": {"x": 93.5, "y": 40, "width": 145, "height": 70},
              "children": [
                {
                  "id": "router-1",
                  "type": "node",
                  "name": "路由器1",
                  "deviceType": "router",
                  "style": {
                    "fillColor": "none",
                    "strokeColor": "#607D8B",
                    "strokeWidth": 2
                  },
                  "geometry": {"x": 8, "y": 25, "width": 55, "height": 25}
                },
                {
                  "id": "router-2",
                  "type": "node",
                  "name": "路由器2",
                  "deviceType": "router",
                  "style": {
                    "fillColor": "none",
                    "strokeColor": "#607D8B",
                    "strokeWidth": 2
                  },
                  "geometry": {"x": 68, "y": 25, "width": 55, "height": 25}
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "edge-1",
      "type": "edge",
      "source": "router-1",
      "target": "router-2",
      "style": {
        "strokeColor": "#333333",
        "endArrow": "none"
      }
    }
  ]
}

Flowchart Example (Mermaid)

{
  "format": "mermaid",
  "title": "用户登录流程",
  "elements": [
    {
      "id": "start",
      "type": "node",
      "name": "开始",
      "shape": "rounded",
      "geometry": {"x": 200, "y": 0}
    },
    {
      "id": "input",
      "type": "node",
      "name": "输入用户名密码",
      "shape": "parallelogram",
      "geometry": {"x": 200, "y": 100}
    },
    {
      "id": "validate",
      "type": "node",
      "name": "验证",
      "shape": "diamond",
      "geometry": {"x": 200, "y": 200}
    },
    {
      "id": "success",
      "type": "node",
      "name": "登录成功",
      "shape": "rounded",
      "geometry": {"x": 100, "y": 350}
    },
    {
      "id": "error",
      "type": "node",
      "name": "显示错误",
      "shape": "rect",
      "geometry": {"x": 300, "y": 350}
    },
    {
      "id": "edge-1",
      "type": "edge",
      "source": "start",
      "target": "input"
    },
    {
      "id": "edge-2",
      "type": "edge",
      "source": "input",
      "target": "validate"
    },
    {
      "id": "edge-3",
      "type": "edge",
      "source": "validate",
      "target": "success",
      "label": "成功"
    },
    {
      "id": "edge-4",
      "type": "edge",
      "source": "validate",
      "target": "error",
      "label": "失败"
    }
  ]
}

Sequence Diagram Example (Mermaid)

{
  "format": "mermaid",
  "title": "API调用流程",
  "elements": [
    {
      "id": "user",
      "type": "node",
      "name": "用户"
    },
    {
      "id": "frontend",
      "type": "node",
      "name": "前端"
    },
    {
      "id": "api",
      "type": "node",
      "name": "API服务"
    },
    {
      "id": "db",
      "type": "node",
      "name": "数据库"
    },
    {
      "id": "edge-1",
      "type": "edge",
      "source": "user",
      "target": "frontend",
      "label": "点击登录"
    },
    {
      "id": "edge-2",
      "type": "edge",
      "source": "frontend",
      "target": "api",
      "label": "POST /login"
    },
    {
      "id": "edge-3",
      "type": "edge",
      "source": "api",
      "target": "db",
      "label": "查询用户"
    },
    {
      "id": "edge-4",
      "type": "edge",
      "source": "db",
      "target": "api",
      "label": "返回数据",
      "style": {
        "lineStyle": "dashed",
        "endArrow": "none"
      }
    }
  ]
}

Style Presets

Network Topology Levels

Level fillColor strokeColor fontSize
environment #e1d5e7 #9673a6 14
datacenter #d5e8d4 #82b366 12
zone #fff2cc #d6b656 10

Device Types

deviceType strokeColor
router #607D8B
switch #4CAF50
firewall #F44336
server #2196F3
pc #607D8B
database #9C27B0
cloud #9E9E9E

Flowchart Shapes

shape Usage
rect Process step
rounded Start/end
parallelogram Input/output
diamond Decision
cylinder Database
cloud External system

Best Practices

ID Generation

  • Use descriptive prefixes: env-, dc-, zone-, device-, edge-
  • Keep IDs short but unique: env-1, router-2
  • Avoid spaces or special characters (except _, -)

Geometry for Network Topology

  • Container coordinates are relative to their parent
  • Device coordinates are relative to their containing zone
  • Standard device size: 55 x 25
  • Leave padding: at least 10 units between elements

Edge Routing

  • For drawio: source/target can reference any node ID
  • Edges can cross container boundaries
  • Use lineStyle: "orthogonal" for clean routing in complex diagrams

Performance

  • Limit total elements to ~100 for good performance
  • Use containers to group related elements
  • For very large diagrams, split into multiple pages
Reference in New Issue View Git Blame Copy Permalink