Skip to content

GraphQL Types

GraphQL is a strongly typed language. Every piece of data and operation is described using a system of types. Understanding these types is essential to designing and querying GraphQL APIs effectively.

Type System Overview

There are several categories of types in GraphQL:

  1. Scalar Types (basic data types)
  2. Object Types (custom structured data)
  3. Enum Types (enumerated values)
  4. Interface Types (shared structure between types)
  5. Union Types (one of many possible types)
  6. Input Types (used for inputs in mutations)

1. Scalar Types

Scalars represent the leaves of a query — the fields that resolve to concrete data.

Built-in Scalars:

Type Description
Int 32-bit signed integer
Float Double-precision floating point
String UTF-8 character sequence
Boolean true or false
ID Unique identifier (often a string)

Custom scalars like Date, Email, URL can be defined and validated server-side.

2. Object Types

These are the most common and represent structured data with fields.

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}
  • Fields can be scalars or other object types.
  • You can nest objects infinitely.

3. Enum Types

Enums define a set of allowed values.

enum Role {
  ADMIN
  USER
  GUEST
}

type User {
  id: ID!
  name: String!
  role: Role!
}

Use enums for roles, statuses, categories, etc.

4. Interface Types

Interfaces allow different types to share fields.

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String!
}

type Post implements Node {
  id: ID!
  title: String!
}

Clients can query shared fields without knowing the exact type.

5. Union Types

Unions allow a field to return one of several types.

union SearchResult = User | Post

type Query {
  search(term: String!): [SearchResult!]!
}

Use unions when a field can return different types that don’t share a common interface.

6. Input Types

Input types are used in mutations or arguments where structured input is needed.

input CreatePostInput {
  title: String!
  content: String!
}

type Mutation {
  createPost(input: CreatePostInput!): Post!
}

Input types cannot contain fields that are other object types (only scalars, enums, or other input types).

Nullability & Lists

GraphQL types are nullable by default. You can make types non-null with ! and use lists with [].

Syntax Meaning
String May be null
String! Must be a string, not null
[String] A list of nullable strings
[String!] A list of non-null strings
[String!]! A non-null list of non-null strings

Best Practices

  • ✅ Use descriptive and meaningful names for types and fields
  • ✅ Model your API based on how clients will consume it
  • ✅ Prefer enums over arbitrary strings for predictable values
  • ✅ Use input types for clarity and validation in mutations

Resources

Summary

GraphQL’s type system is one of its biggest strengths. It allows for self-documenting, strongly-typed, and precise APIs that provide clear contracts between clients and servers.