type Query { me: User users(first: Int = 20, after: String): UserConnection! product(id: ID!): Product}
3. Defining Root Mutation Type
Rule
Detail
Optional
Only required if writes are exposed
Sequential
Top-level fields execute serially (spec)
Naming
Verb-noun: createUser, updatePost
Payload
Return a payload type for extensibility
Example: Mutation with payload
type Mutation { createUser(input: CreateUserInput!): CreateUserPayload!}type CreateUserPayload { user: User errors: [UserError!]!}
4. Defining Root Subscription Type
Rule
Detail
Transport
WebSocket (graphql-ws) or SSE
Single field
Operation must select exactly one root field
Resolver
Returns AsyncIterator of events
Example: Subscription
type Subscription { messageAdded(channelId: ID!): Message!}
5. Using Schema Description Strings
Syntax
Use
"single line"
Short description above type/field
"""block"""
Multi-line, supports markdown
Available on
types, fields, args, enum values, directives
Example: Descriptions
"""A registered customer of the platform."""type User { "Globally unique identifier" id: ID! """ Display name. **May be null** for anonymous users. """ name: String}
6. Organizing Schema Files
Strategy
When
Single file
Small APIs (< 200 lines)
Per type
Medium APIs; one .graphql per domain type
Per domain module
Large APIs; users/, orders/ folders with schema + resolvers
Federation
Schema split across services
Example: Loading multiple SDL files
import { loadFilesSync } from "@graphql-tools/load-files";import { mergeTypeDefs } from "@graphql-tools/merge";const typeDefs = mergeTypeDefs( loadFilesSync("./src/**/*.graphql"));
7. Extending Schema Definitions
Keyword
Use
extend type
Add fields to existing object
extend interface / enum / input
Add members
extend schema
Add directives or root types
Example: Module extends Query
# users/schema.graphqltype Queryextend type Query { me: User user(id: ID!): User}
8. Naming Conventions for Types
Element
Convention
Example
Types/Interfaces/Unions
PascalCase, singular
User, Node
Input types
Suffix Input
CreateUserInput
Payload types
Suffix Payload
LoginPayload
Connections/Edges
Suffix per Relay spec
UserConnection, UserEdge
Enums
PascalCase singular
OrderStatus
9. Naming Conventions for Fields
Element
Convention
Example
Fields/Args
camelCase
firstName, orderBy
Booleans
is/has prefix
isActive, hasAccess
Lists
plural noun
posts, tags
Mutations
verbNoun
createPost, archiveOrder
Enum values
SCREAMING_SNAKE_CASE
IN_PROGRESS
10. Using Comments in Schema
Syntax
Visibility
Use
# comment
Source-only, not in introspection
Implementer notes
"description"
Exposed via introspection
API docs for clients
Warning: Use """...""" for anything clients should see. # comments are stripped from introspection.