System Design (HLD)GraphQL

GraphQL: Query-Based API Architecture

LevelIntermediate

Duration90 mins

TopicGraphQL

2 / 5

Schema Definition

The Schema as Contract and Compass

In GraphQL, the schema is not merely documentation—it is the executable contract that governs every interaction between clients and servers. Unlike REST APIs where the contract is often implicit or externally documented in OpenAPI specifications, a GraphQL schema is the authoritative source of truth, validated at runtime and leveraged by tooling at build time.

The schema answers three fundamental questions:

What data exists? — Types define the domain model
How is data related? — Fields express relationships
What operations are possible? — Root types define entry points

Designing a good schema is one of the most critical decisions in GraphQL architecture. A well-designed schema enables clients to express their needs efficiently, evolves without breaking changes, and encodes domain knowledge that guides correct API usage.

What You Will Learn

By the end of this page, you will master the GraphQL type system—scalars, objects, interfaces, unions, enums, and input types. You'll understand nullability semantics, learn schema design principles that prevent common pitfalls, and develop intuition for designing schemas that evolve gracefully over years of production use.

The Type System Foundation

GraphQL's type system is the foundation upon which all queries are built. Every piece of data that flows through a GraphQL API has a type, and the schema defines the complete universe of possible types.

Type Categories in GraphQL:

Scalar Types — Atomic values (String, Int, Float, Boolean, ID, custom scalars)
Object Types — Composite types with named fields
Interface Types — Abstract types defining common fields
Union Types — Types representing one of several possible object types
Enum Types — Types with a fixed set of possible values
Input Object Types — Object types for mutation/query arguments

Every type (except Input Objects) can be used as output types, while only Scalars, Enums, and Input Objects can be used as input types. This distinction prevents recursive complexity in arguments.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
# ============================================
# SCALAR TYPES
# ============================================
 
# Built-in scalars
# String: UTF-8 character sequence
# Int: 32-bit signed integer
# Float: Double-precision floating-point
# Boolean: true or false
# ID: Unique identifier (serialized as String)
 
# Custom scalar definitions
scalar DateTime        # ISO-8601 datetime
scalar Email           # Validated email address
scalar URL             # Validated URL
scalar JSON            # Arbitrary JSON (escape hatch, use sparingly)
scalar PositiveInt     # Integer > 0
scalar BigInt          # Arbitrary precision integer
 
# ============================================
# ENUM TYPES
# ============================================
 
enum UserRole {
  ADMIN
  MODERATOR
  MEMBER
  GUEST
}
 
enum PostStatus {
  DRAFT
  PENDING_REVIEW
  PUBLISHED @deprecated(reason: "Use LIVE instead")
  LIVE
  ARCHIVED
}
 
enum SortOrder {
  ASC
  DESC
}
 
# ============================================
# OBJECT TYPES
# ============================================
 
type User {
  # Fields with scalar return types
  id: ID!
  email: Email!
  name: String!
  bio: String                    # Nullable field
  avatarUrl: URL
  createdAt: DateTime!
  
  # Field with enum return type
  role: UserRole!
  
  # Field with arguments
  posts(
    first: Int = 10
    after: String
    status: PostStatus
    orderBy: PostOrderBy
  ): PostConnection!
  
  # Computed/derived fields
  fullName: String!              # May be computed from firstName + lastName
  isVerified: Boolean!           # May involve complex business logic
  
  # Relationship fields
  followers: UserConnection!
  following: UserConnection!
  organization: Organization     # Nullable: user may not belong to org
}
 
type Post {
  id: ID!
  title: String!
  slug: String!
  content: String!
  excerpt: String
  status: PostStatus!
  publishedAt: DateTime
  createdAt: DateTime!
  updatedAt: DateTime!
  
  # Relationships
  author: User!
  category: Category
  tags: [Tag!]!                  # Non-null list of non-null items
  comments(first: Int, after: String): CommentConnection!
  
  # Metrics (may be computed or cached)
  viewCount: Int!
  likeCount: Int!
}
 
# ============================================
# INTERFACE TYPES
# ============================================
 
interface Node {
  """Global unique identifier for the object."""
  id: ID!
}
 
interface Timestamped {
  createdAt: DateTime!
  updatedAt: DateTime!
}
 
interface Authored {
  author: User!
}
 
# Types implementing interfaces
type Post implements Node & Timestamped & Authored {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  author: User!
  # ... other Post fields
}
 
type Comment implements Node & Timestamped & Authored {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  author: User!
  body: String!
  post: Post!
}
 
# ============================================
# UNION TYPES
# ============================================
 
union SearchResult = User | Post | Category | Tag
 
union FeedItem = Post | SharedPost | Poll | Article
 
union NotificationTarget = Post | Comment | User
 
type Notification implements Node {
  id: ID!
  message: String!
  target: NotificationTarget!    # Query with inline fragments
  createdAt: DateTime!
}
 
# ============================================
# INPUT OBJECT TYPES
# ============================================
 
input CreatePostInput {
  title: String!
  content: String!
  categoryId: ID
  tagIds: [ID!]
  status: PostStatus = DRAFT
  publishAt: DateTime             # Schedule for later
}
 
input UpdatePostInput {
  title: String
  content: String
  categoryId: ID
  tagIds: [ID!]
  status: PostStatus
}
 
input PostFilters {
  authorId: ID
  categoryId: ID
  status: PostStatus
  publishedAfter: DateTime
  publishedBefore: DateTime
  search: String
}
 
input PostOrderBy {
  field: PostOrderField!
  direction: SortOrder!
}
 
enum PostOrderField {
  CREATED_AT
  PUBLISHED_AT
  TITLE
  VIEW_COUNT
  LIKE_COUNT
}

Type Design Philosophy

Design types to represent domain concepts, not database tables. A User type might draw data from multiple tables (users, profiles, preferences) and compute fields dynamically (followerCount, isOnline). The schema models the domain as clients understand it, not as the database stores it.

Nullability Semantics: The Non-Null Operator

GraphQL's nullability system is one of its most nuanced features. Every field is nullable by default; the ! operator marks fields as non-null. This inversion from many programming languages has profound implications for schema design and error handling.

The Nullability Rules:

type Example {
  nullable: String        # Can be null
  required: String!       # Cannot be null
  nullableList: [String]   # List can be null, items can be null
  requiredList: [String]!  # List cannot be null, items can be null
  strictList: [String!]!   # List cannot be null, items cannot be null
}

Nullability Combinations and Their Meanings
Type Signature	List Null?	Items Null?	Example Valid Values
[String]	Yes	Yes	null, [], [""], [null], ["a", null]
[String]!	No	Yes	[], [""], [null], ["a", null]
[String!]	Yes	No	null, [], [""], ["a", "b"]
[String!]!	No	No	[], [""], ["a", "b"]

The Error Propagation Rule:

When a non-null field resolves to null (due to an error), GraphQL propagates null up the tree until it reaches a nullable field. This can cause entire branches of data to become null.

Example of Null Propagation:

query {
  user(id: "1") {        # Nullable
    name                  # Non-null
    posts {               # Non-null
      edges {             # Non-null
        node {            # Nullable
          title           # Non-null
          author {        # Non-null
            name          # Non-null - if this fails, propagates up
          }
        }
      }
    }
  }
}

If author.name fails and returns null on a non-null field, the error propagates:

author becomes null → but author is non-null
node becomes null → node is nullable ✓ (propagation stops here)

The individual edge's node becomes null, but other edges remain intact.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
// PRINCIPLE 1: Make fields non-null unless null has semantic meaning
 
// ❌ Wrong: Unnecessary nullability
type User {
  id: ID           // IDs should never be null
  name: String     // Does null mean empty or missing?
  createdAt: DateTime  // Timestamp should always exist
}
 
// ✅ Right: Intentional nullability
type User {
  id: ID!
  name: String!
  createdAt: DateTime!
  bio: String          // Nullable: user may not have set bio
  deletedAt: DateTime  // Nullable: null means not deleted
}
 
 
// PRINCIPLE 2: Consider error isolation for relationship fields
 
// Aggressive non-null (entire user disappears if posts fail)
type User {
  posts: [Post!]!  // If post fetching fails, error propagates to user
}
 
// Defensive nullability (posts can fail independently)
type User {
  posts: [Post]   // Individual posts can be null, list can be null
}
 
// Best practice: Use connection types with proper nullability
type User {
  posts(first: Int, after: String): PostConnection!
}
 
type PostConnection {
  edges: [PostEdge!]!      // List always present
  pageInfo: PageInfo!
  totalCount: Int!
}
 
type PostEdge {
  cursor: String!
  node: Post               // Node is nullable - individual failures isolated
}
 
 
// PRINCIPLE 3: Lists should almost always be non-null
 
// ❌ Ambiguous: Is null different from empty array?
type User {
  roles: [Role]
}
 
// ✅ Clear: Empty array means "no roles"
type User {
  roles: [Role!]!
}
 
 
// PRINCIPLE 4: Input types have different considerations
 
// For mutations, required fields should be non-null
input CreateUserInput {
  email: Email!    // Required to create user
  name: String!    // Required to create user
  bio: String      // Optional
}
 
// For updates, most fields should be nullable (patch semantics)
input UpdateUserInput {
  name: String     // Null means "don't update"
  bio: String      # Null means "don't update"
  # To explicitly clear bio, use a separate input pattern:
  clearBio: Boolean
}

Nullability Is a Commitment

Once you mark a field as non-null, removing the ! is a breaking change—existing clients expect a value. Start nullable and add ! later if you're unsure. It's easier to strengthen guarantees than to weaken them.

Interfaces and Abstract Types

Interfaces and Unions enable polymorphism in GraphQL, allowing fields to return different object types. Understanding when to use each is crucial for expressive schema design.

Interface vs Union:

Interface: Defines common fields that multiple types must implement. Use when types share structure.
Union: Groups disparate types that share no common fields. Use when types are fundamentally different.

Decision Framework:

Use Case	Choose	Reason
Share common fields across types	Interface	Avoid field duplication
Types have no structural similarity	Union	Force inline fragment usage
Need guaranteed fields on result	Interface	Common fields always available
Future types may vary significantly	Union	No structural commitment

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
# ============================================
# THE NODE INTERFACE (Relay Specification)
# ============================================
 
"""
An object with a globally unique ID.
Enables refetching any object by ID.
"""
interface Node {
  """
  The globally unique identifier for the object.
  Node IDs are opaque strings, often base64-encoded.
  Example: "VXNlcjoxMjM=" (base64 of "User:123")
  """
  id: ID!
}
 
# Enable global refetching
type Query {
  """Fetches an object given its global ID."""
  node(id: ID!): Node
  
  """Fetches objects given their global IDs."""
  nodes(ids: [ID!]!): [Node]!
}
 
# All types implement Node for consistent ID handling
type User implements Node {
  id: ID!
  # ...
}
 
type Post implements Node {
  id: ID!
  # ...
}
 
# ============================================
# INTERFACE INHERITANCE PATTERNS
# ============================================
 
interface Error {
  message: String!
  code: ErrorCode!
}
 
interface FieldError implements Error {
  message: String!
  code: ErrorCode!
  field: String!           # Additional field
  path: [String!]!         # Path to the field
}
 
type ValidationError implements FieldError & Error {
  message: String!
  code: ErrorCode!
  field: String!
  path: [String!]!
  constraint: String!      # Type-specific field
}
 
type AuthorizationError implements Error {
  message: String!
  code: ErrorCode!
  requiredPermission: Permission!
}
 
# ============================================
# UNION TYPES FOR HETEROGENEOUS RESULTS
# ============================================
 
union SearchResult = User | Post | Comment | Tag | Category
 
type Query {
  search(query: String!, types: [SearchType!]): [SearchResult!]!
}
 
# Querying unions requires inline fragments
query Search($query: String!) {
  search(query: $query) {
    # No common fields - must use fragments
    ... on User {
      id
      name
      avatarUrl
    }
    ... on Post {
      id
      title
      excerpt
      author { name }
    }
    ... on Comment {
      id
      body
      post { title }
    }
  }
}
 
# ============================================
# RESULT TYPES (Union for Success/Error)
# ============================================
 
type CreateUserSuccess {
  user: User!
}
 
type CreateUserError {
  errors: [FieldError!]!
}
 
union CreateUserResult = CreateUserSuccess | CreateUserError
 
type Mutation {
  createUser(input: CreateUserInput!): CreateUserResult!
}
 
# Usage in client
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    ... on CreateUserSuccess {
      user {
        id
        name
      }
    }
    ... on CreateUserError {
      errors {
        field
        message
        code
      }
    }
  }
}
 
# ============================================
# TYPE CONDITIONS WITH __typename
# ============================================
 
# Every object type has an implicit __typename field
query GetFeedWithTypes {
  feed(first: 10) {
    edges {
      node {
        __typename   # Returns "Post", "Photo", "Article", etc.
        ... on Post {
          title
          content
        }
        ... on Photo {
          imageUrl
          caption
        }
      }
    }
  }
}
 
# Clients use __typename for:
# 1. Runtime type discrimination
# 2. Cache normalization (Apollo Client's default key)
# 3. Fragment matching logic

The Payload Pattern

For mutations, consider returning union types that represent success or various error states. This pattern (CreateUserResult = CreateUserSuccess | CreateUserError) makes error handling explicit in the type system rather than relying on runtime error arrays or HTTP status codes.

Custom Scalars: Encoding Domain Constraints

The built-in scalars (String, Int, Float, Boolean, ID) are often insufficient to express domain constraints. Custom scalars encode validation logic and serialization rules directly in the type system.

When to Create Custom Scalars:

Validation: Email, URL, UUID, phone numbers
Formatting: DateTime, Currency, Percentage
Range Constraints: PositiveInt, Latitude, Longitude
Complex Types: JSON, BigInt, Decimal

Custom Scalar Contract:

A custom scalar must define three functions:

serialize(value): Convert internal value to JSON output
parseValue(value): Convert JSON input to internal value
parseLiteral(ast): Convert query literal to internal value

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
import { GraphQLScalarType, Kind, GraphQLError } from 'graphql';
 
// ============================================
// DATETIME SCALAR
// ============================================
 
export const DateTimeScalar = new GraphQLScalarType({
  name: 'DateTime',
  description: 'ISO-8601 formatted date-time string',
  
  // Called when sending data to client
  serialize(value: unknown): string {
    if (value instanceof Date) {
      return value.toISOString();
    }
    if (typeof value === 'string') {
      return new Date(value).toISOString();
    }
    throw new GraphQLError('DateTime cannot serialize non-date value');
  },
  
  // Called when parsing variable values from JSON
  parseValue(value: unknown): Date {
    if (typeof value !== 'string') {
      throw new GraphQLError('DateTime must be a string');
    }
    const date = new Date(value);
    if (isNaN(date.getTime())) {
      throw new GraphQLError('DateTime invalid format');
    }
    return date;
  },
  
  // Called when parsing literal values in the query
  parseLiteral(ast): Date {
    if (ast.kind !== Kind.STRING) {
      throw new GraphQLError('DateTime must be a string');
    }
    const date = new Date(ast.value);
    if (isNaN(date.getTime())) {
      throw new GraphQLError('DateTime invalid format');
    }
    return date;
  },
});
 
// ============================================
// EMAIL SCALAR WITH VALIDATION
// ============================================
 
const EMAIL_REGEX = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
 
export const EmailScalar = new GraphQLScalarType({
  name: 'Email',
  description: 'Validated email address',
  
  serialize(value: unknown): string {
    if (typeof value !== 'string') {
      throw new GraphQLError('Email must be a string');
    }
    return value.toLowerCase();
  },
  
  parseValue(value: unknown): string {
    if (typeof value !== 'string') {
      throw new GraphQLError('Email must be a string');
    }
    const email = value.toLowerCase().trim();
    if (!EMAIL_REGEX.test(email)) {
      throw new GraphQLError(`Invalid email format: ${value}`);
    }
    return email;
  },
  
  parseLiteral(ast): string {
    if (ast.kind !== Kind.STRING) {
      throw new GraphQLError('Email must be a string');
    }
    const email = ast.value.toLowerCase().trim();
    if (!EMAIL_REGEX.test(email)) {
      throw new GraphQLError(`Invalid email format: ${ast.value}`);
    }
    return email;
  },
});
 
// ============================================
// POSITIVE INT SCALAR
// ============================================
 
export const PositiveIntScalar = new GraphQLScalarType({
  name: 'PositiveInt',
  description: 'Positive integer (greater than 0)',
  
  serialize(value: unknown): number {
    if (typeof value !== 'number' || !Number.isInteger(value)) {
      throw new GraphQLError('PositiveInt must be an integer');
    }
    if (value <= 0) {
      throw new GraphQLError('PositiveInt must be positive');
    }
    return value;
  },
  
  parseValue(value: unknown): number {
    if (typeof value !== 'number' || !Number.isInteger(value)) {
      throw new GraphQLError('PositiveInt must be an integer');
    }
    if (value <= 0) {
      throw new GraphQLError('PositiveInt must be positive');
    }
    return value;
  },
  
  parseLiteral(ast): number {
    if (ast.kind !== Kind.INT) {
      throw new GraphQLError('PositiveInt must be an integer');
    }
    const value = parseInt(ast.value, 10);
    if (value <= 0) {
      throw new GraphQLError('PositiveInt must be positive');
    }
    return value;
  },
});
 
// ============================================
// JSON SCALAR (Escape Hatch)
// ============================================
 
export const JSONScalar = new GraphQLScalarType({
  name: 'JSON',
  description: 'Arbitrary JSON value. Use sparingly - prefer typed fields.',
  
  serialize(value: unknown): unknown {
    return value; // Pass through
  },
  
  parseValue(value: unknown): unknown {
    return value; // Accept any valid JSON
  },
  
  parseLiteral(ast, variables): unknown {
    switch (ast.kind) {
      case Kind.STRING:
      case Kind.BOOLEAN:
        return ast.value;
      case Kind.INT:
      case Kind.FLOAT:
        return parseFloat(ast.value);
      case Kind.OBJECT:
        return parseObjectLiteral(ast, variables);
      case Kind.LIST:
        return ast.values.map(v => parseLiteral(v, variables));
      case Kind.NULL:
        return null;
      case Kind.VARIABLE:
        return variables?.[ast.name.value];
      default:
        throw new GraphQLError('Unsupported literal kind');
    }
  },
});

Avoid the JSON Escape Hatch

A JSON scalar accepts any structure, bypassing GraphQL's type safety. Use it only for truly dynamic, unstructured data (user-defined metadata, feature flags). For everything else, model the structure explicitly—that's the entire point of a type system.

The Directive System

Directives are annotations that modify schema behavior or query execution. They're GraphQL's extension mechanism for cross-cutting concerns.

Built-in Directives:

@deprecated(reason: String) — Mark fields/enum values as deprecated
@skip(if: Boolean!) — Conditionally skip field in query
@include(if: Boolean!) — Conditionally include field in query
@specifiedBy(url: String!) — Link scalar specification (added in GraphQL 2021)

Custom Directive Categories:

Schema Directives: Transform schema at build time (e.g., @auth, @cache)
Executable Directives: Modify query execution (e.g., @defer, @stream)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
# ============================================
# BUILT-IN DIRECTIVES
# ============================================
 
type User {
  id: ID!
  username: String!
  
  # Deprecation with migration guidance
  email: String! @deprecated(reason: "Use emailAddress instead")
  emailAddress: Email!
}
 
enum UserStatus {
  ACTIVE
  INACTIVE @deprecated(reason: "Use DEACTIVATED instead")
  DEACTIVATED
  SUSPENDED
}
 
# Conditional fields in queries
query GetUser($userId: ID!, $includeEmail: Boolean!, $skipPosts: Boolean!) {
  user(id: $userId) {
    id
    name
    email @include(if: $includeEmail)
    posts @skip(if: $skipPosts) {
      title
    }
  }
}
 
# ============================================
# CUSTOM SCHEMA DIRECTIVES
# ============================================
 
# Define the directive
directive @auth(
  requires: Role = USER
) on OBJECT | FIELD_DEFINITION
 
directive @cacheControl(
  maxAge: Int!
  scope: CacheScope = PUBLIC
) on OBJECT | FIELD_DEFINITION
 
directive @deprecated(
  reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
 
directive @rateLimit(
  limit: Int!
  window: Int!  # seconds
) on FIELD_DEFINITION
 
enum Role {
  ADMIN
  MODERATOR
  USER
  GUEST
}
 
enum CacheScope {
  PUBLIC
  PRIVATE
}
 
# Apply directives to schema
type Query {
  # Public, cacheable
  publicPosts: [Post!]!
    @cacheControl(maxAge: 300, scope: PUBLIC)
  
  # Requires authentication
  me: User!
    @auth(requires: USER)
    @cacheControl(maxAge: 60, scope: PRIVATE)
  
  # Admin only, rate limited
  adminStats: AdminStats!
    @auth(requires: ADMIN)
    @rateLimit(limit: 10, window: 60)
}
 
type User @auth(requires: USER) {
  id: ID!
  name: String!
  email: Email! @auth(requires: ADMIN)  # Only admins see email
  posts: [Post!]!
}
 
# ============================================
# CUSTOM EXECUTABLE DIRECTIVES
# ============================================
 
# @defer and @stream (pending GraphQL spec additions)
directive @defer(
  label: String
  if: Boolean! = true
) on FRAGMENT_SPREAD | INLINE_FRAGMENT
 
directive @stream(
  label: String
  initialCount: Int! = 0
  if: Boolean! = true
) on FIELD
 
# Usage: Defer expensive computations
query GetUserProfile($userId: ID!) {
  user(id: $userId) {
    id
    name
    avatarUrl
    
    # Defer expensive recommendation computation
    ... @defer(label: "recommendations") {
      recommendedPosts {
        id
        title
      }
    }
    
    # Stream large lists
    notifications @stream(initialCount: 5) {
      id
      message
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
import { mapSchema, getDirective, MapperKind } from '@graphql-tools/utils';
import { GraphQLSchema, defaultFieldResolver, GraphQLError } from 'graphql';
 
// ============================================
// AUTH DIRECTIVE IMPLEMENTATION
// ============================================
 
interface AuthDirectiveArgs {
  requires: 'ADMIN' | 'MODERATOR' | 'USER' | 'GUEST';
}
 
export function authDirective(directiveName: string) {
  const roleHierarchy = {
    GUEST: 0,
    USER: 1,
    MODERATOR: 2,
    ADMIN: 3,
  };
  
  return {
    authDirectiveTypeDefs: `
      directive @${directiveName}(requires: Role = USER) on OBJECT | FIELD_DEFINITION
      enum Role { ADMIN MODERATOR USER GUEST }
    `,
    
    authDirectiveTransformer: (schema: GraphQLSchema) =>
      mapSchema(schema, {
        [MapperKind.OBJECT_FIELD]: (fieldConfig, _fieldName, typeName) => {
          // Check for directive on field or parent type
          const fieldDirective = getDirective(schema, fieldConfig, directiveName)?.[0];
          const typeConfig = schema.getType(typeName);
          const typeDirective = typeConfig 
            ? getDirective(schema, typeConfig, directiveName)?.[0]
            : null;
          
          const directive = fieldDirective ?? typeDirective;
          
          if (directive) {
            const { requires } = directive as AuthDirectiveArgs;
            const requiredRole = roleHierarchy[requires];
            
            const originalResolver = fieldConfig.resolve ?? defaultFieldResolver;
            
            fieldConfig.resolve = async (source, args, context, info) => {
              const userRole = context.user?.role ?? 'GUEST';
              const userRoleLevel = roleHierarchy[userRole] ?? 0;
              
              if (userRoleLevel < requiredRole) {
                throw new GraphQLError(
                  `Unauthorized: requires ${requires} role`,
                  {
                    extensions: {
                      code: 'UNAUTHORIZED',
                      requiredRole: requires,
                      userRole: userRole,
                    }
                  }
                );
              }
              
              return originalResolver(source, args, context, info);
            };
          }
          
          return fieldConfig;
        },
      }),
  };
}
 
// ============================================
// CACHE CONTROL DIRECTIVE
// ============================================
 
export function cacheControlDirective(directiveName: string) {
  return {
    cacheControlDirectiveTypeDefs: `
      directive @${directiveName}(
        maxAge: Int!
        scope: CacheScope = PUBLIC
      ) on OBJECT | FIELD_DEFINITION
      enum CacheScope { PUBLIC PRIVATE }
    `,
    
    cacheControlDirectiveTransformer: (schema: GraphQLSchema) =>
      mapSchema(schema, {
        [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
          const directive = getDirective(schema, fieldConfig, directiveName)?.[0];
          
          if (directive) {
            const { maxAge, scope } = directive;
            const originalResolver = fieldConfig.resolve ?? defaultFieldResolver;
            
            fieldConfig.resolve = async (source, args, context, info) => {
              // Set cache hints on context for HTTP layer
              context.cacheControl = context.cacheControl ?? { maxAge: 0, scope: 'PUBLIC' };
              
              // Take minimum maxAge across all fields
              context.cacheControl.maxAge = Math.min(
                context.cacheControl.maxAge || Infinity,
                maxAge
              );
              
              // Scope degrades from PUBLIC to PRIVATE
              if (scope === 'PRIVATE') {
                context.cacheControl.scope = 'PRIVATE';
              }
              
              return originalResolver(source, args, context, info);
            };
          }
          
          return fieldConfig;
        },
      }),
  };
}

Directives vs Middleware

Directives encode cross-cutting concerns directly in the schema, making them visible to clients and tooling. Middleware operates at the resolver level but is invisible in the schema. Use directives when the behavior is part of the API contract (auth, caching), middleware for internal concerns (logging, metrics).

Schema Design Principles

A well-designed schema is intuitive, evolvable, and encodes domain knowledge. Here are principles distilled from production GraphQL systems serving billions of requests.

Core Schema Design Principles

•Design for the Domain, Not the Database — Types should represent domain concepts as clients understand them, not as they're stored. A User type might combine users, profiles, and preferences tables.
•Names Are Documentation — Use precise, consistent naming. If something is a list, pluralize. If it's a relationship, name it from the perspective of the parent (user.posts, not user.hasMany).
•Prefer Specific Types Over Generic Ones — Instead of a generic node field returning Node, provide specific fields like user, post. Generic interfaces are for refetching, not primary navigation.
•Use Enums for Fixed Sets — If a field has a limited set of valid values, use an enum. String fields with documented allowed values are a code smell.
•Model State, Not Actions — Fields should represent current state (status: PUBLISHED), not past actions (wasPublished: true). Actions are mutations.
•Flat Is Better Than Nested for Inputs — Deep input nesting makes queries verbose and validation complex. Prefer flat inputs with descriptive field names.
•Use Connections for Lists — Any list that might need pagination should use the connection pattern from day one. Retrofitting pagination is a breaking change.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
# ============================================
# PATTERN: Relay Connection Specification
# ============================================
 
# Standard pagination pattern ensures consistency
type Query {
  posts(
    first: Int
    after: String
    last: Int
    before: String
    filter: PostFilter
  ): PostConnection!
}
 
type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!                  # Total matching, regardless of pagination
}
 
type PostEdge {
  cursor: String!                   # Opaque cursor for this edge
  node: Post!                       # The actual item
}
 
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}
 
# ============================================
# PATTERN: Semantic Naming
# ============================================
 
# ❌ Poor naming
type Query {
  getData(type: String!, id: Int!): JSON
  makeChange(data: JSON!): JSON
}
 
# ✅ Semantic naming
type Query {
  user(id: ID!): User
  users(filter: UserFilter): UserConnection!
  post(id: ID!): Post
  post(slug: String!): Post  # Alternate lookup
}
 
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
  publishPost(id: ID!): PublishPostPayload!
}
 
# ============================================
# PATTERN: Input/Payload Types
# ============================================
 
# Input types group mutation arguments
input CreatePostInput {
  title: String!
  content: String!
  categoryId: ID
  tags: [String!]
}
 
# Payload types provide structured results
type CreatePostPayload {
  post: Post               # The created resource
  userErrors: [UserError!]!  # Validation/business errors
}
 
type UserError {
  field: [String!]         # Path to field with error
  message: String!         # Human-readable message
  code: ErrorCode!         # Machine-readable code
}
 
# ============================================
# PATTERN: Field Arguments for Filtering
# ============================================
 
type User {
  # Avoid: separate fields for each filter combination
  # posts: [Post!]!
  # publishedPosts: [Post!]!
  # draftPosts: [Post!]!
  
  # Prefer: single field with filter arguments
  posts(
    status: PostStatus
    first: Int = 10
    after: String
  ): PostConnection!
}
 
# ============================================
# PATTERN: Avoiding Breaking Changes
# ============================================
 
# Never remove fields - deprecate them
type User {
  email: String! @deprecated(reason: "Use emailAddress for validated email")
  emailAddress: Email!      # New field with proper type
}
 
# Never change non-null to null (or vice versa) on existing fields
# Never change argument types
# Never remove enum values
 
# Safe additions:
# - New nullable fields
# - New nullable arguments with defaults
# - New enum values (unless clients use exhaustive matching)
# - New types

The Deliberate Schema

Every schema decision encodes assumptions about your domain. A non-null field says 'this will always exist.' An enum says 'these are the only valid values.' A connection says 'this list can grow unboundedly.' Make these decisions deliberately, with full awareness of their implications.

Schema Evolution and Versioning

Unlike REST APIs that often use URL versioning (/v1/users, /v2/users), GraphQL favors continuous evolution without breaking changes. The schema becomes a living document that grows without fracturing the client ecosystem.

The Evolution Philosophy:

No Breaking Changes: Existing queries must continue to work
Deprecation Over Removal: Mark old fields deprecated, don't delete them
Additive Changes Only: New fields, arguments, and types are safe
Sunset with Data: Use analytics to know when deprecated fields are unused

Change Safety Matrix
Change Type	Safety	Notes
Add nullable field	✅ Safe	Clients ignore unknown fields
Add non-null field	✅ Safe	Clients that don't request it are unaffected
Add nullable argument	✅ Safe	Must have default value
Add required argument	❌ Breaking	Existing queries fail
Add enum value	⚠️ Caution	Safe unless clients use exhaustive switch
Remove field	❌ Breaking	Existing queries fail
Rename field	❌ Breaking	Equivalent to remove + add
Change field type	❌ Breaking	Even changing Int to Float breaks
Nullability: null → non-null	❌ Breaking	Clients may now receive errors
Nullability: non-null → null	❌ Breaking	Violates client type expectations

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
# ============================================
# DEPRECATION LIFECYCLE
# ============================================
 
# Phase 1: Add new field alongside old
type User {
  name: String!                       # Original field
  fullName: String!                   # New field with better semantics
}
 
# Phase 2: Deprecate old field with reason
type User {
  name: String! @deprecated(reason: "Use fullName instead - includes proper formatting")
  fullName: String!
}
 
# Phase 3: (After analytics confirm no usage) Consider removal
# Only if you control all clients, or after long deprecation period
 
# ============================================
# FIELD ARGUMENT EVOLUTION
# ============================================
 
# Original field
type Query {
  posts(first: Int, after: String): PostConnection!
}
 
# Safe evolution: add optional argument with default
type Query {
  posts(
    first: Int = 20
    after: String
    orderBy: PostOrder = CREATED_AT_DESC  # New!
    filter: PostFilter                     # New!
  ): PostConnection!
}
 
# ============================================
# TYPE EVOLUTION
# ============================================
 
# Original type
type Post {
  author: User!
}
 
# Need to support multiple authors? Don't change author, add authors
type Post {
  author: User! @deprecated(reason: "Use authors field for multi-author support")
  authors: [User!]!           # New field
  primaryAuthor: User!        # Convenience accessor
}
 
# ============================================
# ENUM EVOLUTION
# ============================================
 
enum PostStatus {
  DRAFT
  PENDING
  PUBLISHED
  ARCHIVED
  SCHEDULED           # Safe to add
  # PENDING_REVIEW  # Would require deprecation cycle if replacing PENDING
}
 
# When adding enum values, document that clients should handle unknown values
# Client code should have a default case:
# switch (status) {
#   case 'DRAFT': ...
#   case 'PUBLISHED': ...
#   default: // Handle future values gracefully
# }
 
# ============================================
# SCHEMA REGISTRY AND VALIDATION
# ============================================
 
# Modern GraphQL tooling validates changes against registered schemas:
# 
# $ graphql schema:push --schema ./schema.graphql
# 
# ❌ BREAKING CHANGE DETECTED
# 
# Field 'User.email' was removed
#   This field is used by 47 operations across 12 clients
#   Last used: 2024-01-15
# 
# To proceed, use --force (not recommended)
# To safe deprecation, use 'graphql field:deprecate User.email "reason"'

When to Consider Versioning

While continuous evolution is preferred, sometimes version bumps are necessary: fundamental domain model changes, security-breaking changes requiring immediate removal, or when maintaining backward compatibility causes severe complexity. In such cases, consider running parallel schemas (/graphql/v1, /graphql/v2) with planned sunset dates.

Summary: Schema as Foundation

The schema is GraphQL's crown jewel—a type-safe contract that enables powerful tooling, prevents entire categories of bugs, and guides API evolution. Let's consolidate the key concepts:

Key Takeaways

•The Type System Is the Contract — Every type, field, and argument is enforced at runtime and leveraged by tooling at build time.
•Nullability Is Semantic — Use non-null (!) deliberately to indicate guarantees; remember that errors propagate through non-null chains.
•Interfaces and Unions Enable Polymorphism — Use interfaces for shared structure, unions for heterogeneous results.
•Custom Scalars Encode Domain Constraints — Email, DateTime, URL—encode validation in the type system, not in resolvers.
•Directives Extend Schema Capabilities — Use directives for cross-cutting concerns visible in the schema (auth, caching).
•Design for Evolution — Prefer additive changes, deprecation over removal, and analytics-driven sunset decisions.

What's Next:

With schema design understood, we now turn to resolvers—the functions that bring schemas to life by fetching data. We'll explore resolver architecture, the N+1 problem and DataLoader, error handling patterns, and performance optimization strategies.

Page Complete

You now understand GraphQL's type system—scalars, objects, interfaces, unions, enums, input types, and directives. You've learned nullability semantics, design principles, and evolution strategies. Next, we'll explore how resolvers implement this schema to fetch and transform data.

2 / 5

Loading learning content...

System Design (HLD)GraphQL

GraphQL: Query-Based API Architecture

LevelIntermediate

Duration90 mins

TopicGraphQL

2 / 5

Schema Definition

The Schema as Contract and Compass

The schema answers three fundamental questions:

What data exists? — Types define the domain model
How is data related? — Fields express relationships
What operations are possible? — Root types define entry points

What You Will Learn

The Type System Foundation

Type Categories in GraphQL:

Scalar Types — Atomic values (String, Int, Float, Boolean, ID, custom scalars)
Object Types — Composite types with named fields
Interface Types — Abstract types defining common fields
Union Types — Types representing one of several possible object types
Enum Types — Types with a fixed set of possible values
Input Object Types — Object types for mutation/query arguments

Every type (except Input Objects) can be used as output types, while only Scalars, Enums, and Input Objects can be used as input types. This distinction prevents recursive complexity in arguments.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
# ============================================
# SCALAR TYPES
# ============================================
 
# Built-in scalars
# String: UTF-8 character sequence
# Int: 32-bit signed integer
# Float: Double-precision floating-point
# Boolean: true or false
# ID: Unique identifier (serialized as String)
 
# Custom scalar definitions
scalar DateTime        # ISO-8601 datetime
scalar Email           # Validated email address
scalar URL             # Validated URL
scalar JSON            # Arbitrary JSON (escape hatch, use sparingly)
scalar PositiveInt     # Integer > 0
scalar BigInt          # Arbitrary precision integer
 
# ============================================
# ENUM TYPES
# ============================================
 
enum UserRole {
  ADMIN
  MODERATOR
  MEMBER
  GUEST
}
 
enum PostStatus {
  DRAFT
  PENDING_REVIEW
  PUBLISHED @deprecated(reason: "Use LIVE instead")
  LIVE
  ARCHIVED
}
 
enum SortOrder {
  ASC
  DESC
}
 
# ============================================
# OBJECT TYPES
# ============================================
 
type User {
  # Fields with scalar return types
  id: ID!
  email: Email!
  name: String!
  bio: String                    # Nullable field
  avatarUrl: URL
  createdAt: DateTime!
  
  # Field with enum return type
  role: UserRole!
  
  # Field with arguments
  posts(
    first: Int = 10
    after: String
    status: PostStatus
    orderBy: PostOrderBy
  ): PostConnection!
  
  # Computed/derived fields
  fullName: String!              # May be computed from firstName + lastName
  isVerified: Boolean!           # May involve complex business logic
  
  # Relationship fields
  followers: UserConnection!
  following: UserConnection!
  organization: Organization     # Nullable: user may not belong to org
}
 
type Post {
  id: ID!
  title: String!
  slug: String!
  content: String!
  excerpt: String
  status: PostStatus!
  publishedAt: DateTime
  createdAt: DateTime!
  updatedAt: DateTime!
  
  # Relationships
  author: User!
  category: Category
  tags: [Tag!]!                  # Non-null list of non-null items
  comments(first: Int, after: String): CommentConnection!
  
  # Metrics (may be computed or cached)
  viewCount: Int!
  likeCount: Int!
}
 
# ============================================
# INTERFACE TYPES
# ============================================
 
interface Node {
  """Global unique identifier for the object."""
  id: ID!
}
 
interface Timestamped {
  createdAt: DateTime!
  updatedAt: DateTime!
}
 
interface Authored {
  author: User!
}
 
# Types implementing interfaces
type Post implements Node & Timestamped & Authored {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  author: User!
  # ... other Post fields
}
 
type Comment implements Node & Timestamped & Authored {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!
  author: User!
  body: String!
  post: Post!
}
 
# ============================================
# UNION TYPES
# ============================================
 
union SearchResult = User | Post | Category | Tag
 
union FeedItem = Post | SharedPost | Poll | Article
 
union NotificationTarget = Post | Comment | User
 
type Notification implements Node {
  id: ID!
  message: String!
  target: NotificationTarget!    # Query with inline fragments
  createdAt: DateTime!
}
 
# ============================================
# INPUT OBJECT TYPES
# ============================================
 
input CreatePostInput {
  title: String!
  content: String!
  categoryId: ID
  tagIds: [ID!]
  status: PostStatus = DRAFT
  publishAt: DateTime             # Schedule for later
}
 
input UpdatePostInput {
  title: String
  content: String
  categoryId: ID
  tagIds: [ID!]
  status: PostStatus
}
 
input PostFilters {
  authorId: ID
  categoryId: ID
  status: PostStatus
  publishedAfter: DateTime
  publishedBefore: DateTime
  search: String
}
 
input PostOrderBy {
  field: PostOrderField!
  direction: SortOrder!
}
 
enum PostOrderField {
  CREATED_AT
  PUBLISHED_AT
  TITLE
  VIEW_COUNT
  LIKE_COUNT
}

Type Design Philosophy

Nullability Semantics: The Non-Null Operator

The Nullability Rules:

type Example {
  nullable: String        # Can be null
  required: String!       # Cannot be null
  nullableList: [String]   # List can be null, items can be null
  requiredList: [String]!  # List cannot be null, items can be null
  strictList: [String!]!   # List cannot be null, items cannot be null
}

Nullability Combinations and Their Meanings
Type Signature	List Null?	Items Null?	Example Valid Values
[String]	Yes	Yes	null, [], [""], [null], ["a", null]
[String]!	No	Yes	[], [""], [null], ["a", null]
[String!]	Yes	No	null, [], [""], ["a", "b"]
[String!]!	No	No	[], [""], ["a", "b"]

The Error Propagation Rule:

When a non-null field resolves to null (due to an error), GraphQL propagates null up the tree until it reaches a nullable field. This can cause entire branches of data to become null.

Example of Null Propagation:

query {
  user(id: "1") {        # Nullable
    name                  # Non-null
    posts {               # Non-null
      edges {             # Non-null
        node {            # Nullable
          title           # Non-null
          author {        # Non-null
            name          # Non-null - if this fails, propagates up
          }
        }
      }
    }
  }
}

If author.name fails and returns null on a non-null field, the error propagates:

author becomes null → but author is non-null
node becomes null → node is nullable ✓ (propagation stops here)

The individual edge's node becomes null, but other edges remain intact.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
// PRINCIPLE 1: Make fields non-null unless null has semantic meaning
 
// ❌ Wrong: Unnecessary nullability
type User {
  id: ID           // IDs should never be null
  name: String     // Does null mean empty or missing?
  createdAt: DateTime  // Timestamp should always exist
}
 
// ✅ Right: Intentional nullability
type User {
  id: ID!
  name: String!
  createdAt: DateTime!
  bio: String          // Nullable: user may not have set bio
  deletedAt: DateTime  // Nullable: null means not deleted
}
 
 
// PRINCIPLE 2: Consider error isolation for relationship fields
 
// Aggressive non-null (entire user disappears if posts fail)
type User {
  posts: [Post!]!  // If post fetching fails, error propagates to user
}
 
// Defensive nullability (posts can fail independently)
type User {
  posts: [Post]   // Individual posts can be null, list can be null
}
 
// Best practice: Use connection types with proper nullability
type User {
  posts(first: Int, after: String): PostConnection!
}
 
type PostConnection {
  edges: [PostEdge!]!      // List always present
  pageInfo: PageInfo!
  totalCount: Int!
}
 
type PostEdge {
  cursor: String!
  node: Post               // Node is nullable - individual failures isolated
}
 
 
// PRINCIPLE 3: Lists should almost always be non-null
 
// ❌ Ambiguous: Is null different from empty array?
type User {
  roles: [Role]
}
 
// ✅ Clear: Empty array means "no roles"
type User {
  roles: [Role!]!
}
 
 
// PRINCIPLE 4: Input types have different considerations
 
// For mutations, required fields should be non-null
input CreateUserInput {
  email: Email!    // Required to create user
  name: String!    // Required to create user
  bio: String      // Optional
}
 
// For updates, most fields should be nullable (patch semantics)
input UpdateUserInput {
  name: String     // Null means "don't update"
  bio: String      # Null means "don't update"
  # To explicitly clear bio, use a separate input pattern:
  clearBio: Boolean
}

Nullability Is a Commitment

Interfaces and Abstract Types

Interfaces and Unions enable polymorphism in GraphQL, allowing fields to return different object types. Understanding when to use each is crucial for expressive schema design.

Interface vs Union:

Interface: Defines common fields that multiple types must implement. Use when types share structure.
Union: Groups disparate types that share no common fields. Use when types are fundamentally different.

Decision Framework:

Use Case	Choose	Reason
Share common fields across types	Interface	Avoid field duplication
Types have no structural similarity	Union	Force inline fragment usage
Need guaranteed fields on result	Interface	Common fields always available
Future types may vary significantly	Union	No structural commitment

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
# ============================================
# THE NODE INTERFACE (Relay Specification)
# ============================================
 
"""
An object with a globally unique ID.
Enables refetching any object by ID.
"""
interface Node {
  """
  The globally unique identifier for the object.
  Node IDs are opaque strings, often base64-encoded.
  Example: "VXNlcjoxMjM=" (base64 of "User:123")
  """
  id: ID!
}
 
# Enable global refetching
type Query {
  """Fetches an object given its global ID."""
  node(id: ID!): Node
  
  """Fetches objects given their global IDs."""
  nodes(ids: [ID!]!): [Node]!
}
 
# All types implement Node for consistent ID handling
type User implements Node {
  id: ID!
  # ...
}
 
type Post implements Node {
  id: ID!
  # ...
}
 
# ============================================
# INTERFACE INHERITANCE PATTERNS
# ============================================
 
interface Error {
  message: String!
  code: ErrorCode!
}
 
interface FieldError implements Error {
  message: String!
  code: ErrorCode!
  field: String!           # Additional field
  path: [String!]!         # Path to the field
}
 
type ValidationError implements FieldError & Error {
  message: String!
  code: ErrorCode!
  field: String!
  path: [String!]!
  constraint: String!      # Type-specific field
}
 
type AuthorizationError implements Error {
  message: String!
  code: ErrorCode!
  requiredPermission: Permission!
}
 
# ============================================
# UNION TYPES FOR HETEROGENEOUS RESULTS
# ============================================
 
union SearchResult = User | Post | Comment | Tag | Category
 
type Query {
  search(query: String!, types: [SearchType!]): [SearchResult!]!
}
 
# Querying unions requires inline fragments
query Search($query: String!) {
  search(query: $query) {
    # No common fields - must use fragments
    ... on User {
      id
      name
      avatarUrl
    }
    ... on Post {
      id
      title
      excerpt
      author { name }
    }
    ... on Comment {
      id
      body
      post { title }
    }
  }
}
 
# ============================================
# RESULT TYPES (Union for Success/Error)
# ============================================
 
type CreateUserSuccess {
  user: User!
}
 
type CreateUserError {
  errors: [FieldError!]!
}
 
union CreateUserResult = CreateUserSuccess | CreateUserError
 
type Mutation {
  createUser(input: CreateUserInput!): CreateUserResult!
}
 
# Usage in client
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    ... on CreateUserSuccess {
      user {
        id
        name
      }
    }
    ... on CreateUserError {
      errors {
        field
        message
        code
      }
    }
  }
}
 
# ============================================
# TYPE CONDITIONS WITH __typename
# ============================================
 
# Every object type has an implicit __typename field
query GetFeedWithTypes {
  feed(first: 10) {
    edges {
      node {
        __typename   # Returns "Post", "Photo", "Article", etc.
        ... on Post {
          title
          content
        }
        ... on Photo {
          imageUrl
          caption
        }
      }
    }
  }
}
 
# Clients use __typename for:
# 1. Runtime type discrimination
# 2. Cache normalization (Apollo Client's default key)
# 3. Fragment matching logic

The Payload Pattern

Custom Scalars: Encoding Domain Constraints

When to Create Custom Scalars:

Validation: Email, URL, UUID, phone numbers
Formatting: DateTime, Currency, Percentage
Range Constraints: PositiveInt, Latitude, Longitude
Complex Types: JSON, BigInt, Decimal

Custom Scalar Contract:

A custom scalar must define three functions:

serialize(value): Convert internal value to JSON output
parseValue(value): Convert JSON input to internal value
parseLiteral(ast): Convert query literal to internal value

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
import { GraphQLScalarType, Kind, GraphQLError } from 'graphql';
 
// ============================================
// DATETIME SCALAR
// ============================================
 
export const DateTimeScalar = new GraphQLScalarType({
  name: 'DateTime',
  description: 'ISO-8601 formatted date-time string',
  
  // Called when sending data to client
  serialize(value: unknown): string {
    if (value instanceof Date) {
      return value.toISOString();
    }
    if (typeof value === 'string') {
      return new Date(value).toISOString();
    }
    throw new GraphQLError('DateTime cannot serialize non-date value');
  },
  
  // Called when parsing variable values from JSON
  parseValue(value: unknown): Date {
    if (typeof value !== 'string') {
      throw new GraphQLError('DateTime must be a string');
    }
    const date = new Date(value);
    if (isNaN(date.getTime())) {
      throw new GraphQLError('DateTime invalid format');
    }
    return date;
  },
  
  // Called when parsing literal values in the query
  parseLiteral(ast): Date {
    if (ast.kind !== Kind.STRING) {
      throw new GraphQLError('DateTime must be a string');
    }
    const date = new Date(ast.value);
    if (isNaN(date.getTime())) {
      throw new GraphQLError('DateTime invalid format');
    }
    return date;
  },
});
 
// ============================================
// EMAIL SCALAR WITH VALIDATION
// ============================================
 
const EMAIL_REGEX = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
 
export const EmailScalar = new GraphQLScalarType({
  name: 'Email',
  description: 'Validated email address',
  
  serialize(value: unknown): string {
    if (typeof value !== 'string') {
      throw new GraphQLError('Email must be a string');
    }
    return value.toLowerCase();
  },
  
  parseValue(value: unknown): string {
    if (typeof value !== 'string') {
      throw new GraphQLError('Email must be a string');
    }
    const email = value.toLowerCase().trim();
    if (!EMAIL_REGEX.test(email)) {
      throw new GraphQLError(`Invalid email format: ${value}`);
    }
    return email;
  },
  
  parseLiteral(ast): string {
    if (ast.kind !== Kind.STRING) {
      throw new GraphQLError('Email must be a string');
    }
    const email = ast.value.toLowerCase().trim();
    if (!EMAIL_REGEX.test(email)) {
      throw new GraphQLError(`Invalid email format: ${ast.value}`);
    }
    return email;
  },
});
 
// ============================================
// POSITIVE INT SCALAR
// ============================================
 
export const PositiveIntScalar = new GraphQLScalarType({
  name: 'PositiveInt',
  description: 'Positive integer (greater than 0)',
  
  serialize(value: unknown): number {
    if (typeof value !== 'number' || !Number.isInteger(value)) {
      throw new GraphQLError('PositiveInt must be an integer');
    }
    if (value <= 0) {
      throw new GraphQLError('PositiveInt must be positive');
    }
    return value;
  },
  
  parseValue(value: unknown): number {
    if (typeof value !== 'number' || !Number.isInteger(value)) {
      throw new GraphQLError('PositiveInt must be an integer');
    }
    if (value <= 0) {
      throw new GraphQLError('PositiveInt must be positive');
    }
    return value;
  },
  
  parseLiteral(ast): number {
    if (ast.kind !== Kind.INT) {
      throw new GraphQLError('PositiveInt must be an integer');
    }
    const value = parseInt(ast.value, 10);
    if (value <= 0) {
      throw new GraphQLError('PositiveInt must be positive');
    }
    return value;
  },
});
 
// ============================================
// JSON SCALAR (Escape Hatch)
// ============================================
 
export const JSONScalar = new GraphQLScalarType({
  name: 'JSON',
  description: 'Arbitrary JSON value. Use sparingly - prefer typed fields.',
  
  serialize(value: unknown): unknown {
    return value; // Pass through
  },
  
  parseValue(value: unknown): unknown {
    return value; // Accept any valid JSON
  },
  
  parseLiteral(ast, variables): unknown {
    switch (ast.kind) {
      case Kind.STRING:
      case Kind.BOOLEAN:
        return ast.value;
      case Kind.INT:
      case Kind.FLOAT:
        return parseFloat(ast.value);
      case Kind.OBJECT:
        return parseObjectLiteral(ast, variables);
      case Kind.LIST:
        return ast.values.map(v => parseLiteral(v, variables));
      case Kind.NULL:
        return null;
      case Kind.VARIABLE:
        return variables?.[ast.name.value];
      default:
        throw new GraphQLError('Unsupported literal kind');
    }
  },
});

Avoid the JSON Escape Hatch

The Directive System

Directives are annotations that modify schema behavior or query execution. They're GraphQL's extension mechanism for cross-cutting concerns.

Built-in Directives:

@deprecated(reason: String) — Mark fields/enum values as deprecated
@skip(if: Boolean!) — Conditionally skip field in query
@include(if: Boolean!) — Conditionally include field in query
@specifiedBy(url: String!) — Link scalar specification (added in GraphQL 2021)

Custom Directive Categories:

Schema Directives: Transform schema at build time (e.g., @auth, @cache)
Executable Directives: Modify query execution (e.g., @defer, @stream)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
# ============================================
# BUILT-IN DIRECTIVES
# ============================================
 
type User {
  id: ID!
  username: String!
  
  # Deprecation with migration guidance
  email: String! @deprecated(reason: "Use emailAddress instead")
  emailAddress: Email!
}
 
enum UserStatus {
  ACTIVE
  INACTIVE @deprecated(reason: "Use DEACTIVATED instead")
  DEACTIVATED
  SUSPENDED
}
 
# Conditional fields in queries
query GetUser($userId: ID!, $includeEmail: Boolean!, $skipPosts: Boolean!) {
  user(id: $userId) {
    id
    name
    email @include(if: $includeEmail)
    posts @skip(if: $skipPosts) {
      title
    }
  }
}
 
# ============================================
# CUSTOM SCHEMA DIRECTIVES
# ============================================
 
# Define the directive
directive @auth(
  requires: Role = USER
) on OBJECT | FIELD_DEFINITION
 
directive @cacheControl(
  maxAge: Int!
  scope: CacheScope = PUBLIC
) on OBJECT | FIELD_DEFINITION
 
directive @deprecated(
  reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
 
directive @rateLimit(
  limit: Int!
  window: Int!  # seconds
) on FIELD_DEFINITION
 
enum Role {
  ADMIN
  MODERATOR
  USER
  GUEST
}
 
enum CacheScope {
  PUBLIC
  PRIVATE
}
 
# Apply directives to schema
type Query {
  # Public, cacheable
  publicPosts: [Post!]!
    @cacheControl(maxAge: 300, scope: PUBLIC)
  
  # Requires authentication
  me: User!
    @auth(requires: USER)
    @cacheControl(maxAge: 60, scope: PRIVATE)
  
  # Admin only, rate limited
  adminStats: AdminStats!
    @auth(requires: ADMIN)
    @rateLimit(limit: 10, window: 60)
}
 
type User @auth(requires: USER) {
  id: ID!
  name: String!
  email: Email! @auth(requires: ADMIN)  # Only admins see email
  posts: [Post!]!
}
 
# ============================================
# CUSTOM EXECUTABLE DIRECTIVES
# ============================================
 
# @defer and @stream (pending GraphQL spec additions)
directive @defer(
  label: String
  if: Boolean! = true
) on FRAGMENT_SPREAD | INLINE_FRAGMENT
 
directive @stream(
  label: String
  initialCount: Int! = 0
  if: Boolean! = true
) on FIELD
 
# Usage: Defer expensive computations
query GetUserProfile($userId: ID!) {
  user(id: $userId) {
    id
    name
    avatarUrl
    
    # Defer expensive recommendation computation
    ... @defer(label: "recommendations") {
      recommendedPosts {
        id
        title
      }
    }
    
    # Stream large lists
    notifications @stream(initialCount: 5) {
      id
      message
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
import { mapSchema, getDirective, MapperKind } from '@graphql-tools/utils';
import { GraphQLSchema, defaultFieldResolver, GraphQLError } from 'graphql';
 
// ============================================
// AUTH DIRECTIVE IMPLEMENTATION
// ============================================
 
interface AuthDirectiveArgs {
  requires: 'ADMIN' | 'MODERATOR' | 'USER' | 'GUEST';
}
 
export function authDirective(directiveName: string) {
  const roleHierarchy = {
    GUEST: 0,
    USER: 1,
    MODERATOR: 2,
    ADMIN: 3,
  };
  
  return {
    authDirectiveTypeDefs: `
      directive @${directiveName}(requires: Role = USER) on OBJECT | FIELD_DEFINITION
      enum Role { ADMIN MODERATOR USER GUEST }
    `,
    
    authDirectiveTransformer: (schema: GraphQLSchema) =>
      mapSchema(schema, {
        [MapperKind.OBJECT_FIELD]: (fieldConfig, _fieldName, typeName) => {
          // Check for directive on field or parent type
          const fieldDirective = getDirective(schema, fieldConfig, directiveName)?.[0];
          const typeConfig = schema.getType(typeName);
          const typeDirective = typeConfig 
            ? getDirective(schema, typeConfig, directiveName)?.[0]
            : null;
          
          const directive = fieldDirective ?? typeDirective;
          
          if (directive) {
            const { requires } = directive as AuthDirectiveArgs;
            const requiredRole = roleHierarchy[requires];
            
            const originalResolver = fieldConfig.resolve ?? defaultFieldResolver;
            
            fieldConfig.resolve = async (source, args, context, info) => {
              const userRole = context.user?.role ?? 'GUEST';
              const userRoleLevel = roleHierarchy[userRole] ?? 0;
              
              if (userRoleLevel < requiredRole) {
                throw new GraphQLError(
                  `Unauthorized: requires ${requires} role`,
                  {
                    extensions: {
                      code: 'UNAUTHORIZED',
                      requiredRole: requires,
                      userRole: userRole,
                    }
                  }
                );
              }
              
              return originalResolver(source, args, context, info);
            };
          }
          
          return fieldConfig;
        },
      }),
  };
}
 
// ============================================
// CACHE CONTROL DIRECTIVE
// ============================================
 
export function cacheControlDirective(directiveName: string) {
  return {
    cacheControlDirectiveTypeDefs: `
      directive @${directiveName}(
        maxAge: Int!
        scope: CacheScope = PUBLIC
      ) on OBJECT | FIELD_DEFINITION
      enum CacheScope { PUBLIC PRIVATE }
    `,
    
    cacheControlDirectiveTransformer: (schema: GraphQLSchema) =>
      mapSchema(schema, {
        [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
          const directive = getDirective(schema, fieldConfig, directiveName)?.[0];
          
          if (directive) {
            const { maxAge, scope } = directive;
            const originalResolver = fieldConfig.resolve ?? defaultFieldResolver;
            
            fieldConfig.resolve = async (source, args, context, info) => {
              // Set cache hints on context for HTTP layer
              context.cacheControl = context.cacheControl ?? { maxAge: 0, scope: 'PUBLIC' };
              
              // Take minimum maxAge across all fields
              context.cacheControl.maxAge = Math.min(
                context.cacheControl.maxAge || Infinity,
                maxAge
              );
              
              // Scope degrades from PUBLIC to PRIVATE
              if (scope === 'PRIVATE') {
                context.cacheControl.scope = 'PRIVATE';
              }
              
              return originalResolver(source, args, context, info);
            };
          }
          
          return fieldConfig;
        },
      }),
  };
}

Directives vs Middleware

Schema Design Principles

A well-designed schema is intuitive, evolvable, and encodes domain knowledge. Here are principles distilled from production GraphQL systems serving billions of requests.

Core Schema Design Principles

•Design for the Domain, Not the Database — Types should represent domain concepts as clients understand them, not as they're stored. A User type might combine users, profiles, and preferences tables.
•Names Are Documentation — Use precise, consistent naming. If something is a list, pluralize. If it's a relationship, name it from the perspective of the parent (user.posts, not user.hasMany).
•Prefer Specific Types Over Generic Ones — Instead of a generic node field returning Node, provide specific fields like user, post. Generic interfaces are for refetching, not primary navigation.
•Use Enums for Fixed Sets — If a field has a limited set of valid values, use an enum. String fields with documented allowed values are a code smell.
•Model State, Not Actions — Fields should represent current state (status: PUBLISHED), not past actions (wasPublished: true). Actions are mutations.
•Flat Is Better Than Nested for Inputs — Deep input nesting makes queries verbose and validation complex. Prefer flat inputs with descriptive field names.
•Use Connections for Lists — Any list that might need pagination should use the connection pattern from day one. Retrofitting pagination is a breaking change.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
# ============================================
# PATTERN: Relay Connection Specification
# ============================================
 
# Standard pagination pattern ensures consistency
type Query {
  posts(
    first: Int
    after: String
    last: Int
    before: String
    filter: PostFilter
  ): PostConnection!
}
 
type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!                  # Total matching, regardless of pagination
}
 
type PostEdge {
  cursor: String!                   # Opaque cursor for this edge
  node: Post!                       # The actual item
}
 
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}
 
# ============================================
# PATTERN: Semantic Naming
# ============================================
 
# ❌ Poor naming
type Query {
  getData(type: String!, id: Int!): JSON
  makeChange(data: JSON!): JSON
}
 
# ✅ Semantic naming
type Query {
  user(id: ID!): User
  users(filter: UserFilter): UserConnection!
  post(id: ID!): Post
  post(slug: String!): Post  # Alternate lookup
}
 
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
  publishPost(id: ID!): PublishPostPayload!
}
 
# ============================================
# PATTERN: Input/Payload Types
# ============================================
 
# Input types group mutation arguments
input CreatePostInput {
  title: String!
  content: String!
  categoryId: ID
  tags: [String!]
}
 
# Payload types provide structured results
type CreatePostPayload {
  post: Post               # The created resource
  userErrors: [UserError!]!  # Validation/business errors
}
 
type UserError {
  field: [String!]         # Path to field with error
  message: String!         # Human-readable message
  code: ErrorCode!         # Machine-readable code
}
 
# ============================================
# PATTERN: Field Arguments for Filtering
# ============================================
 
type User {
  # Avoid: separate fields for each filter combination
  # posts: [Post!]!
  # publishedPosts: [Post!]!
  # draftPosts: [Post!]!
  
  # Prefer: single field with filter arguments
  posts(
    status: PostStatus
    first: Int = 10
    after: String
  ): PostConnection!
}
 
# ============================================
# PATTERN: Avoiding Breaking Changes
# ============================================
 
# Never remove fields - deprecate them
type User {
  email: String! @deprecated(reason: "Use emailAddress for validated email")
  emailAddress: Email!      # New field with proper type
}
 
# Never change non-null to null (or vice versa) on existing fields
# Never change argument types
# Never remove enum values
 
# Safe additions:
# - New nullable fields
# - New nullable arguments with defaults
# - New enum values (unless clients use exhaustive matching)
# - New types

The Deliberate Schema

Schema Evolution and Versioning

The Evolution Philosophy:

No Breaking Changes: Existing queries must continue to work
Deprecation Over Removal: Mark old fields deprecated, don't delete them
Additive Changes Only: New fields, arguments, and types are safe
Sunset with Data: Use analytics to know when deprecated fields are unused

Change Safety Matrix
Change Type	Safety	Notes
Add nullable field	✅ Safe	Clients ignore unknown fields
Add non-null field	✅ Safe	Clients that don't request it are unaffected
Add nullable argument	✅ Safe	Must have default value
Add required argument	❌ Breaking	Existing queries fail
Add enum value	⚠️ Caution	Safe unless clients use exhaustive switch
Remove field	❌ Breaking	Existing queries fail
Rename field	❌ Breaking	Equivalent to remove + add
Change field type	❌ Breaking	Even changing Int to Float breaks
Nullability: null → non-null	❌ Breaking	Clients may now receive errors
Nullability: non-null → null	❌ Breaking	Violates client type expectations

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
# ============================================
# DEPRECATION LIFECYCLE
# ============================================
 
# Phase 1: Add new field alongside old
type User {
  name: String!                       # Original field
  fullName: String!                   # New field with better semantics
}
 
# Phase 2: Deprecate old field with reason
type User {
  name: String! @deprecated(reason: "Use fullName instead - includes proper formatting")
  fullName: String!
}
 
# Phase 3: (After analytics confirm no usage) Consider removal
# Only if you control all clients, or after long deprecation period
 
# ============================================
# FIELD ARGUMENT EVOLUTION
# ============================================
 
# Original field
type Query {
  posts(first: Int, after: String): PostConnection!
}
 
# Safe evolution: add optional argument with default
type Query {
  posts(
    first: Int = 20
    after: String
    orderBy: PostOrder = CREATED_AT_DESC  # New!
    filter: PostFilter                     # New!
  ): PostConnection!
}
 
# ============================================
# TYPE EVOLUTION
# ============================================
 
# Original type
type Post {
  author: User!
}
 
# Need to support multiple authors? Don't change author, add authors
type Post {
  author: User! @deprecated(reason: "Use authors field for multi-author support")
  authors: [User!]!           # New field
  primaryAuthor: User!        # Convenience accessor
}
 
# ============================================
# ENUM EVOLUTION
# ============================================
 
enum PostStatus {
  DRAFT
  PENDING
  PUBLISHED
  ARCHIVED
  SCHEDULED           # Safe to add
  # PENDING_REVIEW  # Would require deprecation cycle if replacing PENDING
}
 
# When adding enum values, document that clients should handle unknown values
# Client code should have a default case:
# switch (status) {
#   case 'DRAFT': ...
#   case 'PUBLISHED': ...
#   default: // Handle future values gracefully
# }
 
# ============================================
# SCHEMA REGISTRY AND VALIDATION
# ============================================
 
# Modern GraphQL tooling validates changes against registered schemas:
# 
# $ graphql schema:push --schema ./schema.graphql
# 
# ❌ BREAKING CHANGE DETECTED
# 
# Field 'User.email' was removed
#   This field is used by 47 operations across 12 clients
#   Last used: 2024-01-15
# 
# To proceed, use --force (not recommended)
# To safe deprecation, use 'graphql field:deprecate User.email "reason"'

When to Consider Versioning

Summary: Schema as Foundation

The schema is GraphQL's crown jewel—a type-safe contract that enables powerful tooling, prevents entire categories of bugs, and guides API evolution. Let's consolidate the key concepts:

Key Takeaways

•The Type System Is the Contract — Every type, field, and argument is enforced at runtime and leveraged by tooling at build time.
•Nullability Is Semantic — Use non-null (!) deliberately to indicate guarantees; remember that errors propagate through non-null chains.
•Interfaces and Unions Enable Polymorphism — Use interfaces for shared structure, unions for heterogeneous results.
•Custom Scalars Encode Domain Constraints — Email, DateTime, URL—encode validation in the type system, not in resolvers.
•Directives Extend Schema Capabilities — Use directives for cross-cutting concerns visible in the schema (auth, caching).
•Design for Evolution — Prefer additive changes, deprecation over removal, and analytics-driven sunset decisions.

What's Next:

Page Complete

2 / 5