SDL stands for Schema Definition Language — the human-readable syntax used to define a GraphQL schema. It describes types, fields, enums, scalars, interfaces, unions, inputs, and directives. SDL is language-agnostic and is the standard way to document and share GraphQL schemas.

GraphQL Schema – SDL Reference, Types, Enums & Schema-First vs Code-First

Q: What is a GraphQL schema?

A GraphQL schema defines the structure of a GraphQL API — what types exist, what fields they expose, and what operations (queries, mutations, subscriptions) clients can perform. It is written in SDL (Schema Definition Language) and acts as the contract between client and server.

Q: What is the difference between schema-first and code-first GraphQL?

Schema-first means writing the SDL schema definition before writing any resolver code. Code-first means defining the schema programmatically using code (TypeScript classes, decorators, etc.) and generating the SDL from it. Schema-first is better for API design collaboration; code-first is better for type-safe codebases where the schema should mirror existing types.

GraphQL Scalar Types Reference

Built-in scalar types available in every GraphQL implementation, plus common custom scalars used in production schemas.

Scalar	GraphQL Type	Serializes As	Use Case	Kind
Int	Int	32-bit signed integer	Counts, IDs, numeric values	Built-in
Float	Float	Double-precision decimal	Prices, coordinates, ratios	Built-in
String	String	UTF-8 string	Names, descriptions, text	Built-in
Boolean	Boolean	true / false	Flags, toggles, active states	Built-in
ID	ID	String (serialized)	Unique identifiers, primary keys	Special
Date	scalar Date	ISO 8601 string	Dates without time	Custom
DateTime	scalar DateTime	ISO 8601 datetime string	Timestamps, created/updated at	Custom
JSON	scalar JSON	Any JSON value	Unstructured data, metadata blobs	Custom
URL	scalar URL	String (validated URL)	Links, image URLs, endpoints	Custom
Email	scalar Email	String (validated email)	User email fields	Custom
UUID	scalar UUID	String (UUID format)	Globally unique record IDs	Custom
Upload	scalar Upload	Multipart form data	File upload mutations	Custom
BigInt	scalar BigInt	String (large integer)	64-bit IDs, financial amounts	Custom

Non-null and List modifiers

Every scalar (and type) can be wrapped in two modifiers: ! for non-null (required) and [] for lists. They can be combined:

Syntax	Meaning	Example value
String	Nullable string	`"hello" \| null`
String!	Required string	`"hello"`
[String]	Nullable list of nullable strings	`["a", null] \| null`
[String!]	Nullable list of required strings	`["a", "b"] \| null`
[String!]!	Required list of required strings	`["a", "b"]`
[String]!	Required list of nullable strings	`["a", null]`

Schema-First vs Code-First GraphQL

Two fundamentally different approaches to defining a GraphQL schema. The choice affects your workflow, tooling, type safety, and team collaboration model.

Schema-First (SDL-First)

Write SDL (.graphql file) first, then implement resolvers to match
Schema acts as the API contract — clients, backend, and frontend can work in parallel
SDL is language-agnostic — works the same in Node, Java, Python, Go
Best for API-first teams and design reviews before implementation
Supported natively by Apollo Server, GraphQL Yoga, graphql-java
Risk of schema and resolver code drifting out of sync
Requires manual or generated TypeScript types from SDL
Duplication: type defined twice (SDL + resolver types)

Code-First (Programmatic)

Define schema using TypeScript classes, decorators, or builder APIs
Single source of truth — schema derived from code, no drift possible
Full IDE autocomplete and type safety from day one
Best for TypeScript codebases (TypeGraphQL, Nexus, Pothos)
Refactoring is safer — rename a class field, schema updates automatically
SDL output is generated, harder to read and review in PRs
Less portable — tightly coupled to the framework or library used
Steeper learning curve for teams new to the decorator pattern

Choose Schema-First when:

You have multiple teams consuming the API, you want to design the API contract before writing code, your team uses multiple languages, or you're using Apollo Studio / schema registry workflows.

Choose Code-First when:

Your entire stack is TypeScript, you want maximum type safety, you're building a complex schema with lots of shared types, or you want to avoid SDL duplication in a rapid development environment.

Popular libraries by approach

Library	Approach	Language	Notes
Apollo Server	Schema-first	Node.js	Industry standard, typeDefs + resolvers pattern
GraphQL Yoga	Schema-first	Node.js	Lightweight alternative to Apollo Server
TypeGraphQL	Code-first	TypeScript	Decorator-based, mirrors NestJS patterns
Pothos	Code-first	TypeScript	Plugin-based, no decorators, fully type-safe
Nexus	Code-first	TypeScript	Prisma-friendly, generates SDL from code
graphql-java	Both	Java	Schema-first via SDL files or runtime wiring
Strawberry	Code-first	Python	Dataclass + decorator approach
Hot Chocolate	Code-first	.NET / C#	Annotations and fluent builder API
AWS AppSync	Schema-first	SDL + VTL	Managed GraphQL with resolver mapping templates

GraphQL Schema Design Guide

Practical rules for designing production-ready GraphQL schemas that scale with your API.

The schema as a contract

A GraphQL schema is the contract between your server and every client that consumes it. Once a field is published in a schema, removing or renaming it is a breaking change. Design schemas with this permanence in mind — add fields liberally, remove them carefully, and use deprecation (@deprecated) before removal.

Naming conventions

GraphQL schemas follow consistent naming conventions across the ecosystem: types use PascalCase (UserProfile), fields and arguments use camelCase (createdAt), enum values use SCREAMING_SNAKE_CASE (ACTIVE_USER). Mutations use verb-noun naming: createUser, updatePost, deleteComment.

Nullability strategy

A key schema design decision is when to use non-null (!). The GraphQL spec allows nullable by default. A common production pattern is to make fields nullable unless you are certain the resolver will always return a value — this prevents schema errors from propagating into client null-pointer exceptions. Input arguments required for mutation should always be non-null.

Pagination patterns

Lists in GraphQL schemas should almost never be plain arrays. Use the Relay Connection pattern (UserConnection, UserEdge, PageInfo) for cursor-based pagination, or add limit and offset arguments for offset pagination. Never expose unlimited list fields in production — they become performance liabilities as data grows.

Schema versioning and evolution

GraphQL schemas evolve without version numbers (unlike REST /v1, /v2). Add new fields instead of modifying existing ones. Mark old fields with @deprecated(reason: "Use newField instead"). Monitor field usage in Apollo Studio or similar tools before removing deprecated fields. This allows continuous schema evolution without breaking existing clients.

GraphQL Schema – FAQ

What is a GraphQL schema?+

A GraphQL schema defines the complete structure of a GraphQL API. It specifies every type, field, query, mutation, subscription, enum, and directive that clients can interact with. Written in SDL (Schema Definition Language), the schema acts as the contract between the server and all clients. No query can request a field that isn't defined in the schema.

What is GraphQL SDL?+

SDL stands for Schema Definition Language — the human-readable, language-agnostic syntax used to define GraphQL schemas. It uses keywords like type, enum, interface, union, input, scalar, and directive. SDL files use the .graphql extension. Every major GraphQL server (Apollo Server, GraphQL Yoga, graphql-java, AWS AppSync) accepts SDL as input.

What is the difference between Query, Mutation, and Subscription in a GraphQL schema?+

Query is for read operations — fetching data without side effects. Mutation is for write operations — creating, updating, or deleting data. Subscription is for real-time operations — the client receives data pushed from the server when specific events occur. All three are special root types in the schema. Query is always required; Mutation and Subscription are optional.

What is the difference between Interface and Union in GraphQL?+

Interface defines a set of fields that implementing types must include — like a contract for shared fields. Union is a type that can be one of several object types but shares no common fields. Use Interface when types share fields (e.g. all Node types have an id). Use Union when types are completely different but can appear in the same list (e.g. SearchResult can be User, Post, or Product).

What is the difference between schema-first and code-first GraphQL?+

Schema-first means writing the SDL schema definition first, then implementing resolvers. Code-first means generating the SDL from code using TypeScript classes, decorators, or a builder API. Schema-first is better for API design collaboration across teams. Code-first is better for TypeScript codebases where you want type safety and a single source of truth. Popular schema-first tools: Apollo Server, GraphQL Yoga. Popular code-first tools: TypeGraphQL, Pothos, Nexus.

How do I add a custom scalar to a GraphQL schema?+

Declare the scalar in SDL with "scalar DateTime", then implement it in your server code. In Apollo Server, pass a scalar resolver object with serialize (server to client), parseValue (client variable to server), and parseLiteral (inline literal to server) methods. For common scalars like DateTime, Date, JSON, and UUID, use the graphql-scalars npm package which provides production-ready implementations.

GraphQL Schema
SDL Reference & Type Explorer

GraphQL Schema SDL Explorer - graphql schema tools