Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 37 ยท The Schema

Lists and Non-Null Types

Understand ! and [ ] in GraphQL: the four list/non-null combinations, what null means, and how an error bubbles up to the nearest nullable field.

Every field in a GraphQL schema has a type, and two small symbols change what that type promises: ! ("never null") and [ ] ("a list of"). They look trivial, but they decide what your clients can rely on, how errors spread through a response, and how painful your API is to evolve. Most real-world GraphQL bugs around "why is my whole response null?" come from this one topic.

This lesson builds on SDL: Types and Scalars. The schema snippets are read-only; the runnable examples are stand-ins: a small hand-written executor that applies the null rules to plain JavaScript data. A real server does the same in its execution engine (How Execution Works and How Errors Behave goes deeper).

Nullable by default

In SDL, every type is nullable unless you add !. This is the opposite of many languages.

GRAPHQL
type User {
  id: ID!          # never null
  name: String!    # never null
  bio: String      # may be null
}

bio: String means the field can legitimately return null, either because there is no bio or because something went wrong while loading it. name: String! is a promise: the server will never send null there. If it cannot keep the promise, the error does not stay local (see below).

Lists and the four combinations

[Int] is a list of integers. A list has two places where null could appear: the list itself and each item. The ! can be placed on either, which gives four combinations.

Four list types

[Int] List may be null. Items may be null.
[Int!] List may be null. Items never null.
[Int]! List never null. Items may be null.
[Int!]! Neither list nor items are null.

The inner ! belongs to the items.

1 / 2

An empty list [] is valid for all four. "No results" should be an empty list, not null. For that reason [Item!]! is the most common choice for fields that return many things: clients can loop without a null check.

What null means

A field can be null for different reasons: the value is genuinely absent (a user with no bio), the object does not exist (book(id: "999") finds nothing), or something failed. GraphQL does not distinguish these in the data; the errors array tells you if something failed. Because null can carry three meanings, a nullable field forces the client to handle it. A non-null field is a statement that the answer always exists.

Errors bubble up to the nearest nullable field

When a resolver throws, or returns null for a non-null field, the server cannot put null there. So it sets the parent to null instead, and repeats the rule if the parent is also non-null. The error "bubbles up" until it reaches a nullable position, which absorbs it. If it reaches the very top, the whole data becomes null.

flowchart BT
  A["name: String! (error)"] --> B["viewer: User (nullable)"]
  B --> C["data: viewer = null"]

The failing non-null field nulls its parent; the nullable viewer stops the spread.

The stand-in below implements exactly that rule in about 40 lines. It describes types with small helpers (nn(...) for !, list(...) for [ ]), runs the same data through four list types, and shows the response for each. The second item is a function that throws, like a resolver that fails.

JS Stand-in: the four list types under an error

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Compare the four results:

  • [Int]: only the bad item becomes null. The others survive.
  • [Int!]: an item cannot be null, so the list becomes null.
  • [Int]!: items may be null, so the list stays intact, like [Int].
  • [Int!]!: item null is not allowed, the list may not be null either, and scores itself is non-null in Query, so the error reaches the top and data is null.

Each response also has an entry in errors with the message and the path to where it happened (["scores", 1] is "the field scores, index 1").

Partial data versus no data

The most important consequence: the more ! you add, the larger the blast radius of one failure. The next stand-in reuses the executor with an object type. Study the three cases.

JS Stand-in: how far an error travels

Press Run (or Ctrl + Enter) to see the console output here.

No output.

When the nullable email fails, the client still gets the user's name (partial data). When the non-null name fails, viewer becomes null if the field is nullable, but the whole data is null if viewer is User!. Same failure, very different outcome for the user of your app.

Choosing nullability

Practical rules that keep schemas healthy:

  • Use ! for things that truly cannot be absent: id, and fields your own data model guarantees.
  • Make fields nullable if they depend on something that can fail: another service, a slow third-party call, or an optional permission check. A failure then hides only that field.
  • Root fields that look up one thing (book(id:)) are usually nullable, because "not found" is normal.
  • Lists of objects: prefer [Item!]!. Avoid null items unless they have a real meaning.
  • Changing nullability later is risky: loosening String! to String is a breaking change for clients that assumed it was never null; tightening is breaking for the server. Start nullable when unsure and tighten when you are certain. See Schema Design Best Practices and Schema Evolution, Federation and Tooling.

Arguments follow the same syntax: book(id: ID!) makes the argument required, while books(limit: Int) makes it optional.

When you read a type, say it out loud from the outside in: [Int!]! is "a non-null list of non-null integers".

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does [String!] allow?

    The ! inside the brackets applies to items, and there is no ! after the brackets, so the list itself may be null.
  2. 2. A non-null field fails in a resolver. What happens?

    The server cannot return null for a non-null field, so the null moves up to the closest nullable ancestor. If there is none, data is null.
  3. 3. Which type is the usual choice for a field returning many objects?

    [Item!]! gives clients a list that is always present with items that are always present; no results is an empty list.
  4. 4. Why make a field nullable if it depends on another service?

    A nullable field absorbs its own error, so the rest of the response stays usable.

Summary

  • Types are nullable by default; ! means never null; [T] is a list.
  • The four list types differ in whether the list and its items can be null; [T!]! is the common choice for collections.
  • Empty results should be [], not null.
  • A failure in a non-null position bubbles up to the nearest nullable field, or nulls all of data.
  • More ! means stronger guarantees but bigger blast radius for errors; make fragile fields nullable.
  • Tightening or loosening nullability later can break clients.

Next: Enums, Interfaces and Unions.