docs consolidation
This commit is contained in:
StellaOps Bot
@@ -1,42 +1,82 @@
|
||||
# Graph Overlay & Cache Schema (draft placeholder)
|
||||
# Graph overlay and tile cache schema (draft)
|
||||
|
||||
**Status:** Draft v0.2 · owner-proposed
|
||||
## Overview
|
||||
|
||||
## Scope
|
||||
- Overlay/cache schema for graph tiles used by Web gateway and UI overlays.
|
||||
- Validation rules for bbox/zoom/path; pagination tokens; deterministic ordering.
|
||||
- Error codes and sampling/telemetry fields.
|
||||
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": "2025-12-06",
|
||||
"version": "0.2",
|
||||
"tenantId": "tenant-default",
|
||||
"tile": {
|
||||
"id": "graph-tile::asset::<hash>::z8/x12/y5",
|
||||
"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": "", "severity": "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 } ],
|
||||
"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": "", "verdictAt": "2025-12-05T09:00:00Z" } ],
|
||||
"vex": [ { "nodeId": "nodeId", "state": "not_affected|fixed|under_investigation|affected", "statementId": "", "lastUpdated": "2025-12-05T09:10:00Z" } ],
|
||||
"aoc": [ { "nodeId": "nodeId", "status": "pass|fail|warn", "lastVerified": "2025-12-05T10:11:12Z" } ]
|
||||
"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 }
|
||||
}
|
||||
```
|
||||
|
||||
## Constraints (proposal)
|
||||
- Max nodes per tile: 2,000; max edges: 4,000.
|
||||
- Zoom range: 0–12; tiles must include bbox and etag.
|
||||
- Arrays must be pre-sorted: nodes by `id`, edges by `id`, overlays by `nodeId` then `policyId|statementId`.
|
||||
## Determinism rules
|
||||
|
||||
## Samples
|
||||
- `docs/api/graph/samples/overlay-sample.json`
|
||||
- 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.
|
||||
|
||||
## Outstanding
|
||||
- Confirm max sizes, allowed edge types, and etag hashing rule.
|
||||
- Provide validation error example and rate-limit headers for gateway responses.
|
||||
## Constraints (draft)
|
||||
|
||||
- Max nodes per tile: 2,000
|
||||
- Max edges per tile: 4,000
|
||||
- Zoom range: 0-12
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"version": "2025-12-06",
|
||||
"version": "0.2",
|
||||
"tenantId": "tenant-default",
|
||||
"tile": {
|
||||
"id": "graph-tile::asset::sha256:abc123::z8/x12/y5",
|
||||
@@ -19,7 +19,6 @@
|
||||
"label": "app:1.2.3",
|
||||
"severity": "high",
|
||||
"reachability": "reachable",
|
||||
"aoc": { "summary": "pass", "lastVerified": "2025-12-05T10:11:12Z" },
|
||||
"attributes": {
|
||||
"purl": "pkg:docker/app@sha256:abc123",
|
||||
"componentCount": 42
|
||||
@@ -48,22 +47,22 @@
|
||||
"nodeId": "component:pkg:npm/jsonwebtoken@9.0.2",
|
||||
"badge": "fail",
|
||||
"policyId": "policy://tenant-default/runtime-hardening",
|
||||
"verdictAt": "2025-12-05T09:00:00Z"
|
||||
"verdictAt": "2025-01-02T03:04:05Z"
|
||||
}
|
||||
],
|
||||
"vex": [
|
||||
{
|
||||
"nodeId": "component:pkg:npm/jsonwebtoken@9.0.2",
|
||||
"state": "under_investigation",
|
||||
"statementId": "vex:tenant-default:jwt:2025-12-05",
|
||||
"lastUpdated": "2025-12-05T09:10:00Z"
|
||||
"statementId": "vex:tenant-default:jwt:0001",
|
||||
"lastUpdated": "2025-01-02T03:04:05Z"
|
||||
}
|
||||
],
|
||||
"aoc": [
|
||||
{
|
||||
"nodeId": "asset:registry.local/library/app@sha256:abc123",
|
||||
"status": "pass",
|
||||
"lastVerified": "2025-12-05T10:11:12Z"
|
||||
"lastVerified": "2025-01-02T03:04:05Z"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user