graphql-schema

# GraphQL Schema (Deep Workflow) GraphQL concentrates complexity on the server: **resolver graphs**, **N+1** fetches, **schema evolution**, and **field-level authorization**. ## When to Offer This Workflow **Trigger conditions:** - Designing a new GraphQL API or federated subgraph - Latency or complexity incidents from client queries - Need for safe schema deprecation and versioning **Initial offer:** Use **six stages**: (1) domain modeling, (2) operations surface, (3) performance patterns, (4) errors & partial results, (5) security & authz, (6) versioning & evolution). Confirm client patterns (Apollo, Relay) and gateway (if any). --- ## Stage 1: Domain Modeling **Goal:** Types reflect domain concepts; avoid dumping everything on `Query`; use input objects for mutations with validation. --- ## Stage 2: Operations Surface **Goal:** Queries for reads; mutations for writes; subscriptions only when justified (scaling and operational cost). ### Pagination - Prefer cursor-based connections for large lists (Relay-style edges/nodes) --- ## Stage 3: Performance Patterns **Goal:** DataLoader or batching for N+1; query complexity/depth/cost limits; optional persisted queries for public APIs. --- ## Stage 4: Errors & Partial Results **Goal:** Document semantics of `errors` alongside partial `data`; map domain failures to structured extensions. --- ## Stage 5: Security & Authz **Goal:** Enforce authorization at field/object level—not only at the top resolver. --- ## Stage 6: Versioning & Evolution **Goal:** Prefer additive changes; `@deprecated` with migration window; in federation, clear ownership of types and entities. --- ## Final Review Checklist - [ ] Schema reflects domain and operations - [ ] Pagination and mutations idiomatic - [ ] Batching and complexity limits in place - [ ] Error behavior documented for clients - [ ] Field-level authz enforced - [ ] Deprecation policy defined ## Tips for Effective Guidance - N+1 is the default failure mode—plan batching early. - Pair with **rest-best-practices** when REST and GraphQL coexist at the edge. ## Handling Deviations - Public APIs: consider persisted queries or allowlists to limit abusive queries.