3. Schema definition language (SDL)

📄 The GraphQL schema

A schema is like a between the server and the client. It defines what a API can and can't do, and how clients can request or change data. It's an abstraction layer that provides flexibility to consumers while hiding backend implementation details.

Before we jump into defining our schema, let's run through a quick crash course on 's Schema Definition Language, or .

If you're already familiar with , feel free to move to the next lesson.

At its heart, a schema is a collection of object types that contain fields. Each has a type of its own. A field's type can be scalar (such as an Int or a String), or it can be another object type. For example, the Track in our schema will have an author of type Author.

We declare a type using the type keyword, followed by the name of the type (PascalCase is best practice), then opening brackets to hold its contained :

type SpaceCat {
# Fields go here

are declared by their name (camelCase), a colon, and then the type of the field ( or object). A field can also contain a list, indicated by square brackets:

type SpaceCat {
age: Int
missions: [Mission]

Unlike Javascript objects (which look very similar), are not separated by commas. In addition, we can indicate whether each field value is nullable or non-nullable. If a field should never be null, we add an exclamation mark after its type:

A doodle showing the SpaceCat type and its fields: name, age and missions
Which of the following are valid field types?
Code Challenge!

Define a SpaceCat type with the following fields: name of type String (non null), age of type Int, and missions of type List of Mission

Loading progress

All right, last thing before we start writing our schema: descriptions.

It's good practice to your schema, in the same way that it's helpful to comment your code. It makes it easier for your teammates (and future you) to make sense of what's going on. It also allows tools like the Apollo Studio Explorer to guide API consumers on what they can achieve with your API right when and where they need it.

To do that, the lets you add descriptions to both types and by writing strings (in quotation marks) directly above them.

"I'm a regular description"

Triple "double quotes" allow you to add line breaks for clearer formatting of lengthier comments.

I'm a block description
with a line break
A doodle of the SpaceCat type with its description and fields
Code Challenge!

Add a block description for the SpaceCat type (triple "double quotes") and a normal description for the name field.

Loading progress

With that final point covered, we're done with our quick refresher. Let's build our schema!


Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.