name: graphql-schema-design description: GraphQL schema design including types, fields, pagination, nullability, naming conventions, and descriptions. Use when designing or modifying GraphQL schemas.

GraphQL Schema Design

Expert guidance for designing well-structured GraphQL schemas.

Quick Reference

What Do You Need?

1. Type design - Structs, interfaces, unions, enums
2. Field design - Nullability, arguments, defaults
3. Pagination - Relay-style connections
4. Naming - Conventions for consistency
5. Documentation - Descriptions, deprecations

Specify a number or describe your schema concern.

Routing

Critical Rules

• Default to nullable: Easier to make required later than vice versa
• Use Relay pagination: Connections with edges/nodes, not lists
• Document everything: Schema is the API documentation
• Deprecate before removing: @deprecated with reason, wait for clients to migrate
• Noun mutations for state changes: createUser, deletePost, closeCard
• Avoid business logic in schema: Schema describes shape, not behavior

Schema Template

"""
A user in the system
"""
type User {
    """
    The unique identifier of the user
    """
    id: ID!

    """
    The user's display name
    """
    name: String!

    """
    The user's email address (optional if not public)
    """
    email: String

    """
    Posts created by this user, paginated
    """
    posts(
        """
        Number of posts to return
        """
        first: Int
        """
        Cursor for pagination
        """
        after: String
    ): PostConnection!
}

"""
Paginated connection of posts
"""
type PostConnection {
    edges: [PostEdge!]!
    pageInfo: PageInfo!
    totalCount: Int!
}

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

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

Common Schema Issues

Nullability Guidelines

# Good: Nullable by default
type User {
    id: ID!
    name: String!          # Required for user
    email: String          # Optional (not all users have email)
    bio: String            # Optional (not all users filled it out)
    posts(first: Int): PostConnection!  # Connection required, edges may be empty
}

# Avoid: Too many required fields
type User {
    id: ID!
    name: String!
    email: String!         # Required may block mutations
    phone: String!         # Required may block mutations
    bio: String!           # Required may block mutations
}

Reference Index

Success Criteria

Schema is well-designed when:

• All types and fields have descriptions
• Collections use Relay pagination (not unbounded lists)
• Nullability is intentional (not default required)
• Naming follows conventions (PascalCase, camelCase)
• Deprecated fields have @deprecated with reason
• No breaking changes without deprecation period
• Schema reads as documentation for clients