Understanding GraphQL SDL: A Beginner's Guide

GraphQL SDL (Schema Definition Language) is the syntax used to define the shape of a GraphQL API. If you're new to GraphQL, understanding SDL is the first step to building and consuming GraphQL services.

What is SDL?

SDL stands for Schema Definition Language. It's a human-readable syntax for describing the types, fields, and relationships in a GraphQL API. Think of it as a contract between the client and server: "here's exactly what data is available and what shape it takes."

Basic Building Blocks

Every SDL document is built from types. Here's a simple example:

type User {
  id: ID!
  name: String!
  email: String
  age: Int
  score: Float
  isActive: Boolean
}

This defines a User type with several fields, each with a specific scalar type. The ! means the field is non-nullable — it will always return a value.

Scalar Types

GraphQL has five built-in scalar types:

• ID — A unique identifier (serialized as a string).
• String — UTF-8 text.
• Int — A 32-bit signed integer.
• Float — A double-precision floating-point number.
• Boolean — true or false.

Relationships Between Types

Types can reference other types to create relationships:

type Author {
  id: ID!
  name: String!
  books: [Book!]!
}

type Book {
  id: ID!
  title: String!
  author: Author!
}

Here, Author.books returns a list of Book objects, and Book.author returns the parent Author — creating a bidirectional relationship.

The Root Types

Every GraphQL schema has three special root types. Query is the entry point for read operations:

type Query {
  user(id: ID!): User
  users: [User!]!
  search(query: String!): [User!]!
}

SDL vs JSON: A Direct Comparison

If you have JSON data, you already have most of the information needed to write SDL. Each JSON key becomes a field, each value determines the type. Tools like our JSON to GraphQL Converter automate this mapping so you can go from JSON to SDL in seconds.