{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/flancast90/chorograph/main/spec/graph.schema.json",
  "title": "Graph",
  "description": "The complete, serialisable chorograph map. This is the on-disk graph.json contract; every chorograph implementation, in any language, emits and consumes documents valid under this schema.",
  "$defs": {
    "NodeKind": {
      "title": "NodeKind",
      "description": "What a node is. A small closed set, one icon and one colour each. Per-kind semantics and the containment rules live in grammar.json.",
      "type": "string",
      "enum": [
        "domain",
        "service",
        "module",
        "endpoint",
        "function",
        "job",
        "database",
        "table",
        "cache",
        "bucket",
        "queue",
        "event",
        "external"
      ]
    },
    "EdgeKind": {
      "title": "EdgeKind",
      "description": "How two nodes are connected. `from` is the thing doing the verb, `to` is the thing the verb is done to.",
      "type": "string",
      "enum": [
        "calls",
        "reads",
        "writes",
        "emits",
        "consumes",
        "uses"
      ]
    },
    "Node": {
      "title": "Node",
      "description": "A single thing on the map.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "name",
        "kind",
        "parent",
        "tags"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable slug path derived from names: `commerce/orders/post-orders`."
        },
        "name": {
          "type": "string"
        },
        "kind": {
          "$ref": "#/$defs/NodeKind"
        },
        "parent": {
          "type": [
            "string",
            "null"
          ],
          "description": "Containment parent id, or null for a top-level node."
        },
        "description": {
          "type": "string",
          "description": "One or two sentences on what this thing is for. Shown in the detail panel."
        },
        "tech": {
          "type": "string",
          "description": "Implementation note: `PostgreSQL 16`, `Node.js`, `Kafka`."
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "file": {
          "type": "string",
          "description": "Where the declaring comment lives, relative to where chorograph ran."
        },
        "line": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "Edge": {
      "title": "Edge",
      "description": "A directed connection between two nodes.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "from",
        "to",
        "kind"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "from": {
          "type": "string"
        },
        "to": {
          "type": "string"
        },
        "kind": {
          "$ref": "#/$defs/EdgeKind"
        },
        "label": {
          "type": "string",
          "description": "Optional annotation: protocol (`HTTP`, `gRPC`) or a short verb phrase — the why."
        }
      }
    },
    "GraphCounts": {
      "title": "GraphCounts",
      "description": "How many of each kind the graph holds; a cheap summary for tooling.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "nodes",
        "edges"
      ],
      "properties": {
        "nodes": {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/NodeKind"
          },
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          },
          "tsType": "Readonly<Partial<Record<NodeKind, number>>>"
        },
        "edges": {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/EdgeKind"
          },
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          },
          "tsType": "Readonly<Partial<Record<EdgeKind, number>>>"
        }
      }
    },
    "GraphMeta": {
      "title": "GraphMeta",
      "description": "Provenance and summary for a generated graph.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "tool",
        "version",
        "generatedAt",
        "name",
        "counts"
      ],
      "properties": {
        "tool": {
          "const": "chorograph"
        },
        "version": {
          "type": "string",
          "description": "Version of the generator that produced the file."
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp."
        },
        "name": {
          "type": "string",
          "description": "The system name from the `@system` comment."
        },
        "description": {
          "type": "string"
        },
        "counts": {
          "$ref": "#/$defs/GraphCounts"
        }
      }
    }
  },
  "type": "object",
  "additionalProperties": false,
  "required": [
    "meta",
    "nodes",
    "edges"
  ],
  "properties": {
    "meta": {
      "$ref": "#/$defs/GraphMeta"
    },
    "nodes": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Node"
      }
    },
    "edges": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Edge"
      }
    }
  }
}