# 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.