Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท The Schema

Schema Definition Language: Types and Scalars

Read and write GraphQL's Schema Definition Language: object types, the five built-in scalars, root types and descriptions, with a runnable SDL parser stand-in.

Every GraphQL API is described by a schema: a contract that lists which types exist, which fields each type has, and what the field types are. The schema is written in the Schema Definition Language (SDL), a small, language-neutral syntax. A Node server, a Python server and a Java server can all load the same SDL text.

Until now you wrote queries against an imagined schema. This lesson is about the other side: reading and writing the schema itself. The real thing is a server library that builds an executable schema from SDL, and that cannot run here, so the SDL blocks are read-only. The runnable example is a stand-in: a tiny parser that turns a few lines of SDL into a map of types. It handles only the subset in this lesson, but it shows what "a schema is data" means.

Object types

The workhorse of SDL is the object type. It has a name and a list of fields, and every field has a type.

GRAPHQL
type Book {
  id: ID!
  title: String!
  pages: Int
  rating: Float
  inPrint: Boolean!
  author: Author!
}

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

Read title: String! as "a field named title whose type is String, and it is never null" (the ! is covered in Lists and Non-Null Types). A field's type can be a scalar, another object type (author: Author!) or a list. Object types can refer to each other in both directions, which is what makes a schema a graph: from a Book you can reach its Author, and from there its other books.

Names follow common conventions: types in PascalCase, fields and arguments in camelCase. Names starting with two underscores (__) are reserved for the introspection system.

The built-in scalars

A scalar is a leaf: a field of scalar type has no sub-selection. GraphQL defines exactly five.

The five built-in scalars

Int A signed 32-bit integer.
Float A double-precision number.
String UTF-8 text.
Boolean true or false.

ID is the fifth.

1 / 2

Details that trip people up:

  • Int is 32-bit. A value like 9007199254740993 does not fit; use a string, a custom scalar (see Input Types, Custom Scalars and Introspection) or Float with care.
  • ID accepts both "42" and 42 as input, but it is always returned as a string. Do not do arithmetic on it.
  • There is no built-in date type. Dates are usually sent as ISO 8601 strings through a custom scalar such as DateTime.

Root operation types

A schema needs an entry point for each operation type from Mutations and Subscriptions. These are root types, ordinary object types whose fields are the top-level fields clients can use.

GRAPHQL
type Query {
  book(id: ID!): Book
  books(limit: Int = 10): [Book!]!
}

type Mutation {
  addBook(title: String!, authorId: ID!): Book!
}

type Subscription {
  bookAdded: Book!
}

By default the names are Query, Mutation and Subscription. Query is required; the other two are optional. If you need different names you can declare them with a schema { query: RootQuery } block, but almost nobody does.

A field can take arguments, written in parentheses with a type and an optional default: books(limit: Int = 10).

Descriptions

Documentation lives inside the schema. A string above a type, field or argument becomes its description. Triple quotes allow several lines, and tools such as GraphiQL show them as hover text.

GRAPHQL
"""
A book that can be borrowed from the library.
"""
type Book {
  "ISBN-13 without dashes, or an internal id for old titles."
  id: ID!

  "Page count. Null for audiobooks."
  pages: Int
}

Write descriptions for everything a newcomer would otherwise have to guess. Unlike code comments (# like this), descriptions are part of the schema and are returned by introspection.

A schema is data: an SDL parser stand-in

A real server turns SDL text into a type map: for each type, its kind and fields, and for each field its type. This stand-in does the same for object types only, using a regular expression. It is deliberately naive (no descriptions, directives, interfaces or multiline fields) and is not a valid GraphQL parser, but the result has the same idea.

JS Parse tiny SDL into a type map

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The output classifies every field as a scalar leaf or an object link. That distinction is exactly what the executor uses when it decides whether a field needs a sub-selection. It is also what validation uses to reject a query such as book(id: "1") { title { length } } ("title is a scalar and must not have a selection") or book(id: "1") with no selection at all.

Try changing author: Author! to author: Writer!. The "Unknown types" count becomes 1, which mirrors the error a real server prints when the schema mentions a type that was never defined.

Where the SDL lives

In practice the schema is either schema-first (you write .graphql files and attach resolvers, covered in Resolvers) or code-first (you build the types with classes or functions and the library prints SDL for you). Both end up as the same schema. Schema-first is easier to read, review and share with front-end teams, which is why this tutorial uses it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which of these is NOT a built-in GraphQL scalar?

    The built-in scalars are Int, Float, String, Boolean and ID. Dates need a custom scalar.
  2. 2. What is the range of the built-in Int type?

    GraphQL's Int is 32-bit. Larger numbers need a string, a custom scalar or Float.
  3. 3. What does a type like type Query { ... } define?

    Query is the root type for read operations. Its fields are the top-level fields a client can ask for.
  4. 4. Why are descriptions better than # comments for documentation?

    Descriptions are stored in the schema and returned by introspection, so GraphiQL and other tools can display them. A # comment is ignored.

Summary

  • A GraphQL schema is written in SDL and describes types, fields, arguments and their types.
  • Object types hold fields; fields can link to other object types, which forms a graph.
  • The built-in scalars are Int (32-bit), Float, String, Boolean and ID.
  • Query is the required root type; Mutation and Subscription are optional.
  • Descriptions in """...""" or "..." document the schema and show up in tools.
  • The parser here is a stand-in; real servers build a validated schema from SDL.

Next: Lists and Non-Null Types.