GraphQL

Guides

Schema Conventions

Demand-oriented design, naming rules, nullability, abstract types (interfaces & unions), custom scalars, descriptions, and deprecation.

Queries & Mutations

Input types, pagination with Relay connections, mutation payloads with userErrors + warnings, domain-scoped error codes, optimistic concurrency, and relationship modeling.

Federation Patterns

Thinking in entities, entities vs. value types, entity keys, directives, cross-subgraph extension, query namespacing, schema governance, versioning, and entity ownership.

Quick Checklist

Use this when reviewing a schema change:

• Schema models client needs, not database shape (demand-oriented)
• Types PascalCase, fields camelCase, enum values SCREAMING_SNAKE_CASE
• Fields non-null by default; nullable only when legitimately optional
• Lists are [Type!]! (never null, never null items)
• Large collections use Relay connections
• Mutations take a single input argument and return a payload with userErrors + warnings
• Error codes are domain-scoped enums, not a single shared enum
• Multi-step resources use version: Int! for optimistic concurrency
• Timestamps use DateTime, URLs use URL, money uses Money
• Every type, field, and argument has a """description"""
• Removed fields go through @deprecated first
• Only types with identity and cross-subgraph usage are entities (@key)
• Value types (no identity) do not have @key
• Composition check passes in CI (rover supergraph compose)

References

• Apollo - Schema Design
• Apollo - Thinking in Entities
• Apollo - Moving from Monolith
• Apollo Federation Docs
• Relay Connection Spec
• GraphQL Best Practices