GraphQL Schema

The schema is composed of object types that define the shape of the data. Each object contains fields with specific scalar or complex types. This strict typing acts as a machine-readable contract, allowing tools to validate queries before execution. Key scalar types include:

• String, Int, Float, Boolean, and ID
• Custom scalars like DateTime or JSON for domain-specific precision
• Non-nullable modifiers (!) enforce data integrity at the schema level

Every schema has three special root operation types that serve as the entry points for all client interactions. The Query type defines all read operations, the Mutation type defines write operations that modify server-side data, and the Subscription type establishes persistent, real-time connections. This explicit separation enforces a clear command-query responsibility pattern, preventing side effects during reads.

A GraphQL schema is self-documenting. Clients can query the __schema and __type meta-fields to dynamically discover available types, fields, and directives. This powers development tools like GraphiQL and Apollo Studio, enabling automatic documentation generation and intelligent auto-completion without requiring out-of-band knowledge. The introspection result is a standard JSON structure defined by the specification.

To handle polymorphic data, schemas support Interfaces and Unions. An Interface defines a set of fields that multiple object types must implement, guaranteeing a common shape. A Union represents a type that could be one of several distinct object types with no guaranteed shared fields. Clients use inline fragments (... on Type) to conditionally access fields based on the concrete type at runtime.

Directives provide a mechanism to annotate schema elements with custom metadata or runtime logic. They are declared with the directive @name on LOCATION syntax. While the specification defines standard directives like @deprecated and @skip, custom directives can enforce authorization (@auth), format dates (@date), or mark fields for caching (@cacheControl), extending the schema's declarative power without changing resolver logic.

The schema definition is structural, but the resolver map provides the imperative logic. Each field in the schema is backed by a resolver function that knows how to fetch the data. The execution engine traverses the incoming query tree, calling resolvers in parallel where possible. This strict separation of definition from execution allows the same schema to be implemented across different data sources like databases, REST APIs, or gRPC backends.