Skip to content
API Design Learn/GraphQL Foundations
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Schema-First Design

4 min read

You'll learn to

  • -Write GraphQL types with the built-in scalars, lists and the non-null mark (!)
  • -Explain why the schema is the one contract that every request is checked against before it runs
  • -Treat non-null as a lifelong promise, and see what happens when the data breaks it

A REST API's contract is spread across every endpoint's own request and response shape. GraphQL turns that around. There is exactly one schema, which describes every type and every query or mutation the API supports, and each client request is checked against that schema before it ever runs. GraphQL is a query language for APIs in which the client says exactly which fields it wants, and gets back just those.

An Analogy: The Restaurant Menu

A menu lists every dish you can order and what each one contains. You cannot order something that is not on it, and the kitchen can check your order against the menu before starting to cook. The schema is the menu. A mark of ! is the kitchen's promise that an item always comes with a given part.

Types and Scalars

A basic GraphQL type, built from scalars and other types
type User {
  id: ID!
  name: String!
  email: String!
  age: Int
  isVerified: Boolean!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
  placedBy: User!
}
  • -A scalar is a basic value. GraphQL's built-in ones are Int, Float, String, Boolean and ID (a unique identifier, sent as text but meaning something different from an ordinary String).
  • -A type such as User or Order is a named object made of fields, each with its own type.
  • -A field's type can be another object type, which lets the schema express relationships such as orders: [Order!]!, the same way a foreign key does in a database.

The Non-Null Modifier: A Deliberate, Consequential Choice

A ! after a type means the field can never be null: if a query includes it, the server guarantees a value. That sounds like a small detail, but getting it wrong in either direction costs something. Mark a field non-null that later needs to be nullable, and that is a breaking change, because clients assumed it could never be null. Mark everything nullable "to be safe", and every client has to null-check data that is in practice always there.

The practical difference non-null makes to the caller
type User {
  name: String!   # every User always has a name - clients never null-check this
  bio: String     # bio is genuinely optional - clients must handle null
}

The demo shows the schema acting as a gatekeeper. Query 1 asks for fields that exist, and a nullable field may be empty. Query 2 asks for a field that does not exist, and is rejected before any data is touched. Query 3 hits a data bug: the schema promised name is never null, so the server reports an error instead of breaking the promise.

Press Run: a missing field is rejected up front, and a broken non-null promise is reported

The Query Root

The entry points every query starts from
type Query {
  user(id: ID!): User
  users(limit: Int, offset: Int): [User!]!
  order(id: ID!): Order
}

The Query type is the entry point. Every field on it is a top-level query a client can run, each with its own arguments, like id: ID!. Everything reachable from a Query field's return type becomes queryable in one request, here all of User's fields and, through orders, Order's fields. That is the structural source of "ask for exactly what you need, in one round trip".

Treat non-null as a promise you keep for the schema's whole lifetime, not a default to reach for. When you are unsure whether a field can ever be absent, start nullable. Loosening a non-null field later is a breaking change, but tightening a nullable one rarely is.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design Schema Genesis in the API Design Lab's GraphQL Mastery act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!