83 lines
2.4 KiB
Markdown
83 lines
2.4 KiB
Markdown
# Graph overlay and tile cache schema (draft)
|
|
|
|
## Overview
|
|
|
|
This document describes the cached/materialized tile representation used by gateway/UI components to store graph tiles alongside overlay data.
|
|
|
|
This cache schema is separate from the streaming NDJSON tile protocol:
|
|
- Streaming API contract: `docs/api/graph-gateway-spec-draft.yaml`
|
|
- Sample cached tile: `docs/api/graph/samples/overlay-sample.json`
|
|
|
|
## Cached tile shape
|
|
|
|
A cached tile document is a single JSON object with:
|
|
- `version`: cache schema version (string; bump only for breaking changes)
|
|
- `tenantId`: tenant partition for the cache entry
|
|
- `tile`: tile identity + spatial key (`id`, `bbox`, `zoom`) and cache validator (`etag`)
|
|
- `nodes`: node records
|
|
- `edges`: edge records
|
|
- `overlays`: overlay arrays keyed by overlay kind
|
|
- `telemetry`: generation/caching metadata
|
|
|
|
## Schema (draft)
|
|
|
|
```jsonc
|
|
{
|
|
"version": "0.2",
|
|
"tenantId": "tenant-default",
|
|
"tile": {
|
|
"id": "graph-tile::<scope>::<hash>::z8/x12/y5",
|
|
"bbox": { "minX": -122.41, "minY": 37.77, "maxX": -122.38, "maxY": 37.79 },
|
|
"zoom": 8,
|
|
"etag": "c0ffee-etag"
|
|
},
|
|
"nodes": [
|
|
{
|
|
"id": "asset:...",
|
|
"kind": "asset|component|vuln",
|
|
"label": "optional display label",
|
|
"severity": "critical|high|medium|low|info",
|
|
"reachability": "reachable|unreachable|unknown",
|
|
"attributes": {}
|
|
}
|
|
],
|
|
"edges": [
|
|
{
|
|
"id": "edge-1",
|
|
"source": "nodeId",
|
|
"target": "nodeId",
|
|
"type": "depends_on|contains|evidence",
|
|
"weight": 0.0,
|
|
"attributes": {}
|
|
}
|
|
],
|
|
"overlays": {
|
|
"policy": [
|
|
{ "nodeId": "nodeId", "badge": "pass|warn|fail|waived", "policyId": "policy://...", "verdictAt": "2025-01-02T03:04:05Z" }
|
|
],
|
|
"vex": [
|
|
{ "nodeId": "nodeId", "state": "not_affected|fixed|under_investigation|affected", "statementId": "vex:...", "lastUpdated": "2025-01-02T03:04:05Z" }
|
|
],
|
|
"aoc": [
|
|
{ "nodeId": "nodeId", "status": "pass|fail|warn", "lastVerified": "2025-01-02T03:04:05Z" }
|
|
]
|
|
},
|
|
"telemetry": { "generationMs": 0, "cache": "hit|miss", "samples": 0 }
|
|
}
|
|
```
|
|
|
|
## Determinism rules
|
|
|
|
- Arrays are pre-sorted:
|
|
- `nodes` by `id`
|
|
- `edges` by `id`
|
|
- overlay arrays by `nodeId` then secondary key (`policyId`, `statementId`, etc.)
|
|
- Timestamps are ISO-8601 UTC.
|
|
- Hashes are lower-case hex.
|
|
|
|
## Constraints (draft)
|
|
|
|
- Max nodes per tile: 2,000
|
|
- Max edges per tile: 4,000
|
|
- Zoom range: 0-12
|