Use when designing GraphQL schemas with type system, SDL patterns, field design, pagination, directives, and versioning strategies for maintainable and scalable APIs.
Read-only skill
Additional assets for this skill
This skill cannot use any tools. It operates in read-only mode without the ability to modify files or execute commands.
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.
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!]!
}
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 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
}
}
}
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 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 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 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)
}
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!
}
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
}
}
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
}
}
}
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!
}
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!
}
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!
}
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!]!
}
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
}
Use GraphQL schema design skills when: