{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://platformcosmo.io/schema/v1.json",
  "title": "PlatformCosmoSpec",
  "description": "PlatformCosmo spec, format major version 1. Draft until v1.0.",
  "type": "object",
  "additionalProperties": false,
  "required": ["meta"],
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Schema URL that editors use for completion, normally https://platformcosmo.io/schema/v1.json."
    },
    "meta": {
      "type": "object",
      "additionalProperties": false,
      "required": ["version"],
      "properties": {
        "version": {
          "const": "1",
          "description": "Spec format major version, always the string \"1\"."
        },
        "title": {
          "$ref": "#/$defs/text",
          "description": "Short title of the spec, used as the SVG title element."
        },
        "description": {
          "type": "string",
          "maxLength": 2000,
          "pattern": "^[^\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F]*$",
          "description": "Longer description of the spec, used as the SVG desc element."
        }
      },
      "description": "Spec metadata: format version, title and description."
    },
    "canvas": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "theme": {
          "enum": ["light", "dark", "blueprint", "mono"],
          "description": "Color theme for the diagram: light, dark, blueprint or mono.",
          "default": "light"
        },
        "grid": {
          "type": "boolean",
          "description": "Whether to draw the iso ground grid behind the diagram (on by default; set false for a plain background).",
          "default": true
        },
        "padding": {
          "type": "integer",
          "minimum": 0,
          "maximum": 1000,
          "description": "Empty space around the diagram in pixels, from 0 to 1000.",
          "default": 32
        },
        "aspect": {
          "type": "string",
          "pattern": "^(auto|[1-9][0-9]*:[1-9][0-9]*)$",
          "description": "Output aspect ratio: \"auto\" or \"width:height\" such as 16:9.",
          "default": "auto"
        }
      },
      "description": "Canvas appearance: theme, background grid, padding and aspect ratio."
    },
    "nodes": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/node"
      },
      "minItems": 1,
      "maxItems": 500,
      "description": "Components to draw, each with a semantic type and an optional icon."
    },
    "groups": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/group"
      },
      "maxItems": 200,
      "description": "Zones, VPCs, clusters or platforms that group nodes, optionally nested."
    },
    "edges": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/edge"
      },
      "maxItems": 1000,
      "description": "Connections between objects (nodes, racks, equipment, or rackId/slotId)."
    },
    "flows": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/flow"
      },
      "maxItems": 200,
      "description": "Animated flows of traffic or power along an edge, a cable or a pair of endpoints."
    },
    "metrics": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/metric"
      },
      "maxItems": 50,
      "description": "Headline metric tiles shown with the diagram."
    },
    "steps": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/step"
      },
      "maxItems": 99,
      "description": "Animation steps, each with a caption, state changes, flows, metrics and a focus target."
    },
    "legend": {
      "oneOf": [
        {
          "const": "auto"
        },
        {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["label"],
            "properties": {
              "label": {
                "$ref": "#/$defs/text",
                "description": "Text shown for the legend entry."
              },
              "color": {
                "$ref": "#/$defs/color",
                "description": "#rgb or #rrggbb hex, a palette name (blue, green, red, orange, yellow, purple, teal, pink, gray) or a flow kind name."
              }
            }
          },
          "maxItems": 50
        }
      ],
      "description": "Legend mode: \"auto\" to derive entries from the diagram, or a manual list of label and color pairs."
    },
    "racks": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/rack"
      },
      "minItems": 1,
      "maxItems": 500,
      "description": "Equipment racks, each with a height in rack units and optional slots."
    },
    "equipment": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/equipment"
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "Data-center equipment items (UPS, CRAH, CDU and similar) placed on the floor."
    },
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/row"
      },
      "maxItems": 100,
      "description": "Ordered rows of racks or equipment on the floor, with a facing direction."
    },
    "aisles": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/aisle"
      },
      "maxItems": 100,
      "description": "Cold or hot aisles, each grouping rows of racks."
    },
    "cables": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/cable"
      },
      "maxItems": 2000,
      "description": "DC cables (power, network, fiber or management) between racks, slots and equipment."
    },
    "facility": {
      "$ref": "#/$defs/facility",
      "description": "Facility-wide settings: raised floor, perforated tiles and cable trays."
    }
  },
  "$defs": {
    "id": {
      "title": "SpecId",
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "maxLength": 64
    },
    "color": {
      "title": "SpecColor",
      "type": "string",
      "pattern": "^(#[0-9a-fA-F]{3}|#[0-9a-fA-F]{6}|blue|green|red|orange|yellow|purple|teal|pink|gray|normal|heavy|health|failed|airflow|power)$",
      "description": "#rgb or #rrggbb hex, a palette name (blue, green, red, orange, yellow, purple, teal, pink, gray) or a flow kind name. Flow kind names: normal, heavy, health, failed, airflow, power."
    },
    "state": {
      "title": "SpecState",
      "enum": ["healthy", "degraded", "down", "highlighted"]
    },
    "nodeType": {
      "title": "SpecNodeType",
      "enum": [
        "server",
        "vm",
        "container",
        "pod",
        "function",
        "lb",
        "gateway",
        "cdn",
        "dns",
        "firewall",
        "vpc",
        "sql",
        "nosql",
        "cache",
        "object-store",
        "warehouse",
        "queue",
        "stream",
        "users",
        "client",
        "mobile",
        "metrics",
        "logs",
        "traces",
        "repo",
        "pipeline",
        "registry",
        "iam",
        "secrets",
        "waf",
        "llm",
        "embedding",
        "vector-db",
        "gpu",
        "inference-server",
        "agent",
        "tool",
        "rag",
        "guardrail",
        "feature-store",
        "training-job"
      ]
    },
    "node": {
      "title": "SpecNode",
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "type"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id",
          "description": "Unique identifier of the node, used by edges, flows and steps."
        },
        "type": {
          "$ref": "#/$defs/nodeType",
          "description": "Semantic component type, such as lb, sql or queue."
        },
        "icon": {
          "type": "string",
          "pattern": "^[a-z0-9-]+:[a-z0-9-]+$",
          "description": "Icon name to draw, such as aws:rds, which must be installed."
        },
        "label": {
          "$ref": "#/$defs/text",
          "description": "Text label shown for the node."
        },
        "badge": {
          "$ref": "#/$defs/text",
          "description": "Short badge text shown on the node."
        },
        "size": {
          "enum": ["sm", "md", "lg"],
          "description": "Node size: sm, md or lg.",
          "default": "md"
        },
        "pos": {
          "$ref": "#/$defs/gridPos",
          "description": "Optional manual grid position that overrides automatic layout."
        },
        "group": {
          "$ref": "#/$defs/id",
          "description": "Id of the group that contains the node."
        },
        "state": {
          "$ref": "#/$defs/state",
          "description": "Initial operational state of the node: healthy, degraded, down or highlighted.",
          "default": "healthy"
        }
      }
    },
    "group": {
      "title": "SpecGroup",
      "type": "object",
      "additionalProperties": false,
      "required": ["id"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id",
          "description": "Unique identifier of the group."
        },
        "label": {
          "$ref": "#/$defs/text",
          "description": "Text label shown for the group."
        },
        "style": {
          "enum": ["zone", "vpc", "cluster", "platform"],
          "description": "Visual style of the group: zone, vpc, cluster or platform.",
          "default": "zone"
        },
        "parent": {
          "$ref": "#/$defs/id",
          "description": "Id of the enclosing group, used for nesting."
        }
      }
    },
    "edge": {
      "title": "SpecEdge",
      "type": "object",
      "additionalProperties": false,
      "required": ["from", "to"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id",
          "description": "Optional unique identifier of the edge, used to reference it from flows."
        },
        "from": {
          "$ref": "#/$defs/endpoint",
          "description": "Source endpoint of the edge, as an object id or a rackId/slotId pair."
        },
        "to": {
          "$ref": "#/$defs/endpoint",
          "description": "Destination endpoint of the edge, as an object id or a rackId/slotId pair."
        },
        "label": {
          "$ref": "#/$defs/text",
          "description": "Text label shown on the edge."
        },
        "style": {
          "enum": ["solid", "dashed", "dotted"],
          "description": "Line style of the edge: solid, dashed or dotted.",
          "default": "solid"
        },
        "bidirectional": {
          "type": "boolean",
          "description": "Whether the edge is drawn as two-way rather than one-way.",
          "default": false
        }
      }
    },
    "flow": {
      "title": "SpecFlow",
      "oneOf": [
        {
          "title": "SpecFlowByEdge",
          "type": "object",
          "additionalProperties": false,
          "required": ["edge"],
          "properties": {
            "edge": {
              "$ref": "#/$defs/id",
              "description": "Id of the edge or cable that the flow travels along."
            },
            "kind": {
              "$ref": "#/$defs/flowKind",
              "description": "Flow kind that sets the default look: normal, heavy, health, failed, airflow or power.",
              "default": "normal"
            },
            "rate": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 20,
              "description": "Particles emitted per second (0 < rate <= 20). Each flow costs ceil(rate x 2) particles; the total over base and all step flows must be <= 2000.",
              "default": 1
            },
            "color": {
              "$ref": "#/$defs/color",
              "description": "#rgb or #rrggbb hex, a palette name (blue, green, red, orange, yellow, purple, teal, pink, gray) or a flow kind name."
            }
          }
        },
        {
          "title": "SpecFlowByEndpoints",
          "type": "object",
          "additionalProperties": false,
          "required": ["from", "to"],
          "properties": {
            "from": {
              "$ref": "#/$defs/endpoint",
              "description": "Source endpoint of the flow, as an object id or a rackId/slotId pair."
            },
            "to": {
              "$ref": "#/$defs/endpoint",
              "description": "Destination endpoint of the flow, as an object id or a rackId/slotId pair."
            },
            "kind": {
              "$ref": "#/$defs/flowKind",
              "description": "Flow kind that sets the default look: normal, heavy, health, failed, airflow or power.",
              "default": "normal"
            },
            "rate": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 20,
              "description": "Particles emitted per second (0 < rate <= 20). Each flow costs ceil(rate x 2) particles; the total over base and all step flows must be <= 2000.",
              "default": 1
            },
            "color": {
              "$ref": "#/$defs/color",
              "description": "#rgb or #rrggbb hex, a palette name (blue, green, red, orange, yellow, purple, teal, pink, gray) or a flow kind name."
            }
          }
        }
      ]
    },
    "metric": {
      "title": "SpecMetric",
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "label", "value"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id",
          "description": "Unique identifier of the metric tile."
        },
        "label": {
          "$ref": "#/$defs/text",
          "description": "Text label shown on the metric tile."
        },
        "value": {
          "$ref": "#/$defs/metricValue",
          "description": "Value shown on the metric tile, as text or a number."
        }
      }
    },
    "step": {
      "title": "SpecStep",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "caption": {
          "$ref": "#/$defs/text",
          "description": "Text caption shown while the step plays."
        },
        "set": {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/endpoint"
          },
          "additionalProperties": {
            "$ref": "#/$defs/state"
          },
          "maxProperties": 1000,
          "description": "State changes from this step onward (cumulative), keyed by object id or rackId/slotId."
        },
        "flows": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/flow"
          },
          "maxItems": 200,
          "description": "If present (even []), replaces the base flows for this step only; omit to keep the base flows."
        },
        "metrics": {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/id"
          },
          "additionalProperties": {
            "$ref": "#/$defs/metricValue"
          },
          "maxProperties": 50,
          "description": "Metric values from this step onward (cumulative), keyed by metric id."
        },
        "duration": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 600,
          "description": "Step length in seconds at speed 1 (> 0, <= 600).",
          "default": 3
        },
        "focus": {
          "$ref": "#/$defs/endpoint",
          "description": "Id to zoom to for this step only (object, rackId/slotId, group, row, aisle); omit for the full view."
        }
      },
      "minProperties": 1
    },
    "flowKind": {
      "title": "SpecFlowKind",
      "enum": ["normal", "heavy", "health", "failed", "airflow", "power"]
    },
    "dcSlotType": {
      "title": "SpecDcSlotType",
      "enum": [
        "server-1u",
        "server-2u",
        "server-4u",
        "blade-chassis",
        "gpu-node",
        "switch-tor",
        "switch-leaf",
        "switch-spine",
        "patch-panel",
        "storage-shelf",
        "storage-flash",
        "storage-jbod",
        "pdu-1u",
        "ups-2u",
        "blank"
      ]
    },
    "dcEquipmentType": {
      "title": "SpecDcEquipmentType",
      "enum": ["ups", "busway", "pdu-floor", "crah", "in-row-cooler", "cdu", "tape-library"]
    },
    "rack": {
      "title": "SpecRack",
      "type": "object",
      "additionalProperties": false,
      "required": ["id"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id",
          "description": "Unique identifier of the rack."
        },
        "label": {
          "$ref": "#/$defs/text",
          "description": "Text label shown for the rack."
        },
        "u": {
          "enum": [42, 45, 48],
          "description": "Rack height in rack units: 42, 45 or 48.",
          "default": 42
        },
        "pos": {
          "$ref": "#/$defs/gridPos",
          "description": "Optional manual grid position that overrides automatic placement."
        },
        "state": {
          "$ref": "#/$defs/state",
          "description": "Operational state of the rack.",
          "default": "healthy"
        },
        "pdu": {
          "enum": ["none", "single", "dual"],
          "description": "PDU redundancy for the rack: none, single or dual.",
          "default": "dual"
        },
        "rearDoorHeatExchanger": {
          "type": "boolean",
          "description": "Whether the rack has a rear-door heat exchanger.",
          "default": false
        },
        "slots": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/rackSlot"
          },
          "maxItems": 48,
          "description": "Devices placed in the rack's rack units."
        }
      }
    },
    "rackSlot": {
      "title": "SpecRackSlot",
      "type": "object",
      "additionalProperties": false,
      "required": ["at", "type"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id",
          "description": "Defaults to u<at>."
        },
        "at": {
          "type": "integer",
          "minimum": 1,
          "maximum": 48,
          "description": "Lowest rack unit the device occupies (1 = bottom)."
        },
        "size": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10,
          "description": "Rack units; defaults to the device type height."
        },
        "type": {
          "$ref": "#/$defs/dcSlotType",
          "description": "Device type placed in the slot, such as server-1u or switch-tor."
        },
        "label": {
          "$ref": "#/$defs/text",
          "description": "Text label shown for the device in the slot."
        },
        "state": {
          "$ref": "#/$defs/state",
          "description": "Device state. Omit to inherit the rack state."
        }
      }
    },
    "equipment": {
      "title": "SpecEquipment",
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "type"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id",
          "description": "Unique identifier of the equipment item."
        },
        "type": {
          "$ref": "#/$defs/dcEquipmentType",
          "description": "Kind of data-center equipment, such as ups, crah or cdu."
        },
        "label": {
          "$ref": "#/$defs/text",
          "description": "Text label shown for the equipment item."
        },
        "pos": {
          "$ref": "#/$defs/gridPos",
          "description": "Optional manual grid position that overrides automatic placement."
        },
        "state": {
          "$ref": "#/$defs/state",
          "description": "Operational state of the equipment item.",
          "default": "healthy"
        }
      }
    },
    "row": {
      "title": "SpecRow",
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "members"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id",
          "description": "Unique identifier of the row."
        },
        "label": {
          "$ref": "#/$defs/text",
          "description": "Text label shown for the row."
        },
        "members": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/id"
          },
          "minItems": 1,
          "maxItems": 100,
          "description": "Ids of the racks or equipment items in the row, in order."
        },
        "facing": {
          "enum": ["front", "back"],
          "description": "Which side of the rack faces the row front. Omit to derive it from the aisles: rows face their cold aisle and turn their backs to their hot aisle."
        }
      }
    },
    "aisle": {
      "title": "SpecAisle",
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "kind", "rows"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id",
          "description": "Unique identifier of the aisle."
        },
        "label": {
          "$ref": "#/$defs/text",
          "description": "Text label shown for the aisle."
        },
        "kind": {
          "enum": ["cold", "hot"],
          "description": "Whether the aisle is a cold aisle or a hot aisle."
        },
        "rows": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/id"
          },
          "minItems": 1,
          "maxItems": 2,
          "description": "The one or two rows bounding the aisle."
        },
        "contained": {
          "type": "boolean",
          "description": "Whether the aisle is enclosed by doors or containment.",
          "default": false
        }
      }
    },
    "cable": {
      "title": "SpecCable",
      "type": "object",
      "additionalProperties": false,
      "required": ["from", "to"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id",
          "description": "Unique identifier of the cable."
        },
        "from": {
          "$ref": "#/$defs/endpoint",
          "description": "Source endpoint of the cable, as an object id or a rackId/slotId pair."
        },
        "to": {
          "$ref": "#/$defs/endpoint",
          "description": "Destination endpoint of the cable, as an object id or a rackId/slotId pair."
        },
        "kind": {
          "enum": ["power", "network", "fiber", "management"],
          "description": "Cable type: power, network, fiber or management.",
          "default": "network"
        },
        "label": {
          "$ref": "#/$defs/text",
          "description": "Text label shown on the cable."
        }
      }
    },
    "endpoint": {
      "title": "SpecEndpoint",
      "description": "An object id, or rackId/slotId for a device in a rack slot.",
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*(/[a-z][a-z0-9-]*)?$",
      "maxLength": 129
    },
    "facility": {
      "title": "SpecFacility",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "raisedFloor": {
          "type": "boolean",
          "description": "Whether the room has a raised floor.",
          "default": true
        },
        "perforatedTiles": {
          "type": "boolean",
          "description": "Whether the raised floor uses perforated airflow tiles.",
          "default": true
        },
        "cableTrays": {
          "enum": ["none", "overhead", "underfloor"],
          "description": "Where cable trays run: none, overhead or underfloor.",
          "default": "overhead"
        }
      }
    },
    "text": {
      "title": "SpecText",
      "type": "string",
      "maxLength": 200,
      "pattern": "^[^\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F]*$"
    },
    "gridPos": {
      "title": "SpecGridPos",
      "description": "Manual grid position override (tiles).",
      "type": "object",
      "additionalProperties": false,
      "required": ["x", "y"],
      "properties": {
        "x": {
          "type": "integer",
          "minimum": -1000,
          "maximum": 1000,
          "description": "Horizontal grid tile coordinate, from -1000 to 1000."
        },
        "y": {
          "type": "integer",
          "minimum": -1000,
          "maximum": 1000,
          "description": "Vertical grid tile coordinate, from -1000 to 1000."
        }
      }
    },
    "metricValue": {
      "title": "SpecMetricValue",
      "oneOf": [
        {
          "type": "string",
          "maxLength": 64,
          "pattern": "^[^\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F]*$"
        },
        {
          "type": "number"
        }
      ]
    }
  },
  "x-revision": "1.1.3",
  "anyOf": [
    {
      "required": ["nodes"],
      "properties": {
        "nodes": true
      }
    },
    {
      "required": ["racks"],
      "properties": {
        "racks": true
      }
    },
    {
      "required": ["equipment"],
      "properties": {
        "equipment": true
      }
    }
  ]
}
