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
- Give every new argument or input field a default value, or make it nullable. Existing clients don't send it, so a required field without a default makes their requests fail validation.
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
| Pattern |
Meaning |
| String |
Nullable - may be null |
| String! |
Non-null - always has value |
| [String] |
Nullable list, nullable items |
| [String!] |
Nullable list, non-null items |
| [String]! |
Non-null list, nullable items |
| [String!]! |
Non-null list, non-null items |
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
- ALWAYS paginate lists that can grow without limit, such as
Query.users or Post.comments: return a connection and give first a default page size
- NEVER expose database internals in schema
- NEVER break backwards compatibility without deprecation
- NEVER add a required argument or input field without a default value
- 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)
1---2name: graphql-schema3description: >4 Guide for designing and changing GraphQL schemas following industry best practices. Use this skill5 whenever you create or edit GraphQL SDL, such as a `schema.graphql` file or `typeDefs`, including when:6 (1) designing a new GraphQL schema or API,7 (2) adding or changing types, fields, arguments, mutations, or descriptions in an existing schema,8 (3) reviewing existing schema for improvements,9 (4) deciding on type structures or nullability,10 (5) implementing pagination or error patterns,11 (6) ensuring security in schema design.12license: MIT13compatibility: Any GraphQL implementation (Apollo Server, graphql-js, Yoga, etc.)14metadata:15 source: https://skillmd.com/skills/stanfish06/graphql-schema16 author: apollographql17 version: "1.0.2"18allowed-tools: Bash(npm:*) Bash(npx:*) Read Write Edit Glob Grep19---2021# GraphQL Schema Design Guide2223This 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.2425## Schema Design Principles2627### 1. Design for Client Needs2829- Think about what queries clients will write30- Organize types around use cases, not database tables31- Expose capabilities, not implementation details3233### 2. Be Explicit3435- Use clear, descriptive names36- Make nullability intentional37- Document with descriptions3839### 3. Design for Evolution4041- Plan for backwards compatibility42- Use deprecation before removal43- Avoid breaking changes44- Give every new argument or input field a default value, or make it nullable. Existing clients don't send it, so a required field without a default makes their requests fail validation.4546## Quick Reference4748### Type Definition Syntax4950```graphql51"""52A user in the system.53"""54type User {55 id: ID!56 email: String!57 name: String58 posts(first: Int = 10, after: String): PostConnection!59 createdAt: DateTime!60}61```6263### Nullability Rules6465| Pattern | Meaning |66|---------|---------|67| String | Nullable - may be null |68| String! | Non-null - always has value |69| [String] | Nullable list, nullable items |70| [String!] | Nullable list, non-null items |71| [String]! | Non-null list, nullable items |72| [String!]! | Non-null list, non-null items |7374**Best Practice:** Use **[Type!]!** for lists - empty list over null, no null items.7576### Input vs Output Types7778```graphql79# Output type - what clients receive80type User {81 id: ID!82 email: String!83 createdAt: DateTime!84}8586# Input type - what clients send87input CreateUserInput {88 email: String!89 name: String90}9192# Mutation using input type93type Mutation {94 createUser(input: CreateUserInput!): User!95}96```9798### Interface Pattern99100```graphql101interface Node {102 id: ID!103}104105type User implements Node {106 id: ID!107 email: String!108}109110type Post implements Node {111 id: ID!112 title: String!113}114```115116### Union Pattern117118```graphql119union SearchResult = User | Post | Comment120121type Query {122 search(query: String!): [SearchResult!]!123}124```125126## Reference Files127128Detailed documentation for specific topics:129130- [Types](references/types.md) - Type design patterns, interfaces, unions, and custom scalars131- [Naming](references/naming.md) - Naming conventions for types, fields, and arguments132- [Pagination](references/pagination.md) - Connection pattern and cursor-based pagination133- [Errors](references/errors.md) - Error modeling and result types134- [Security](references/security.md) - Security best practices for schema design135136## Key Rules137138### Type Design139140- Define types based on domain concepts, not data storage141- Use interfaces for shared fields across types142- Use unions for mutually exclusive types143- Keep types focused (single responsibility)144- Avoid deep nesting - flatten when possible145146### Field Design147148- Fields should be named from client's perspective149- Return the most specific type possible150- Make expensive fields explicit (consider arguments)151- Use arguments for filtering, sorting, pagination152153### Mutation Design154155- Use single input argument pattern: `mutation(input: InputType!)`156- Return affected objects in mutation responses157- Model mutations around business operations, not CRUD158- Consider returning a union of success/error types159160### ID Strategy161162- Use globally unique IDs when possible163- Implement `Node` interface for refetchability164- Base64-encode compound IDs if needed165166## Ground Rules167168- ALWAYS add descriptions to types and fields169- ALWAYS use non-null (**!**) for fields that cannot be null170- ALWAYS use **[Type!]!** pattern for lists171- ALWAYS paginate lists that can grow without limit, such as `Query.users` or `Post.comments`: return a connection and give `first` a default page size172- NEVER expose database internals in schema173- NEVER break backwards compatibility without deprecation174- NEVER add a required argument or input field without a default value175- PREFER dedicated input types over many arguments176- PREFER enums over arbitrary strings for fixed values177- USE `ID` type for identifiers, not `String` or `Int`178- USE custom scalars for domain-specific values (DateTime, Email, URL)