Learn GraphQL - Building Schemas and Understanding the Type System

#Introduction

The schema is the contract between client and server in GraphQL. Everything else — queries, mutations, resolvers — follows the shape defined here. Episode 3 dissects the Schema Definition Language (SDL) and the entire available type system.

#Scalar Types

#Built-in Scalars

• Int: 32-bit integer.
• Float: decimal number.
• String: UTF-8 text.
• Boolean: true or false.
• ID: unique identity, serialized like a String.

type Product {
  id: ID!
  name: String!
  price: Float!
  inStock: Boolean
  stockCount: Int
}

#Custom Scalars

scalar DateTime
scalar JSON

#Object Types

#Defining an Object Type

type User {
  id: ID!
  username: String!
  avatar(size: AvatarSize): String
}
 
type Query {
  user(id: ID!): User
  users(limit: Int = 10): [User!]!
}

#Input Types

input CreateUserInput {
  username: String!
  email: String!
  password: String!
}
 
input UpdateUserInput {
  username: String
  email: String
}
 
type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
}

#Enum Types

enum OrderStatus {
  PENDING
  PAID
  SHIPPED
  DELIVERED
  CANCELLED
}
 
type Order {
  id: ID!
  status: OrderStatus!
}

#Interface and Union Types

#Interface

interface Node {
  id: ID!
}
 
type User implements Node {
  id: ID!
  username: String!
}
 
type Post implements Node {
  id: ID!
  title: String!
}
 
type Query {
  search(term: String!): [Node]
}

query Cari($term: String!) {
  search(term: $term) {
    ... on User {
      username
    }
    ... on Post {
      title
    }
  }
}

#Union Types

union SearchResult = User | Post | Comment
 
type Query {
  search(term: String!): [SearchResult!]!
}

#List Types and Modifiers

Lists are written with square brackets. Combining them with ! produces four variants, and the best practice many teams follow is [String!]! for a required list — this nullability design prevents cascading errors and affects client-side caching (episodes 18 and 20). To check the consistency of your schema, run npx graphql-schema-linter schema.graphql.

type Query {
  a: [String]     # list may be null, items may be null
  b: [String]!    # list is required, items may be null
  c: [String!]    # list may be null, items must be strings
  d: [String!]!   # list is required, items must be strings
}

#Conclusion

Key takeaways:

• Five built-in scalars: Int, Float, String, Boolean, and ID.
• Custom scalars for special needs like DateTime and JSON.
• Object types for output, input types for arguments and mutations.
• Enums restrict values, interfaces define shared contracts, unions handle independent results.
• The four list and ! modifier combinations define the nullability contract.

In the next episode, episode 4, you'll learn about query operations — basic syntax, arguments, aliases, fragments, variables, and directives. With the schema you designed in this episode, it's now time to write your first operation that actually fetches data.