Lists and Non-Null Types

GraphQL type modifiers let you express collection and nullability constraints.

The [] syntax represents a list and ! represents Non-Null.

Consider these types:

users: [User]
users: [User]!
users: [User!]
users: [User!]!

They are not equivalent.

`[User]`

The list may be null, and individual elements may also be null.

`[User]!`

The list itself cannot be null, but individual elements may be null.

`[User!]`

The list may be null, but every element that exists must be a User rather than null.

`[User!]!`

Neither the list nor its elements can be null.

This distinction is important when designing reliable APIs. Nullability is part of the schema contract and affects validation, execution, generated types, and client behavior.

For example:

type Query {
  users: [User!]!
}

communicates that a successful resolver result should always be a list and that every element should be a valid non-null User.

Non-null does not mean that the underlying database can never contain missing data. It means the GraphQL field contract promises that a null value cannot be returned at that location during successful execution. If a resolver violates a non-null contract, GraphQL can propagate null upward according to its execution rules and report an error.

Nullability Comparison

[User]: Nullable list, nullable elements

Both the list and its individual elements may be null.

[User]!: Non-null list, nullable elements

The list must exist, but an element can be null.

[User!]: Nullable list, non-null elements

The list can be null, but an existing element cannot be null.

[User!]!: Non-null list, non-null elements

Neither the list nor any element may be null.

Understanding GraphQL List Nullability

Key Takeaways

Square brackets represent lists.
The exclamation mark represents Non-Null.
List nullability and element nullability are independent.
Nullability is an important part of API design.

Knowledge Check

What does `[User!]!` mean?