GraphQL Schema Vocabulary

The SDL is the schema — every GraphQL API starts with it.

A minimal SDL example:

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  author: User!
}

type Query {
  user(id: ID!): User
  posts: [Post!]!
}

type Mutation {
  createPost(title: String!, authorId: ID!): Post!
}

What SDL defines:
• Object types — the data structures (User, Post)
• Fields — the properties of each type with their types
• The Query type — what clients can read (every root query field is an entry point)
• The Mutation type — what clients can write/change
• The Subscription type — what clients can subscribe to (real-time events)

Why SDL matters:
• It's the contract between your backend team and frontend teams
• Tools generate client code, documentation, and mocks directly from the SDL
• Schema-first development: write the SDL before writing resolvers
• Introspection: clients can query the API to discover its schema at runtime

Key vocabulary:
• SDL (Schema Definition Language) — the text format for defining a GraphQL schema
• Schema-first design — designing the API contract before implementation
• Introspection — the ability to query a GraphQL API to discover its own types and fields

Non-null and list modifiers are the foundation of schema safety in GraphQL — they encode your API's data guarantees.

The four variations:

Type	Meaning	Allowed values
String	Nullable string	"hello", null
String!	Non-null string	"hello" (never null)
[String]	Nullable list of nullable strings	null, [], ["a", null, "b"]
[String!]!	Non-null list of non-null strings	[], ["a", "b"] (list never null, items never null)

Why this matters:
• The non-null guarantee allows clients to skip null checks for ! fields
• Overly nullable schemas force clients to add defensive null-checking everywhere
• If a resolver returns null for a ! field, GraphQL propagates the null up to the nearest nullable parent field — this is called null propagation
• Null propagation can turn a single resolver failure into a partial response — understanding this is critical for error handling design

Best practice: use ! (non-null) for fields your service can always provide. Use nullable for optional, may-not-exist data.

Key vocabulary:
• Non-null modifier — ! in SDL; guarantees the field will never return null
• Null propagation — in GraphQL, a null in a non-null field bubbles up to the nearest nullable ancestor
• Nullable field — a field that may return null (absence of ! in SDL)

Query, Mutation, and Subscription are the three root operation types in GraphQL.

Query:
• Read-only — fetches data without any side effects
• Safe to cache — CDNs and clients can cache query results
• Multiple fields in a Query are resolved in parallel (order not guaranteed)
• Example: query { user(id: "123") { name email } }

Mutation:
• Writes data — creates, updates, or deletes resources
• Side effects are expected — triggering emails, sending messages, updating databases
• Multiple fields in a Mutation are resolved sequentially (order guaranteed by spec)
• Example: mutation { createPost(title: "Hello") { id title } }

Subscription:
• Real-time updates — maintains a persistent WebSocket (or Server-Sent Events) connection
• Server pushes data to the client when a specified event occurs
• Use cases: live chat, real-time dashboards, notifications, collaborative editing
• Example: subscription { orderStatusChanged(orderId: "123") { status updatedAt } }

Key vocabulary:
• Root operation type — Query, Mutation, or Subscription (the entry points to a GraphQL API)
• Side effect — an action beyond data fetching (email, database write, external API call)
• WebSocket — the persistent bi-directional connection protocol typically used for subscriptions
• Real-time push — server-initiated data delivery to clients (vs client polling)

Scalars are the leaf nodes of the GraphQL type system — every field chain must end in a scalar.

Built-in GraphQL scalars:
• Int — 32-bit signed integer
• Float — Double-precision floating point
• String — UTF-8 character sequence
• Boolean — true / false
• ID — unique identifier, serialized as a String (opaque to clients)

When to add a custom scalar:
Custom scalars add domain semantics, validation, and serialization for types the built-ins don't cover.

scalar DateTime    # ISO 8601 timestamp — serialized as string "2025-01-15T14:30:00Z"
scalar URL         # Validates the string is a valid URL
scalar Email       # Validates the string matches email format
scalar JSON        # Arbitrary JSON value
scalar PositiveInt # Integer > 0

Schema using custom scalars:

type Post {
  id: ID!
  title: String!
  createdAt: DateTime!   # Much clearer than String! for timestamps
  authorEmail: Email!
  permalink: URL!
}

Benefits of custom scalars:
• Self-documenting — DateTime is more expressive than String
• Validation at the schema boundary — invalid values rejected before reaching resolvers
• Libraries: graphql-scalars provides common custom scalars (DateTime, UUID, Email, etc.)

Key vocabulary:
• Scalar — a primitive, leaf-level type with no sub-fields
• Custom scalar — a domain-specific scalar with custom serialization/validation logic
• Leaf node — a field that resolves to a scalar (vs an object type that has sub-fields)

Enums and input types both improve schema design quality significantly over plain scalar arguments.

Enum benefits:
• Type safety: the schema enforces only DRAFT, PUBLISHED, or ARCHIVED are valid — typos like "pubished" are rejected at the GraphQL validation layer before reaching resolvers
• Documentation: enums are self-documenting — clients can introspect all valid values
• IDE autocomplete: GraphQL clients suggest enum values in tooling like GraphiQL, Insomnia, or generated code
• Refactoring safety: renaming an enum value shows up as a schema breaking change — clients get clear feedback

Input type benefits:
• Argument grouping: instead of createPost(title: String!, body: String!, status: PostStatus!, tags: [String!]), you get the cleaner createPost(input: CreatePostInput!)
• Reusability: the same input type can be used in multiple mutations (createPost and updatePost)
• Variables: clients can pass a typed variable object instead of inline arguments
• Schema evolution: adding an optional field to an input type (e.g., excerpt: String) is a non-breaking change — existing clients continue to work without sending the new field

Key vocabulary:
• Enum — a scalar type restricted to a defined set of named values
• Input type — an object type used exclusively as a mutation/query argument (cannot be a return type)
• Non-breaking change — a schema change that doesn't break existing clients
• Breaking change — a schema change that removes or renames types/fields existing clients rely on