graphql

GraphQL Standards

Source: GraphQL Best Practices · Apollo Naming Conventions · GraphQL Schema Design

Priority: P0 — Schema Correctness

Nullability

The GraphQL spec makes every field nullable by default. A wrong ! is not just inaccurate — when a non-null field resolver returns null, GraphQL propagates the null upward through the response tree, wiping out the nearest nullable parent. One bad guarantee can null out an entire object from the client's response (graphql.org).

• Mark a field non-null (!) only when the server can guarantee it will never be null — not just "usually non-null".
• Mutation payload root fields (user, order) must be nullable — the mutation may fail and return errors instead of data.
• List elements and the list itself have separate nullability: [User!]! means a non-null list of non-null users.
• ID! is always non-null — if you have an ID, it exists.

Scalars & Custom Types

• Use built-in scalars: String, Int, Float, Boolean, ID.
• Add custom scalars for domain types: DateTime, Date, URL, EmailAddress, JSON.
• DON'T use String for dates, emails, or URLs — custom scalars carry semantic meaning, enable server-side validation, and surface intent in generated client types.

See refs/schema-design.md for custom scalar declaration examples.

Mutation Shape

Every mutation must take a single input argument typed as an Input object and return a Payload type — never a naked entity, never Boolean (Apollo).

See refs/schema-design.md for input/payload design rationale and full examples.

Global Object Identification

Implement the Node interface (graphql.org) for any type that clients need to refetch individually. The id field must be globally unique across all types — base64-encode the type and database ID (base64("User:123")), never expose raw database IDs. Without this, Apollo Client and Relay cannot correctly normalise their caches.