Schema design in GraphQL

This chapter follows Building a GraphQL server with NestJS.

A schema that mirrors database tables one-to-one often forces clients to stitch fields that product design already treats as one screen. Query-driven design starts from UI or API consumer needs, then maps fields to services and storage.

Start from client operations

Collect the GraphQL documents your first clients need (or write them in design review). If a screen loads upcomingEvents { name location { weather { temperature } } }, the schema should expose that graph directly instead of forcing five REST-shaped queries.

Keep internal microservice boundaries inside resolvers; the public schema stays stable while backends split or merge.

Naming conventions

Mutations should be verbs (createPost, archiveOrder). Queries are nouns or noun phrases (post, searchPosts). Consistency helps codegen and logs.

Nullability strategy

Prefer non-null for fields clients always need when the parent exists. Use nullable fields for optional enrichment (weather on Location) so one failed dependency does not bubble away the whole parent if you mark the parent nullable carefully.

Adding ! to an formerly optional output field is breaking for clients that must handle null. Removing ! changes error bubbling—also risky.

Cursor connections for pagination

Offset pagination (limit/offset) is simple but performs poorly on large tables. Relay cursor connections standardize pagination:

1
type Query {
2
  posts(first: Int, after: String): PostConnection!
3
}
4

5
type PostConnection {
6
  edges: [PostEdge!]!
7
  pageInfo: PageInfo!
8
}
9

10
type PostEdge {
11
  node: Post!
12
  cursor: String!
13
}
14

15
type PageInfo {
16
  hasNextPage: Boolean!
17
  endCursor: String
18
}

Clients pass after: endCursor from the previous page. NestJS and other libraries offer @nestjs/graphql plugins or helpers to generate connection types.

Mutation input and payload pattern

Group write arguments in a single input and return a payload with the changed entity:

1
input UpdateEmailInput {
2
  userId: ID!
3
  email: String!
4
}
5

6
type UpdateEmailPayload {
7
  user: User
8
  errors: [UserError!]
9
}
10

11
type Mutation {
12
  updateEmail(input: UpdateEmailInput!): UpdateEmailPayload!
13
}

Returning the updated user avoids a second round trip. Listing errors in the payload suits expected validation failures.

Errors as data versus the errors array

GraphQL’s top-level errors array fits unexpected failures and partial null bubbling. Domain errors (email taken, insufficient stock) are often clearer as union or interface results:

1
union CreateOrderResult = Order | ValidationError
2

3
type ValidationError {
4
  message: String!
5
  field: String
6
}

Clients branch with __typename without treating business rules as transport exceptions. Reserve errors for truly exceptional resolver throws and log them server-side.

Next: GraphQL clients compared.