GraphQL Schema

In REST, the API contract is often implicit. Documented in Swagger/OpenAPI if you are lucky, in someone's head if you are not. The server returns whatever JSON it wants. The client parses it and hopes the fields are there. A renamed field breaks mobile apps in production with no compile-time warning.

GraphQL flips this. The schema IS the API. Every type, every field, every argument, every relationship is explicitly defined in a typed schema. The server must implement what the schema declares. The client can only query what the schema allows. Both sides have a single source of truth.

The schema is written in SDL (Schema Definition Language), a clean, readable syntax that serves simultaneously as documentation, validation rules, and code generation input. Change the schema, and your IDE, your tests, and your generated types all update automatically. GitHub's GraphQL API has over 200 types in its schema. Shopify's has over 400. The schema is how teams of hundreds of engineers stay in sync.

Scalar types: String, Int, Float, Boolean, ID (plus custom scalars like DateTime, URL, JSON)

Object types:

type Product {
 id: ID! # ! means non-null
 name: String!
 price: Float!
 description: String # nullable (no !)
 category: Category!
 reviews: [Review!]! # non-null list of non-null reviews
}

The ! suffix is the non-null marker. name: String! means the server guarantees it will always return a String for name, never null. [Review!]! means the list itself is non-null AND each item in the list is non-null. Use ! aggressively. Nullable fields should be the exception, not the rule.

Input types (for mutations):

input CreateProductInput {
 name: String!
 price: Float!
 categoryId: ID!
}

type Mutation {
 createProduct(input: CreateProductInput!): Product!
}

Input types are like object types but restricted to scalar fields. They cannot have relationships or resolvers. This prevents circular references in mutation arguments.

Enums:

enum OrderStatus {
 PENDING
 PAID
 SHIPPED
 DELIVERED
 CANCELLED
}

Enums are finite value sets. Type-safe alternatives to magic strings. The schema enforces that only valid values can be used.

Interfaces and unions:

interface Node {
 id: ID!
}

type User implements Node { id: ID!, name: String! }
type Post implements Node { id: ID!, title: String! }

union SearchResult = User | Post | Product

Interfaces define shared fields. Unions represent "one of" types. Both enable polymorphic queries: a search endpoint can return a mix of Users, Posts, and Products, and the client handles each type differently.