Schema-First Design
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
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.
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.
The Query Root
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.
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.
No comments yet. Be the first to start the thread!