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
| 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
- 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)
1---2name: graphql-schema3description: >4 Guide for designing GraphQL schemas following industry best practices. Use this skill when:5 (1) designing a new GraphQL schema or API,6 (2) reviewing existing schema for improvements,7 (3) deciding on type structures or nullability,8 (4) implementing pagination or error patterns,9 (5) ensuring security in schema design.10license: MIT11compatibility: Any GraphQL implementation (Apollo Server, graphql-js, Yoga, etc.)12metadata:13 source: https://skillmd.com/skills/apollographql/graphql-schema14 author: apollographql15 version: "1.0.0"16allowed-tools: Bash(npm:*) Bash(npx:*) Read Write Edit Glob Grep17---1819# GraphQL Schema Design Guide2021This 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.2223## Schema Design Principles2425### 1. Design for Client Needs2627- Think about what queries clients will write28- Organize types around use cases, not database tables29- Expose capabilities, not implementation details3031### 2. Be Explicit3233- Use clear, descriptive names34- Make nullability intentional35- Document with descriptions3637### 3. Design for Evolution3839- Plan for backwards compatibility40- Use deprecation before removal41- Avoid breaking changes4243## Quick Reference4445### Type Definition Syntax4647```graphql48"""49A user in the system.50"""51type User {52 id: ID!53 email: String!54 name: String55 posts(first: Int = 10, after: String): PostConnection!56 createdAt: DateTime!57}58```5960### Nullability Rules6162| Pattern | Meaning |63|---------|---------|64| String | Nullable - may be null |65| String! | Non-null - always has value |66| [String] | Nullable list, nullable items |67| [String!] | Nullable list, non-null items |68| [String]! | Non-null list, nullable items |69| [String!]! | Non-null list, non-null items |7071**Best Practice:** Use **[Type!]!** for lists - empty list over null, no null items.7273### Input vs Output Types7475```graphql76# Output type - what clients receive77type User {78 id: ID!79 email: String!80 createdAt: DateTime!81}8283# Input type - what clients send84input CreateUserInput {85 email: String!86 name: String87}8889# Mutation using input type90type Mutation {91 createUser(input: CreateUserInput!): User!92}93```9495### Interface Pattern9697```graphql98interface Node {99 id: ID!100}101102type User implements Node {103 id: ID!104 email: String!105}106107type Post implements Node {108 id: ID!109 title: String!110}111```112113### Union Pattern114115```graphql116union SearchResult = User | Post | Comment117118type Query {119 search(query: String!): [SearchResult!]!120}121```122123## Reference Files124125Detailed documentation for specific topics:126127- [Types](references/types.md) - Type design patterns, interfaces, unions, and custom scalars128- [Naming](references/naming.md) - Naming conventions for types, fields, and arguments129- [Pagination](references/pagination.md) - Connection pattern and cursor-based pagination130- [Errors](references/errors.md) - Error modeling and result types131- [Security](references/security.md) - Security best practices for schema design132133## Key Rules134135### Type Design136137- Define types based on domain concepts, not data storage138- Use interfaces for shared fields across types139- Use unions for mutually exclusive types140- Keep types focused (single responsibility)141- Avoid deep nesting - flatten when possible142143### Field Design144145- Fields should be named from client's perspective146- Return the most specific type possible147- Make expensive fields explicit (consider arguments)148- Use arguments for filtering, sorting, pagination149150### Mutation Design151152- Use single input argument pattern: `mutation(input: InputType!)`153- Return affected objects in mutation responses154- Model mutations around business operations, not CRUD155- Consider returning a union of success/error types156157### ID Strategy158159- Use globally unique IDs when possible160- Implement `Node` interface for refetchability161- Base64-encode compound IDs if needed162163## Ground Rules164165- ALWAYS add descriptions to types and fields166- ALWAYS use non-null (**!**) for fields that cannot be null167- ALWAYS use **[Type!]!** pattern for lists168- NEVER expose database internals in schema169- NEVER break backwards compatibility without deprecation170- PREFER dedicated input types over many arguments171- PREFER enums over arbitrary strings for fixed values172- USE `ID` type for identifiers, not `String` or `Int`173- USE custom scalars for domain-specific values (DateTime, Email, URL)174