The GraphQL Schema

The schema is the heart of any GraphQL API: written in Schema Definition Language (SDL), it declares every object type, field, argument, and operation the API supports, and serves as a strongly-typed contract that both client and server agree to. Because the schema is introspectable, tools like GraphiQL, Apollo Studio, and GraphQL Code Generator can read it at runtime or build-time to power autocomplete, documentation, and even generate typed client code, which is a level of tooling REST's looser, often out-of-band documentation can't always guarantee stays accurate.

Object types in SDL are declared with the type keyword and list their fields along with each field's type, such as type Book { title: String, pages: Int, author: Author }. Two modifiers change a field's nullability and cardinality: an exclamation mark makes a type non-null, meaning the server guarantees a value will always be present (String! can never return null), and square brackets denote a list, so [String!]! is a non-null list of non-null strings. Scalar types like String, Int, Float, Boolean, and ID form the leaves of the graph, while object types like Author or Book let fields reference other types, building the graph structure that gives GraphQL its name.

Every GraphQL schema defines up to three root operation types: Query, which exposes all the read operations clients can perform and must be present in every schema; Mutation, which exposes operations that create, update, or delete data and, by convention, returns the modified object so the client can immediately see the result; and Subscription, which exposes long-lived operations that push real-time updates to clients over a protocol like WebSockets, useful for features like live chat messages or live sports scores. Each root type's fields work exactly like any other object type's fields — they can take arguments and return scalars or object types — but they are special in that they represent the actual entry points into the graph.

Schema-first development means writing the SDL file by hand first, treating it as the definitive contract, and then implementing resolver functions that satisfy each field — this keeps the schema readable and reviewable independent of any programming language, and tools like GraphQL Code Generator can produce typed client and server code from it. Code-first development inverts the order: developers write ordinary code (TypeScript classes with decorators in TypeGraphQL, or JavaScript objects in Nexus) and the schema is generated automatically from that code at build or runtime, which keeps the schema and the implementation from drifting apart since they're the same source, at the cost of the SDL no longer being a hand-authored, human-first artifact.