GraphQL Schema Basics

The schema is the backbone of every GraphQL API. It describes every type of data that exists in your system and every operation a client can perform. Think of it as the blueprint of your entire API written in a simple, readable format called SDL — Schema Definition Language.

SDL Looks Like a Blueprint

  Schema Definition Language (SDL)
  ─────────────────────────────────
  type Product {            ← Define a data type
    id:    ID!              ← Field: id, type ID, required
    name:  String!          ← Field: name, type String, required
    price: Float            ← Field: price, type Float, optional
  }

  type Query {              ← Define readable operations
    product(id: ID!): Product
    allProducts: [Product]
  }

The Query Type Is the Entry Point for Reading

The Query type is special. It defines all the operations a client can use to read data. Every field in the Query type becomes a top-level query a client can call.

  Schema:                   Client can call:
  ──────                    ────────────────
  type Query {              { product(id: "5") { name } }
    product(id: ID!): Product
    allProducts: [Product]  { allProducts { name price } }
  }

The Mutation Type Is the Entry Point for Writing

The Mutation type defines all write operations — create, update, delete. If your schema has no Mutation type, the API is read-only.

  type Mutation {
    createProduct(name: String!, price: Float!): Product
    deleteProduct(id: ID!): Boolean
  }

Types Reference Other Types

A GraphQL schema becomes powerful when types reference other types. This models real-world relationships like a store having many products, or a blog post having many comments.

  type Author {             type Book {
    id:    ID!                id:     ID!
    name:  String!            title:  String!
    books: [Book]    ←───     author: Author   ←── Book
  }                         }                       points
                                                    back to
                                                    Author

The Exclamation Mark Means Required

An exclamation mark (!) after a type means the field will never return null. Without it, the field can be null. Putting an exclamation mark in the wrong place causes confusion, so learn this rule early.

  String    ← Can be null or a string
  String!   ← Will always be a string, never null
  [String]  ← Can be null, or a list (items can be null)
  [String!] ← Can be null, or a list where items are never null
  [String]! ← Will always be a list (but items can be null)
  [String!]!← Always a list AND items are never null

Comments in SDL

SDL supports two types of comments. Regular comments use #. Documentation strings use three double-quotes and appear in the API explorer automatically.

  # This is a regular comment — not visible to clients

  """
  A product available for purchase in the store.
  This description appears in Apollo Sandbox.
  """
  type Product {
    """The unique identifier of the product"""
    id: ID!

    """The display name shown to customers"""
    name: String!
  }

A Complete Mini Schema

  type Category {
    id:   ID!
    name: String!
  }

  type Product {
    id:       ID!
    name:     String!
    price:    Float!
    inStock:  Boolean!
    category: Category
  }

  type Query {
    product(id: ID!):   Product
    products:          [Product!]!
    categories:        [Category!]!
  }

  type Mutation {
    addProduct(
      name:       String!
      price:      Float!
      categoryId: ID!
    ): Product!
  }

Key Points

• The schema is written in SDL and acts as the contract between client and server.
• The Query type defines all read operations; the Mutation type defines all write operations.
• An exclamation mark means a field is non-null — it will always return a value.
• Types can reference other types to model real-world relationships.
• Triple-quoted strings become automatic documentation visible in GraphQL tools.