GraphQL Schema Design: Types, Queries, Mutations
On this page
Why the GraphQL schema is the API
In GraphQL, the schema defines everything a client can ask for. Generated client types, documentation and query validation all come from it. Mistakes here, such as wrong nullability or table-shaped types, spread to every client.
GraphQL types and nullability
type User {
id: ID!
name: String!
email: String # only the user themselves or an admin may read it
}
type Post {
id: ID!
title: String!
author: User!
createdAt: String!
}- Scalars:
ID,String,Int,Float,Boolean, plus custom scalars likeDateTime.createdAt: String!above works, but aDateTimescalar documents and validates the format, so prefer it in real schemas. !means non-null. Fields are nullable by default.- Lists:
[Post!]!is a non-null list of non-null posts.
Nullability is a real design decision. If a non-null field fails to resolve, the null propagates to its nearest nullable parent, possibly blanking a large part of the response. Tested with GraphQL Yoga: Post.viewCount was declared Int!, and its resolver failed because an analytics service was down:
{"errors":[{"message":"analytics service unavailable","path":["post","viewCount"]}],
"data":{"post":null}}The title loaded fine, but because viewCount couldn't be null, GraphQL nulled out the whole post. Declared as viewCount: Int, the response would have kept the title with "viewCount": null. Fields that can fail independently (data from another service, permission-gated fields like email) are often better nullable, so one failure doesn't take out the whole screen.
Designing query entry points
type Query {
posts(first: Int = 10, after: String): PostConnection!
user(id: ID!): User
}Design root fields around what clients need to look up: a single object by ID returns a nullable type (it may not exist); lists use connections (Day 17).
Mutations with input and payload types
input AddCommentInput {
postId: ID!
text: String!
}
type AddCommentPayload {
comment: Comment
errors: [UserError!]!
}
type UserError {
field: String
message: String!
}
type Mutation {
addComment(input: AddCommentInput!): AddCommentPayload!
}- One input object per mutation, so you can add fields later without changing the argument list.
- A payload type instead of returning
Commentdirectly, so you can return the created object, related data and errors together, and add fields later. - Name mutations as actions:
addComment,publishPost,cancelOrder, not genericupdatePostwith a status field.
Returning validation errors as data
GraphQL has a top-level errors array, but it's designed for exceptions, not for "this field is invalid". Returning expected errors in the payload makes them part of the typed schema. Tested with GraphQL Yoga:
mutation {
addComment(input: { postId: "7", text: " " }) {
comment { id }
errors { field message }
}
}{"data":{"addComment":{"comment":null,"errors":[{"field":"text","message":"must not be empty"}]}}}The client handles errors like any other data, with generated types. Unexpected failures (database down, not authenticated) still go in the top-level errors array.
GraphQL schema design guidelines
- Model the domain, not the database:
Post.authorreturns aUser, not anauthorIdthe client must look up. - Prefer specific fields to generic ones:
publishedAtrather than a JSON blob. - Use enums for fixed sets of values.
- Plan for evolution: add fields freely, deprecate with
@deprecated(reason: "..."), remove only after usage drops (Day 23). - Lint the schema (graphql-eslint) and check changes for breaking changes in CI.
Check yourself
The null propagates to the nearest nullable parent field, which becomes null, possibly hiding a large part of the response.
New input fields can be added later without changing the mutation's argument list, keeping changes backward compatible, and each mutation's validation can evolve on its own instead of sharing a type with other mutations.
They become part of the typed schema, so clients handle them as structured data, with fields and codes, rather than parsing exception messages from the top-level errors array, which is better reserved for unexpected failures.
When it can legitimately be missing, or when its resolver might fail independently, such as data from another service. Nullable fields keep one failure from wiping out a larger part of the response.
They lose type checking and self-documentation, since the schema says nothing about what's allowed. Specific mutations like changeEmail express intent, can enforce their own rules and permissions, and are easier to evolve and audit.