482 lines
12 KiB
Markdown
482 lines
12 KiB
Markdown
# JSON Schema Guide
|
|
|
|
Complete schema for diagram specification passed to `mcp-diagram-generator` MCP server.
|
|
|
|
## Root Schema
|
|
|
|
```json
|
|
{
|
|
"$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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"id": "edge-1",
|
|
"type": "edge",
|
|
"source": "device-1",
|
|
"target": "device-2",
|
|
"label": "专线连接",
|
|
"style": {
|
|
"strokeColor": "#FF3333",
|
|
"strokeWidth": 2,
|
|
"endArrow": "arrow",
|
|
"lineStyle": "straight"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Network Topology Example
|
|
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
```json
|
|
{
|
|
"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
|