Enums, Lists, and Non-Null Modifiers

Enums Lock a Field to a Closed Set

A field that may hold one of four states is everywhere in real APIs: order status, plan tier, severity. Typed it as String and every consumer re-implements the same validation, discovers valid values from the code, and breaks on the day someone writes "Cancelled" instead of "CANCELED".

enum OrderStatus {
  PENDING
  PAID
  SHIPPED
  CANCELLED
}

type Order {
  id: ID!
  status: OrderStatus!
  statusHistory: [StatusChange!]!
}

type StatusChange {
  at: String!
  from: OrderStatus
  to: OrderStatus!
}

The enum becomes a first-class type: it can be used in output fields, in arguments, and inside input objects, and every use draws from the same declared set.

Enum values are names, not strings. They must be valid GraphQL names: no quotes, no spaces, no leading digits, and they cannot collide with true, false, null, or the reserved __ prefix. That constraint is a feature: code generators turn the set into a union type, so an editor autocompletes the four valid values and flags CANCELED before the code compiles, see TypeScript code generation.

Invalid values fail early. A bad literal inside the query fails validation; the same bad value arriving through a variable fails variable coercion. Either way the request stops before execution, which is precisely what status: String could never promise.

Evolution is asymmetric. Adding an enum value is additive and safe, because no existing client can hold it. Removing one breaks every query and every client literal that uses it, so removals follow the same deprecation discipline as any other breaking change; see schema evolution rules and deprecation strategy.

Six Ways to Wrap a Type

List and non-null are wrappers that compose, and each combination states a different promise about the data. Reading them as a matrix is faster than memorizing six rules.

Two structural rules make the matrix predictable: the ! always binds to whatever is immediately to its left, and wrapping order matters because the two wrappers are distinct types. [String]! is a non-null list of possibly-null strings; [String!] is a nullable list whose items are never null. A validator treats them as different types, so assigning one where the other is declared is an error rather than a coercion.

What each looks like on the wire:

{ "tags": null }          // legal for [String] and [String]!, illegal for [String]!
{ "tags": [] }            // legal for all three list declarations: empty is not null
{ "tags": ["a", null] }   // legal only for [String] and [String]!

The design consequences are concrete:

• [Order!]! for a screen that cannot render without its list, and cannot render a row without an id.
• [Order] when individual rows may fail but the screen should still show the rest.
• [String]! when the list is guaranteed but entries may be unknown.

Note that null and [] are different answers: an empty list means "none found," null means "unknown or failed." Collapsing them in the schema forces every consumer to guess, which is the problem wrappers exist to prevent.

Arguments follow the same matrix. A field declared search(term: String!) rejects a missing argument during validation, so every caller must commit to a term; search(term: String) lets the caller omit it entirely and pushes the "no filter" decision into the resolver. Declaring it wrong in either direction is felt immediately: either clients send arguments they do not care about, or filtering silently stops happening.

When Null Breaks the Contract

Declaring a field String! is a promise that it will never be null. The specification's enforcement of that promise is the single most surprising behavior in GraphQL, and it deserves a full example.

type Query {
  event(id: ID!): Event!
}

type Event {
  id: ID!
  title: String!
  venue: Venue!
}

type Venue {
  name: String!
}

A resolver returns an event whose venue exists but whose name is null. One field violated one promise, and here is the chain reaction:

1. name cannot be null, so the executor raises a field error for it.
2. Since name is non-null inside Venue, Venue itself must become null - but venue: Venue! is also non-null, so the null propagates again.
3. event: Event! is non-null, so it propagates once more to the root.
4. The response collapses:

{
  "data": null,
  "errors": [
    {
      "message": "Cannot return null for non-nullable field Venue.name.",
      "path": ["event", "venue", "name"]
    }
  ]
}

One bad record blanked the entire screen. The fix is a schema decision, not a code fix: make event nullable so the failure stops at the top (data: { "event": null } plus an errors entry), or make venue nullable so the rest of the event still renders. Non-null is a commitment to build the whole branch from guaranteed parts; see null propagation semantics for the full rules and standard error shape for how the error is described.

The rule that makes the matrix and the chain consistent: errors propagate to the nearest nullable ancestor. If there is none before the root, data itself becomes null.

Interview angle: "What is the difference between [String]! and [String!]?" Answer with the matrix, then show you understand the cost by walking the propagation chain above.