Schema and Type System Syntax
A GraphQL schema is written in Schema Definition Language (SDL) using type for object types, ! to mark a field non-nullable, [Type] for lists, interface and union for polymorphism, and enum for a fixed set of values. Every schema must define a Query root type; Mutation and Subscription root types are optional but conventionally used for writes and real-time events respectively.
Cricket analogy: Like the ICC's official playing conditions document defining exactly what a 'wicket' or 'over' means before any match is played, SDL defines the strict type contract before any query executes.
type Book {
id: ID!
title: String!
publishedYear: Int
author: Author!
tags: [String!]!
}
type Author {
id: ID!
name: String!
books: [Book!]!
}
enum SortOrder {
ASC
DESC
}
type Query {
books(sort: SortOrder): [Book!]!
book(id: ID!): Book
}
type Mutation {
addBook(title: String!, authorId: ID!): Book!
}Query, Variable, and Fragment Syntax
Operations are written as query, mutation, or subscription blocks with an optional name, and typed variables declared with $name: Type in parentheses after the operation name, passed separately from the query string at request time. Fragments (fragment Name on Type { ... }) let you reuse a set of fields across multiple queries, and inline fragments (... on TypeName) select type-specific fields when querying through an interface or union.
Cricket analogy: Like a reusable pre-match team-sheet template that every match report references instead of retyping the XI each time, GraphQL fragments let you reuse the same field selection across multiple queries.
fragment BookFields on Book {
id
title
author {
name
}
}
query GetBook($id: ID!) {
book(id: $id) {
...BookFields
publishedYear
}
}Common Directives and Introspection
Built-in directives modify execution at runtime: @include(if: Boolean) includes a field only when the condition is true, @skip(if: Boolean) excludes it, and @deprecated(reason: String) marks a schema field as discouraged without removing it. Every GraphQL server also exposes introspection through the __schema and __type meta-fields, which is how tools like GraphiQL and Apollo Studio auto-generate documentation and autocomplete.
Cricket analogy: Like a broadcast director conditionally cutting to a replay only if a wicket just fell, @include(if:) conditionally includes a field in the response only when its argument is true.
Disable introspection (__schema/__type) in production for sensitive internal APIs if you don't want the full schema shape discoverable by anyone with network access — tools like GraphiQL rely on it being enabled in development.
- SDL uses type, interface, union, enum, and input to define the schema; ! marks non-nullable fields.
- Every schema requires a Query root type; Mutation and Subscription are optional but conventional.
- Variables are declared with $name: Type and passed separately from the query string.
- Fragments (fragment Name on Type) let you reuse field selections across multiple operations.
- Inline fragments (... on TypeName) select type-specific fields on interfaces and unions.
- @include, @skip, and @deprecated are the standard built-in directives for runtime and schema behavior.
- __schema and __type introspection fields power tooling like GraphiQL and Apollo Studio autocomplete.
Practice what you learned
1. What does an exclamation mark (!) after a type mean in GraphQL SDL, e.g. String!?
2. Which root type is required in every valid GraphQL schema?
3. What is the purpose of a GraphQL fragment?
4. What does the @skip(if: Boolean) directive do?
5. What GraphQL meta-fields power tools like GraphiQL's autocomplete and documentation explorer?
Was this page helpful?
You May Also Like
Apollo Client Basics
Learn how Apollo Client manages GraphQL queries, mutations, and the normalized cache in front-end applications.
GraphQL Code Generation
Understand how GraphQL Code Generator produces type-safe TypeScript types, hooks, and resolvers from your schema and operations.
GraphQL Interview Questions
A curated set of common GraphQL interview questions and model answers covering core concepts, performance, and real-world tradeoffs.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics