{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://excali-ft/dsl.schema.json",
  "title": "Excalidraw Diagram DSL",
  "description": "Compact, semantic-only description of a diagram. Carries planning decisions (what exists, what connects, what type). All geometry, sizing, IDs, colors, and Excalidraw format fields are computed deterministically by the converter and MUST NOT appear here.",
  "type": "object",
  "additionalProperties": false,
  "required": ["diagram", "title", "nodes"],
  "properties": {
    "diagram": {
      "description": "Selects the converter strategy and default layout.",
      "type": "string",
      "enum": [
        "system_architecture",
        "flowchart",
        "er_diagram",
        "sequence_diagram",
        "data_pipeline",
        "timeline",
        "mind_map",
        "mobile_wireframe"
      ]
    },
    "title": {
      "description": "Human-readable diagram title, rendered as a heading text element.",
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "direction": {
      "description": "Primary flow/layout direction. Optional; the converter applies a per-diagram default when omitted (e.g. TB for flowchart, LR for architecture, radial for mind_map).",
      "type": "string",
      "enum": ["LR", "RL", "TB", "BT", "radial"]
    },
    "nodes": {
      "description": "The boxes/entities/participants/milestones. Internal `id`s are reference handles only and are never rendered.",
      "type": "array",
      "minItems": 1,
      "maxItems": 40,
      "items": { "$ref": "#/$defs/node" }
    },
    "edges": {
      "description": "Connections between nodes. For sequence_diagram, array order is message order. May be empty (e.g. some timelines/mind maps without explicit links).",
      "type": "array",
      "maxItems": 80,
      "items": { "$ref": "#/$defs/edge" },
      "default": []
    },
    "groups": {
      "description": "Optional clusters/swimlanes/screens. A node joins a group via node.group = group.id.",
      "type": "array",
      "maxItems": 12,
      "items": { "$ref": "#/$defs/group" },
      "default": []
    },
    "meta": {
      "description": "Diagram-level escape hatch for type-specific knobs. Keep empty unless a type below defines a key.",
      "type": "object",
      "additionalProperties": true,
      "default": {}
    }
  },

  "$defs": {
    "id": {
      "description": "Stable snake_case identifier, unique within its collection. Reference handle only — not rendered.",
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]*$",
      "minLength": 1,
      "maxLength": 40
    },
    "label": {
      "description": "Visible text. Non-empty, single line preferred.",
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "role": {
      "description": "Semantic kind of the node. The converter maps role -> {shape, fill color, stroke color}. The model never picks shapes or colors directly.",
      "type": "string",
      "enum": [
        "actor",
        "client",
        "service",
        "gateway",
        "database",
        "cache",
        "queue",
        "worker",
        "storage",
        "external",
        "monitoring",
        "auth",
        "start",
        "end",
        "process",
        "decision",
        "io",
        "source",
        "transform",
        "sink",
        "entity",
        "participant",
        "milestone",
        "root",
        "branch",
        "leaf",
        "screen",
        "ui_element",
        "component",
        "generic"
      ]
    },
    "node": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "label", "role"],
      "properties": {
        "id": { "$ref": "#/$defs/id" },
        "label": { "$ref": "#/$defs/label" },
        "role": { "$ref": "#/$defs/role" },
        "group": {
          "description": "Optional group membership; must equal some groups[].id.",
          "$ref": "#/$defs/id"
        },
        "color": {
          "description": "OPTIONAL explicit override only when a human would intentionally choose a color (e.g. emphasis). Otherwise omit and let the converter derive color from role.",
          "type": "string",
          "enum": ["red", "orange", "yellow", "green", "blue", "violet", "gray", "black"]
        },
        "meta": {
          "description": "Type-specific node data. See per-diagram rules in DSL_SPEC.md. Examples: er_diagram fields, timeline date, wireframe ui kind.",
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "fields": {
              "description": "er_diagram only: entity columns.",
              "type": "array",
              "maxItems": 20,
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": ["name"],
                "properties": {
                  "name": { "type": "string", "minLength": 1, "maxLength": 40 },
                  "type": { "type": "string", "maxLength": 30 },
                  "key": { "type": "string", "enum": ["pk", "fk", "none"], "default": "none" }
                }
              }
            },
            "date": {
              "description": "timeline only: ISO-ish date or short label used for ordering and display.",
              "type": "string",
              "maxLength": 30
            },
            "kind": {
              "description": "mobile_wireframe only: the UI element kind.",
              "type": "string",
              "enum": ["header", "nav", "text", "input", "button", "list", "image", "card", "tab", "footer"]
            }
          }
        }
      }
    },
    "edge": {
      "type": "object",
      "additionalProperties": false,
      "required": ["from", "to"],
      "properties": {
        "from": {
          "description": "Source node id. Must reference an existing node.",
          "$ref": "#/$defs/id"
        },
        "to": {
          "description": "Target node id. Must reference an existing node.",
          "$ref": "#/$defs/id"
        },
        "label": {
          "description": "Optional edge label. For flowchart decision branches use 'yes'/'no'.",
          "type": "string",
          "maxLength": 40
        },
        "style": {
          "description": "Line style. Default solid.",
          "type": "string",
          "enum": ["solid", "dashed", "dotted"],
          "default": "solid"
        },
        "meta": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "cardinality": {
              "description": "er_diagram only: relationship cardinality.",
              "type": "string",
              "enum": ["1:1", "1:N", "N:1", "N:M"]
            },
            "kind": {
              "description": "sequence_diagram only: message kind.",
              "type": "string",
              "enum": ["sync", "async", "return"],
              "default": "sync"
            }
          }
        }
      }
    },
    "group": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "label"],
      "properties": {
        "id": { "$ref": "#/$defs/id" },
        "label": { "$ref": "#/$defs/label" }
      }
    }
  },

  "allOf": [
    {
      "description": "ER diagrams: relationships should carry cardinality.",
      "if": { "properties": { "diagram": { "const": "er_diagram" } } },
      "then": {
        "properties": {
          "edges": {
            "items": {
              "properties": {
                "meta": { "required": ["cardinality"] }
              },
              "required": ["meta"]
            }
          }
        }
      }
    },
    {
      "description": "Timelines: every milestone node should carry a date.",
      "if": { "properties": { "diagram": { "const": "timeline" } } },
      "then": {
        "properties": {
          "nodes": {
            "items": {
              "properties": {
                "meta": { "required": ["date"] }
              },
              "required": ["meta"]
            }
          }
        }
      }
    },
    {
      "description": "Mobile wireframes: every node needs a UI kind.",
      "if": { "properties": { "diagram": { "const": "mobile_wireframe" } } },
      "then": {
        "properties": {
          "nodes": {
            "items": {
              "properties": {
                "meta": { "required": ["kind"] }
              },
              "required": ["meta"]
            }
          }
        }
      }
    }
  ]
}