---

name: graphql-schema-design description: Use when designing GraphQL schemas with type system, SDL patterns, field design, pagination, directives, and versioning strategies for maintainable and scalable APIs. allowed-tools: []

GraphQL Schema Design

Apply GraphQL schema design principles to create well-structured, maintainable, and scalable GraphQL APIs. This skill covers the type system, Schema Definition Language (SDL), field design patterns, pagination strategies, directives, and schema evolution techniques.

Core Type System

Object Types

Object types are the fundamental building blocks of GraphQL schemas. Each object type represents a kind of object you can fetch from your service, and what fields it has.

type User {
  id: ID!
  username: String!
  email: String!
  createdAt: DateTime!
  posts: [Post!]!
  profile: Profile
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  publishedAt: DateTime
  tags: [String!]!
}

Interface Types

Interfaces define abstract types that multiple object types can implement. Use interfaces when multiple types share common fields.

interface Node {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
}

interface Timestamped {
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Article implements Node & Timestamped {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  title: String!
  content: String!
  author: User!
}

type Comment implements Node & Timestamped {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  text: String!
  author: User!
  post: Post!
}

Union Types

Union types represent values that could be one of several object types. Use unions when a field can return different types without shared fields.

union SearchResult = Article | User | Tag | Comment

type Query {
  search(query: String!): [SearchResult!]!
}

# Query example
query {
  search(query: "graphql") {
    __typename
    ... on Article {
      title
      content
    }
    ... on User {
      username
      email
    }
    ... on Tag {
      name
      count
    }
  }
}

Enum Types

Enums define a specific set of allowed values for a field. Use enums for fields with a fixed set of options to ensure type safety.

enum UserRole {
  ADMIN
  MODERATOR
  USER
  GUEST
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
  DELETED
}

enum SortOrder {
  ASC
  DESC
}

type User {
  id: ID!
  role: UserRole!
  status: AccountStatus!
}

enum AccountStatus {
  ACTIVE
  SUSPENDED
  DEACTIVATED
}

Input Types

Input types are used for complex arguments in queries and mutations. They allow you to pass structured data as a single argument.

input CreateUserInput {
  username: String!
  email: String!
  password: String!
  profile: UserProfileInput
}

input UserProfileInput {
  firstName: String
  lastName: String
  bio: String
  avatarUrl: String
}

input UpdatePostInput {
  title: String
  content: String
  status: PostStatus
  tags: [String!]
}

input PostFilterInput {
  status: PostStatus
  authorId: ID
  tags: [String!]
  createdAfter: DateTime
  createdBefore: DateTime
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updatePost(id: ID!, input: UpdatePostInput!): Post!
}

type Query {
  posts(filter: PostFilterInput, limit: Int): [Post!]!
}

Custom Scalars

Custom scalars extend the built-in scalar types (String, Int, Float, Boolean, ID) with domain-specific types.

scalar DateTime
scalar EmailAddress
scalar URL
scalar JSON
scalar UUID
scalar PositiveInt
scalar Currency

type User {
  id: UUID!
  email: EmailAddress!
  website: URL
  createdAt: DateTime!
  metadata: JSON
  age: PositiveInt
}

type Product {
  id: ID!
  price: Currency!
  images: [URL!]!
}

Directives

Directives provide a way to modify execution behavior or add metadata to your schema.

# Built-in directives
type Query {
  # Skip field if condition is true
  user(id: ID!): User @skip(if: $skipUser)

  # Include field only if condition is true
  posts: [Post!]! @include(if: $includePosts)
}

type Post {
  id: ID!
  title: String!
  # Mark field as deprecated with migration hint
  oldTitle: String @deprecated(reason: "Use 'title' instead")
}

# Custom directives
directive @auth(requires: UserRole!) on FIELD_DEFINITION
directive @rateLimit(max: Int!, window: Int!) on FIELD_DEFINITION
directive @cacheControl(
  maxAge: Int!
  scope: CacheScope = PUBLIC
) on FIELD_DEFINITION | OBJECT

enum CacheScope {
  PUBLIC
  PRIVATE
}

type Query {
  me: User @auth(requires: USER)
  adminPanel: AdminData @auth(requires: ADMIN)

  publicPosts: [Post!]!
    @cacheControl(maxAge: 300)
    @rateLimit(max: 100, window: 60)
}

Nullable vs Non-Null Design

Carefully consider nullability in your schema design. Non-null fields provide stronger guarantees but reduce flexibility.

type User {
  # Required fields - will never be null
  id: ID!
  username: String!
  email: String!

  # Optional fields - may be null
  bio: String
  website: URL

  # Non-null list with nullable items
  # List itself will never be null, but items can be
  favoriteColors: [String]!

  # Nullable list with non-null items
  # List can be null, but if present, items won't be
  phoneNumbers: [String!]

  # Non-null list with non-null items
  # Neither list nor items will be null
  roles: [UserRole!]!

  # Optional relationship
  profile: Profile

  # Required relationship
  account: Account!
}

Pagination Patterns

Offset-Based Pagination

Simple pagination using limit and offset. Easy to implement but has performance issues with large offsets.

type Query {
  posts(limit: Int = 10, offset: Int = 0): PostsResult!
}

type PostsResult {
  posts: [Post!]!
  total: Int!
  hasMore: Boolean!
}

# Query example
query {
  posts(limit: 20, offset: 40) {
    posts {
      id
      title
    }
    total
    hasMore
  }
}

Cursor-Based Pagination (Connections)

More efficient for large datasets and supports bidirectional pagination. Based on Relay Connection specification.

type Query {
  posts(
    first: Int
    after: String
    last: Int
    before: String
  ): PostConnection!
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type PostEdge {
  node: Post!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

# Query example
query {
  posts(first: 10, after: "Y3Vyc29yOjEw") {
    edges {
      cursor
      node {
        id
        title
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Mutation Design Patterns

Input Object Pattern

Use input objects for mutations to allow for easier evolution and better organization of arguments.

type Mutation {
  createPost(input: CreatePostInput!): CreatePostPayload!
  updatePost(input: UpdatePostInput!): UpdatePostPayload!
  deletePost(input: DeletePostInput!): DeletePostPayload!
}

input CreatePostInput {
  title: String!
  content: String!
  authorId: ID!
  tags: [String!]
  publishedAt: DateTime
}

type CreatePostPayload {
  post: Post
  errors: [UserError!]
  success: Boolean!
}

type UserError {
  message: String!
  field: String
  code: String!
}

input UpdatePostInput {
  id: ID!
  title: String
  content: String
  status: PostStatus
}

type UpdatePostPayload {
  post: Post
  errors: [UserError!]
  success: Boolean!
}

Error Handling in Schema

Design your schema to support both field-level and mutation-level error handling.

type Mutation {
  # Option 1: Union return type
  login(email: String!, password: String!): LoginResult!
}

union LoginResult = LoginSuccess | LoginError

type LoginSuccess {
  user: User!
  token: String!
  expiresAt: DateTime!
}

type LoginError {
  message: String!
  code: LoginErrorCode!
}

enum LoginErrorCode {
  INVALID_CREDENTIALS
  ACCOUNT_LOCKED
  EMAIL_NOT_VERIFIED
}

# Option 2: Payload with errors array
type Mutation {
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
}

type UpdateUserPayload {
  user: User
  errors: [UserError!]
  success: Boolean!
}

Schema Stitching and Federation Basics

Schema Federation

Design schemas for federation by defining entities and extending types across services.

# User service
type User @key(fields: "id") {
  id: ID!
  username: String!
  email: String!
}

# Posts service
extend type User @key(fields: "id") {
  id: ID! @external
  posts: [Post!]!
}

type Post @key(fields: "id") {
  id: ID!
  title: String!
  content: String!
  author: User!
}

# Reviews service
extend type Post @key(fields: "id") {
  id: ID! @external
  reviews: [Review!]!
}

type Review {
  id: ID!
  rating: Int!
  comment: String
  post: Post!
}

Versioning Strategies

Field Deprecation

Mark fields as deprecated while maintaining backward compatibility.

type User {
  id: ID!
  name: String! @deprecated(
    reason: "Use 'firstName' and 'lastName' instead"
  )
  firstName: String!
  lastName: String!

  email: String! @deprecated(
    reason: "Use 'primaryEmail' from ContactInfo"
  )
  contactInfo: ContactInfo!
}

type ContactInfo {
  primaryEmail: String!
  secondaryEmails: [String!]!
}

Additive Changes

Add new fields and types without breaking existing queries.

# Version 1
type Post {
  id: ID!
  title: String!
  content: String!
}

# Version 2 - Additive changes
type Post {
  id: ID!
  title: String!
  content: String!
  # New fields added
  summary: String
  readingTime: Int
  tags: [Tag!]!
}

# New type added
type Tag {
  id: ID!
  name: String!
  color: String
}

Best Practices

1. Use meaningful names: Choose clear, descriptive names for types, fields, and arguments that reflect their purpose and domain
2. Design for nullable fields: Make fields nullable by default unless you can guarantee the value will always be present
3. Prefer input objects: Use input types for complex arguments in mutations to allow for easier evolution
4. Implement pagination: Always paginate list fields that could grow unbounded using cursor-based or offset-based patterns
5. Use enums for fixed sets: Define enums for fields with a limited set of possible values to ensure type safety
6. Document your schema: Add descriptions to types, fields, and arguments using GraphQL description syntax
7. Version through deprecation: Use @deprecated directive rather than removing fields to maintain backward compatibility
8. Design mutations carefully: Return payload types that include both the result and potential errors
9. Keep schema flat: Avoid deeply nested types that could lead to complex queries and N+1 problems
10. Use interfaces wisely: Define interfaces for shared fields across multiple types to enable polymorphic queries

Common Pitfalls

1. Over-fetching in schema design: Creating fields that return entire objects when only specific data is needed
2. Under-fetching: Not providing enough related data, forcing clients to make multiple requests
3. Circular dependencies: Creating circular references between types without careful resolver design
4. Breaking changes: Removing or renaming fields without deprecation period, breaking existing clients
5. No pagination: Returning unbounded lists that can cause performance issues as data grows
6. Inconsistent naming: Using different conventions for similar fields across types
7. Over-use of non-null: Making too many fields non-null, reducing schema flexibility and resilience
8. Missing error handling: Not designing proper error handling in mutation payloads
9. Ignoring N+1 problems: Creating schema designs that inherently lead to N+1 query problems
10. Poor input validation: Not defining constraints on input types, leading to runtime validation issues

When to Use This Skill

Use GraphQL schema design skills when:

• Designing a new GraphQL API from scratch
• Refactoring an existing GraphQL schema for better structure
• Adding new features to an existing schema
• Migrating from REST to GraphQL
• Implementing schema federation across microservices
• Optimizing schema for performance and maintainability
• Establishing schema design standards for a team
• Reviewing and improving schema design patterns
• Designing for long-term API evolution and versioning
• Creating reusable schema patterns and conventions

Resources

• GraphQL Specification - Official GraphQL specification
• GraphQL Best Practices - Official best practices guide
• Apollo Schema Design Guide Schema design patterns
• Relay Connection Specification - Cursor-based pagination standard
• GraphQL Schema Design Book - In-depth schema design resource