What is a Schema

An API schema is a formal, machine-readable definition of everything an API can do — the types it exposes, the fields each type has, the operations available, and the parameters they accept. It is the contract between client and server.

How it works

In GraphQL, the schema is written in SDL (Schema Definition Language) and defines types, queries, mutations, and subscriptions. The schema is introspectable — clients can query it to discover available types and fields at runtime, which powers tools like GraphiQL and code generators.

In REST, the schema is typically an OpenAPI (Swagger) document that describes endpoints, request/response bodies, parameters, and authentication requirements. In gRPC, the schema is a .proto file that defines services and message types.

Why it matters

A schema is the single source of truth for an API. With a schema, you can generate client code, validate requests, create documentation, and detect breaking changes automatically. Schema-first APIs (where the schema is written before the implementation) tend to produce cleaner, more consistent designs than code-first APIs where the schema is extracted from existing code.

See How GraphQL Works for how schemas define the query surface of a GraphQL API.