Designing Nullability Carefully

Nullability is one of the most consequential GraphQL schema design decisions.

Consider:

type User {
  id: ID!
  name: String!
  nickname: String
}

This says that id and name are required in a successful User value, while nickname may be null.

Do not make everything non-null simply because non-null feels safer. If a value can legitimately be absent, forcing it to be non-null can create execution failures or make future evolution harder.

At the same time, making everything nullable weakens the contract and forces clients to handle unnecessary null cases.

Ask these questions when choosing nullability:

  1. Is the value guaranteed by the domain?
  2. Can the value legitimately be absent?
  3. Can the resolver fail to produce the value?
  4. What should happen if the underlying data source is unavailable?
  5. How will null propagation affect parent fields?

For lists, separately consider list nullability and element nullability.

products: [Product!]!

This is a strong contract: the list exists and contains only valid products.

Schema evolution also matters. Changing a nullable field to non-null can break clients if the server previously returned null. Therefore, nullability changes should be treated as API contract changes.

Nullability is an API contract

Changing a field from nullable to non-null can affect execution behavior and existing clients. Treat nullability changes as compatibility-sensitive schema changes.

Key Takeaways
  • Do not make every field non-null automatically.
  • Do not make every field nullable without reason.
  • Consider domain guarantees and failure behavior.
  • Nullability changes can affect backward compatibility.
Knowledge Check

Why can changing an existing GraphQL field from nullable to non-null be risky?