GraphQL Schema Design Guide

This guide covers best practices for designing GraphQL schemas that are intuitive, performant, and maintainable. Schema design is primarily a server-side concern that directly impacts API usability.

Schema Design Principles

1. Design for Client Needs

• •Think about what queries clients will write
• •Organize types around use cases, not database tables
• •Expose capabilities, not implementation details

2. Be Explicit

• •Use clear, descriptive names
• •Make nullability intentional
• •Document with descriptions

3. Design for Evolution

• •Plan for backwards compatibility
• •Use deprecation before removal
• •Avoid breaking changes

Quick Reference

Type Definition Syntax

"""
A user in the system.
"""
type User {
  id: ID!
  email: String!
  name: String
  posts(first: Int = 10, after: String): PostConnection!
  createdAt: DateTime!
}

Nullability Rules

Best Practice: Use [Type!]! for lists - empty list over null, no null items.

Input vs Output Types

# Output type - what clients receive
type User {
  id: ID!
  email: String!
  createdAt: DateTime!
}

# Input type - what clients send
input CreateUserInput {
  email: String!
  name: String
}

# Mutation using input type
type Mutation {
  createUser(input: CreateUserInput!): User!
}

Interface Pattern

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  email: String!
}

type Post implements Node {
  id: ID!
  title: String!
}

Union Pattern

union SearchResult = User | Post | Comment

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

Reference Files

Detailed documentation for specific topics:

• •Types - Type design patterns, interfaces, unions, and custom scalars
• •Naming - Naming conventions for types, fields, and arguments
• •Pagination - Connection pattern and cursor-based pagination
• •Errors - Error modeling and result types
• •Security - Security best practices for schema design

Key Rules

Type Design

• •Define types based on domain concepts, not data storage
• •Use interfaces for shared fields across types
• •Use unions for mutually exclusive types
• •Keep types focused (single responsibility)
• •Avoid deep nesting - flatten when possible

Field Design

• •Fields should be named from client's perspective
• •Return the most specific type possible
• •Make expensive fields explicit (consider arguments)
• •Use arguments for filtering, sorting, pagination

Mutation Design

• •Use single input argument pattern: mutation(input: InputType!)
• •Return affected objects in mutation responses
• •Model mutations around business operations, not CRUD
• •Consider returning a union of success/error types

ID Strategy

• •Use globally unique IDs when possible
• •Implement Node interface for refetchability
• •Base64-encode compound IDs if needed

Ground Rules

• •ALWAYS add descriptions to types and fields
• •ALWAYS use non-null (!) for fields that cannot be null
• •ALWAYS use [Type!]! pattern for lists
• •NEVER expose database internals in schema
• •NEVER break backwards compatibility without deprecation
• •PREFER dedicated input types over many arguments
• •PREFER enums over arbitrary strings for fixed values
• •USE ID type for identifiers, not String or Int
• •USE custom scalars for domain-specific values (DateTime, Email, URL)