GraphQL Scalar Types

Scalar types are the leaf nodes of every GraphQL query. They hold actual values — text, numbers, booleans, and identifiers. Every field that returns data must eventually resolve to a scalar type; object types just group scalars together into a shape.

The Five Built-In Scalars

  Scalar    Holds                           Example value
  ──────    ─────                           ─────────────
  String    Text in UTF-8                   "Hello, World"
  Int       Whole number, 32-bit signed     42
  Float     Decimal number                  3.14
  Boolean   True or false                   true
  ID        Unique identifier (stored as    "user_001"
            string, may be numeric)

ID Is Not an Int

The ID type looks like a string in queries and responses even when the underlying database uses integers. GraphQL serializes IDs as strings so they work consistently across databases, UUID systems, and auto-increment integers alike.

  Database row:          GraphQL response:
  ─────────────          ─────────────────
  id: 42  (integer)  →   "id": "42"  (string)

Scalars Are the End of the Road

When you reach a scalar field in a query, you stop opening curly braces. Scalars have no sub-fields.

  type Article {
    id:        ID!       ← scalar, stop here
    title:     String!   ← scalar, stop here
    viewCount: Int       ← scalar, stop here
    published: Boolean!  ← scalar, stop here
    author:    Author    ← object type, go deeper
  }

Custom Scalars

GraphQL lets you define your own scalar types for data that the built-in scalars do not cover well. Common custom scalars include Date, DateTime, Email, URL, and JSON.

  SDL:
  ─────
  scalar Date
  scalar Email

  type User {
    name:      String!
    email:     Email!      ← custom scalar
    createdAt: Date!       ← custom scalar
  }

  Custom scalars need a resolver that handles:
  ────────────────────────────────────────────
  serialize   → Convert internal value → JSON output
  parseValue  → Convert client JSON input → internal value
  parseLiteral→ Convert query literal → internal value

Key Points

• The five built-in scalars are String, Int, Float, Boolean, and ID.
• ID always serializes to a string, regardless of the underlying database type.
• Scalars are leaf fields — you cannot select sub-fields from them.
• Custom scalars let you represent types like Date, Email, and URL with proper validation.