7c39058386
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Export Center CI / export-ci (push) Has been cancelled
Symbols Server CI / symbols-smoke (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
33 lines
1.6 KiB
Markdown
33 lines
1.6 KiB
Markdown
# Graph API schema review notes (planned)
|
|
Date: 2025-11-24 (target)
|
|
Scope: Review OpenAPI/JSON schema for search/query/paths/diff/export, tiles, budgets, and overlays alignment (GRAPH-API-28-001).
|
|
|
|
## Attendees
|
|
- Graph API Guild: TBD
|
|
- Policy Engine Guild: TBD
|
|
- QA Guild (observer): TBD
|
|
|
|
## Pre-reads
|
|
- `docs/api/graph-gateway-spec-draft.yaml`
|
|
- `docs/modules/graph/prep/2025-11-22-graph-api-schema-outline.md`
|
|
- Policy overlay contract references: `POLICY-ENGINE-30-001..003`
|
|
|
|
## Agenda
|
|
- Validate tile envelope shape and budget semantics.
|
|
- Confirm overlay payload fields and versioning handshake with Policy Engine.
|
|
- Decide DSL vs structured filter scope for `/graph/query` v1.
|
|
- Agree on export manifest shape and size caps for PNG/SVG.
|
|
|
|
## Decisions
|
|
- Tile envelope shape frozen for draft v0.0.3-pre: `node|edge|stats|cursor|diagnostic`, `seq`, optional `cost`, overlays keyed by overlay kind with `{kind, version, data}`.
|
|
- Resume support will rely on cursor tokens; requests accept optional `cursor` field for search/query/diff to resume streams.
|
|
- Path responses carry `pathHop` on node/edge tiles; depth capped at 6 as per sprint scope.
|
|
- Rate-limit/budget headers documented (`X-RateLimit-Remaining`, `Retry-After`), with 429 response carrying error envelope.
|
|
|
|
## Open items / follow-ups
|
|
- Overlay payload contract (fields for policy/vex/advisory) to be versioned once POLICY-ENGINE-30-001..003 freeze; placeholder schema retained.
|
|
- Export render limits (PNG/SVG size caps) still pending Observability/UX sign-off.
|
|
|
|
## Outcomes snapshot
|
|
- Draft spec updated at `docs/api/graph-gateway-spec-draft.yaml` (v0.0.3-pre) and referenced in sprint Execution Log.
|