Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 3 · Lesson 15 · 4 min read

GraphQL Schema Design: Types, Queries, Mutations

On this page
  1. Why the GraphQL schema is the API
  2. GraphQL types and nullability
  3. Designing query entry points
  4. Mutations with input and payload types
  5. Returning validation errors as data
  6. GraphQL schema design guidelines
  7. Check yourself

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

GraphQL
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 like DateTime. createdAt: String! above works, but a DateTime scalar 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:

JSON
{"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

GraphQL
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

GraphQL
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 Comment directly, so you can return the created object, related data and errors together, and add fields later.
  • Name mutations as actions: addComment, publishPost, cancelOrder, not generic updatePost with a status field.
A schema of types and relationships, with queries as read entry points and mutations that take an input type and return a payload with data and user errors.
A schema of types and relationships, with queries as read entry points and mutations that take an input type and return a payload with data and user errors.

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:

GraphQL
mutation {
  addComment(input: { postId: "7", text: "  " }) {
    comment { id }
    errors { field message }
  }
}
JSON
{"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.author returns a User, not an authorId the client must look up.
  • Prefer specific fields to generic ones: publishedAt rather 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.