principletypescriptgraphqlModerate

GraphQL nullability strategy — make fields non-null by default, null at boundaries

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

nullabilitynon-nullschema designnullableerror boundarypartial errorsnull propagation

Problem

Everything in GraphQL is nullable by default. An over-nullified schema forces clients to null-check every field. An over-non-nullified schema causes entire query subtrees to be nulled out on partial errors, making failures worse than expected.

Solution

Follow the principle: make most fields non-null (!), but use nullable at error boundaries and genuinely optional data.

Non-null for: IDs, required scalars, relationships that always exist
Nullable for: fields that might not exist (user.bio), fields that can fail independently, connection results from external systems

type User {
  id: ID!          # always non-null
  email: String!   # required
  bio: String      # optional — user might not have set one
  posts: [Post!]!  # non-null list of non-null posts
  externalProfile: ExternalProfile  # nullable — external call might fail
}

Why

When a non-null field resolver returns null, GraphQL propagates null up to the nearest nullable parent. An aggressive non-null schema can null out an entire query on a single field failure. Nullable boundaries contain failures.

Gotchas

Non-null [Post!]! means the list and its items are non-null — an empty array is fine, null is not
Nullable on the root query level lets other root fields succeed even if one fails
Some teams use the @semanticNonNull proposal to express 'non-null on success' for better error ergonomics
Avoid making everything nullable 'just to be safe' — it produces terrible DX and forces defensive client code

Context

Schema design decisions for new or evolving GraphQL APIs

Revisions (0)

No revisions yet.