Schema Definition & Extensions

## Where an operation starts Every GraphQL operation is a selection set that has to be resolved against *some* object type. A client sending `{ seatMap(flightId: "LH1071-2026-03-14") { cabins { rows { seats { number } } } } }` selects fields on a type it never names anywhere in the document. The **schema definition** is the construct that tells the service which type that is. GraphQL recognises three kinds of operation — query, mutation and subscription — and each kind needs its own entry point, called a **root operation type**. The schema definition maps kind to type: ```graphql schema { query: SeatMapQuery mutation: SeatMapMutation subscription: SeatMapSubscription } ``` Those three named types are ordinary object types. There is no special keyword, no marker interface, no separate category in the type system. `SeatMapQuery` is declared exactly the way `Seat` or `Cabin` is, and the only thing that makes it a root is that the schema definition points at it. ## Which roots are required The **query root is mandatory**. A schema without one is invalid — there would be no way to read anything, and the introspection meta-fields hang off the query root. **Mutation and subscription roots are optional.** A read-only seat-map service that exposes no writes and no streams legitimately declares only a query root, and omitting the other two is not laziness; it is the correct way to state that this service has no mutations and no subscriptions. A trap catches people scaffolding a new schema: an object type must declare at least one field. Writing `type Mutation` with an empty body, intending to fill it in next sprint, does not build. Leave the root out until you have a field to put in it. ## Omitting the schema definition The schema definition may be left out altogether. When it is, the roots are located by **name**: a type called `Query` becomes the query root, `Mutation` the mutation root, `Subscription` the subscription root. This is not a community habit that servers happen to share — it is written into the specification's type-system definition language, which is why every implementation behaves identically here. It is also why the large majority of real schemas contain no `schema { ... }` block at all: you only need one when a root carries a different name. ## The half of the rule people forget The defaults apply **only when the schema definition is omitted**. Once the block is written it is the sole authority. Given: ```graphql schema { query: SeatMapQuery } type SeatMapQuery { seatMap(flightId: ID!): SeatMap } type Query { legacySeatMap: SeatMap } ``` `Query` here is an object type like any other. It is not a root, it is not merged into `SeatMapQuery`, and `legacySeatMap` is unreachable unless some field somewhere returns a `Query`. This bites a team that renames its root and leaves the old type behind: the schema still builds, the old type is still visible through introspection, and every request that starts at the old field fails validation with a message about a field that does not exist on `SeatMapQuery`. The type exists; it is simply no longer an entry point. ## Roots are not sealed off Nothing in the type system treats a root as a special case, so nothing stops a root type from being referenced as a field's type elsewhere in the schema. You almost never want that, and it is worth knowing only because it explains why roots must be declared at all: the type system has no way to infer which of the object types is an entry point, so either the block says so or the naming convention does. ## One per schema, extensible afterwards A type system may contain at most one schema definition. When a root has to be added later — a subscription root arriving with a feature written by another team, in another document — the extension form exists precisely for that, and reaching for it is better than editing a definition somebody else owns. The schema definition can itself carry a description and directive applications, which is where a schema-wide annotation goes when a directive is declared to allow that location. ## What this looks like in an interview This is asked early because it separates people who have written SDL from people who have only sent documents. The complete answer is four sentences: three operation kinds, three root object types, query required and the other two optional, and default names by type when the block is omitted — only then. The usual follow-up is the trap above, and the correct response to “what is a type named `Query` in a schema whose block names something else” is simply: nothing special.