4. Building our schema
5m

Overview

With basics in place, it's time to define the Catstronauts schema for our homepage feature. In this lesson, we will:

  • Create a schema.graphql file in the server
  • Define the Track and Author s
  • Add a Query type with a tracksForHome
  • schema types and with descriptions

✏️ Let's define that schema

In the editor, let's navigate to the server/src/ directory. In there, we'll create a file called schema.graphql.

📂 server
 ┗ 📂 src
    ┗ 📄 schema.graphql

Referring back to our mockup, for each learning track, we need the following:

  • Title
  • Thumbnail
  • Length
  • Modules Count
  • Author name
  • Author picture

How do we organize this data into types?

Well, we could create a single type named Track, shove all those into it, and call it a day. But would that make sense from a business domain point of view? Not really. For starters, a single author might create multiple tracks, and that author's information would be needlessly duplicated across multiple locations.

Instead, we need to think in terms of standalone . We'll start with two: Tracks and Authors.

The Track type

We'll start with the type Track that represents a particular learning track. Let's define the type and add a description:

schema.graphql
"Educational modules teaching a specific topic"
type Track {
  # Fields go here
}

Now for the track's , we'll have:

  • id of type ID!
  • title of type String!
  • author of type Author! (we'll define the Author type when we're done with Track)
  • thumbnail of type String (a URL to the image for the track's card)
  • length of type Int
  • modulesCount of type Int

Here's our complete Track type:

schema.graphql
"Educational modules teaching a specific topic"
type Track {
  id: ID!
  title: String!
  author: Author!
  thumbnail: String
  length: Int
  modulesCount: Int
}

Not seeing the nice syntax highlighting you want? Check out the GraphQL: Syntax Highlighting extension for VS Code.

How do we determine which of these should be allowed to be null? One approach is to make the schema reflect our "business" domain rules. In our case, a track could exist without a thumbnail, but a track without a title or author doesn't make any sense from our "business" point of view.

Add some nice descriptions for each of these , then let's move on to the Author type.

The Author type

schema.graphql
"An author of a track or module"
type Author {
  # Fields go here
}

The Author type contains only three :

  • id of type ID!
  • name of type String!
  • photo of type String

Here's the complete type:

schema.graphql
"An author of a track or module"
type Author {
  id: ID!
  name: String!
  photo: String
}

Excellent, our first feature is now fully represented in our schema. These are the data types we'll be able to retrieve.

We're still missing one piece though: how do we return these Track and Author types? We'll need to define a Query type.

The Query type

The Query type is defined like any other :

schema.graphql
type Query {
  # Fields go here
}

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

For now, we're only interested in fetching the track list for our homepage. Let's name that specific tracksForHome to make it as descriptive as possible. We want this to return a non-null list of non-null Tracks. We'll also add a nice description:

schema.graphql
type Query {
  "Fetch a list of tracks for the homepage grid"
  tracksForHome: [Track!]!
}

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

Code review

Practice

What does an exclamation mark after a field's type indicate?
Which of these are always true about the Query type?
Code Challenge!

Define a Query type with a field, popularPlanets, that returns a non-null List of non-null Planet types. Remember to give your field a description!

Loading progress

Up next

Now that our base schema is ready, we can start working on our .

Previous

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.