SDL - GraphQL Schema Definition Language

3. Schema definition language (SDL)

Overview

To begin putting the pieces of our GraphQL server together, we need to take a closer look at Schema Definition Language, or SDL. This is the syntax that lets us actually define object types and their fields in a way that the GraphQL server can understand.

In this lesson, we will:

Explore SDL syntax
Define a basic schema with a Query and a Playlist type
Add our DGS dependencies

📄 Exploring SDL

You can think of our server's schema as a contract between the server and any client asking for data. It defines what a GraphQL 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.

In practice, a schema is a collection of object types that contain fields. Each field 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. We'll see an example of this shortly.

GraphQL type syntax

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 fields:

Example GraphQL type

type Artist {

}

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

type Artist {
  id: ID
  name: String
  birthYear: Int
  albumNames: [String]
}

Take a closer look at the albumNames field; it returns a list of String types.

albumNames: [String]

This representation lets us envision the shape the underlying albumNames data might take:

{
  "albumNames": [
    "GraphQL: Top Hits of the 00s",
    "The Full-Stack Discography",
    "Get up and Graph! Groovy Hits from the 1970s"
  ]
}

In a future iteration of the schema, we might decide to break out each album title into its own Album type, which would let us describe album data in greater detail. For now, this simple example is intended to illustrate the purpose of the GraphQL list syntax.

Nullability in GraphQL

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:

type Artist {
  id: ID!
  name: String!
  birthYear: Int
  albumNames: [String]
}

This syntax states that it's not valid for an Artist to return null for the id or name fields; we require them to return a value that matches their specified data type. By contrast, we'll permit birthYear and albumNames to be null if we have no data to return.

One approach is to make the schema reflect our "business" domain rules.

type Artist {
  id: ID! # REQUIRED!
  name: String! # REQUIRED!
  birthYear: Int
  albumNames: [String]
}

Considering the Artist type above, we'd find it difficult to work with this data if we lacked an artist's unique identifier (the id field) or name. Allowing either of those fields to return null doesn't make sense from our "business" point of view.

We might not feel as strongly about albumNames or birthYear, however: after all, the artist might not have any published albums yet, and some artists might prefer not to disclose their age!

Working with multiple object types

The initial schema we define isn't rigid, or locked in place—GraphQL gives us the flexibility to add more types and fields as time goes on, further enhancing the data capabilities of our API. Take these two object types for example:

type Artist {
  id: ID!
  name: String!
  birthYear: Int
}

type RecordLabel {
  id: ID!
  name: String!
  yearFounded: Int
}

Suppose we want to represent an artist as belonging to a particular record label. How do we represent this in GraphQL?

In this case, we'd update Artist with a field that returns another object type; one that specifies which record label it belongs to.

type Artist {
  id: ID!
  name: String!
  birthYear: Int
  signedTo: RecordLabel
}

type RecordLabel {
  id: ID!
  name: String!
  yearFounded: Int
}

This relationship lets us query details about an artist, then query further details about the record label they're signed to. We can ask more complex questions of our data—like "When were each of these artists born, and what are the names of the record labels they're each signed to?"—and get all of the answers in one neatly-bundled response.

Documenting the schema

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

It's good practice to document 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 SDL lets you add descriptions to both types and fields 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
"""

Here's what a fully-documented GraphQL type might look like.

"Catalog information for a single artist."
type Artist {
  "The ID for the artist"
  id: ID!
  "The artist's name"
  name: String!
  "The year (YYYY format) the artist was born"
  birthYear: Int
  "The particular record label the artist is signed with"
  signedTo: RecordLabel
}

With that final point covered, let's build our schema!

Adding schema dependencies

To get started with our schema, we'll need to bring in our DGS dependencies. Fortunately, DGS provides us with a couple helpful starter packages that we can integrate seamlessly with our empty Spring Boot project:

implementation("com.netflix.graphql.dgs:graphql-dgs-spring-boot-starter")
implementation(platform("com.netflix.graphql.dgs:graphql-dgs-platform-dependencies:7.6.0"))

Open up the build.gradle.kts file in the root of your project, and copy these lines into dependencies.

build.gradle.kts

dependencies {
  implementation("org.springframework.boot:spring-boot-starter-web")
  implementation("org.springframework.boot:spring-boot-starter-webflux")
  implementation("com.netflix.graphql.dgs:graphql-dgs-spring-boot-starter")
  implementation(platform("com.netflix.graphql.dgs:graphql-dgs-platform-dependencies:7.6.0"))
  testImplementation("org.springframework.boot:spring-boot-starter-test")
}

These packages are responsible for all of the GraphQL wiring we'll need to get our project up and running. DGS automatically scours our project for schema files (specifically, by looking in the project's src/main/resources/schema folder, which we are about to create), along with certain annotations and functions that we'll define shortly.

But before it can do anything for us, we actually need to define a schema!

Building the schema

Let's navigate to the resources package, in src/main. In there, we're going to create a new schema directory to house our schema file, which we'll define next.

📂 src
 ┣ 📂 main
 ┃ ┣ 📂 java
 ┃ ┣ 📂 resources
 ┃ ┃ ┃ ┣ 📂 schema
 ┃ ┃ ┃ ┣ 📄 application.properties

Right-click on the schema folder, and add a new file called schema.graphqls.

When working with DGS (as well as other tools, such as Kotlin), we denote our schema files with the .graphqls extension, rather than .graphql (note the lack of an 's'!). This convention allows us to differentiate between GraphQL schema files (those that contain Schema Definition Language syntax) and files that contain actual GraphQL operations that will be run to fetch or change data.

To understand the difference right now, you can think of the schema.graphqls file as the "menu" of all the things we can ask our API for, whereas a file with the .graphql extension would contain the specific order for something from that menu. We'll see how to build these operations shortly!

✏️ Let's define that schema

Referring back to our mockup, we identified that we need some data for each playlist.

Zoomed in on a single Playlist object, identifying its properties

For this course, we're going to skip the playlist image and tackle a pared-down version of the mockup. So let's focus on these two basic fields:

name
description

We'll also need a field that we can use to differentiate one playlist from another—we'll give this field the name id.

With our three fields of id, name, and description, let's bring the Playlist type to life!

The `Playlist` type

Let's define the Playlist type in our schema.graphqls file and add a description right away.

schema.graphqls

"A curated collection of tracks designed for a specific activity or mood."
type Playlist {
  # Fields go here
}

Now for the playlist's fields, we'll have:

id of type ID!
name of type String!
description of type String

So we should end up with a Playlist type that looks like this:

"A curated collection of tracks designed for a specific activity or mood."
type Playlist {
  "The ID for the playlist."
  id: ID!
  "The name of the playlist."
  name: String!
  "Describes the playlist, what to expect and entices the user to listen."
  description: String
}

The Playlist type is complete for now, but we need a way to actually ask for playlist data from our GraphQL server. For that, we have a separate Query type.

The `Query` type

The Query type is defined like any other object type:

type Query {
  # Fields go here
}

The fields of this type are entry points into the rest of our schema. These are the top-level fields that our client can query for.

For now, we're only interested in fetching the list of featured playlists for our homepage. Let's name the field featuredPlaylists to make it as descriptive as possible. We want this field to return a list of Playlists. We'll also add a nice description:

type Query {
  "Playlists hand-picked to be featured to all users."
  featuredPlaylists: [Playlist!]!
}

Not to worry—those exclamation points can be tricky. A good tip is to start from the outside and move your way in.

The outermost exclamation point (!) applies to the array ([]) itself. This means that the array can be empty—it just CAN'T be null. The featured playlists list might contain zero playlists, so this syntax states that at the very least we should return an empty array, or list, to stand in for featuredPlaylists.

Next, inside of the square brackets ([]), we'll see another exclamation point (!) applied to the Playlist type. This bit of syntax specifies that the list returned should either contain objects that adhere to the Playlist GraphQL type structure, or it should be empty. In other words, an array like [1,2,3] or [null, null] is not allowed!

Our schema is now fully defined to support our first feature!

type Query {
  "Playlists hand-picked to be featured to all users."
  featuredPlaylists: [Playlist!]!
}
"A curated collection of tracks designed for a specific activity or mood."
type Playlist {
  "The ID for the playlist."
  id: ID!
  "The name of the playlist."
  name: String!
  "Describes the playlist, what to expect and entices the user to listen."
  description: String
}

Practice

Which of the following are valid field types?

IntString![Int]String

What does an exclamation mark after a field's type indicate?

The field's value can't be null.The field's value can be null.The field is a scalar type.The field has a default value.

Which of these are always true about the Query type?

It contains a field for every other schema type.Its fields cannot be null.It defines entry points into our schema.It defines what data clients can query in our schema.

Key takeaways

The fields of the Query type are entry points into our schema. These are the top-level fields that a GraphQL consumer can query for.
GraphQL object types define fields we can query for data. These fields can return scalar data (such as String or Int) or return other object types.
With just a few dependencies, DGS automatically searches for a schema.graphqls file housed in a directory called schema.

Up next

Now that our base schema is ready, we can start working on the next piece of our API—writing the functions that actually return some data. In the next lesson, we'll write our first datafetcher.

Share your questions and comments about this lesson

This course is currently in

beta

. 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.