GraphQL's schema definition language is concise enough to look self-explanatory until a client interprets a nullable list differently than the server intended. The punctuation is the contract.
Short answer: SDL defines object types, scalar fields, inputs, queries, mutations, and relationships. String! means a non-null string; [User!]! means a non-null list containing no null users.
type Query { order(id: ID!): Order }
type Order { id: ID!, totalCents: Int!, notes: String }
input CreateOrderInput { sku: ID!, quantity: Int! }
| SDL form | Meaning |
|---|---|
String | Value may be null |
String! | Value must not be null |
[User] | List and entries may be null |
[User!]! | List exists; entries exist |
Non-null is a promise with blast radius. If a resolver fails to produce a required child field, GraphQL may null out the enclosing result up to the next nullable boundary.
Model the nouns clients need, avoid generic JSON escape hatches for stable data, and deprecate fields before removal. A schema is a public API even when it lives in the same monorepo as its first client.
Cover photo by Google DeepMind on Pexels.