Object types and scalars

This chapter follows Schemas and SDL.

GraphQL types form a graph: object types are nodes with named fields, and scalars are the terminal values execution must eventually produce. Understanding nullability and polymorphism (interface, union) prevents subtle client bugs and bad cache behavior.

Object types and fields

An object type groups fields. Each field has a return type and optional arguments:

1
type Author {
2
  id: ID!
3
  name: String!
4
  books(first: Int = 10): [Book!]!
5
}

Every object type implicitly includes __typename, a string naming the runtime type. Clients query it when a field returns an interface or union:

1
{
2
  author(id: "1") {
3
    __typename
4
    name
5
  }
6
}

Resolvers for object fields receive the parent value returned by the parent field’s resolver (often a database row or DTO).

Built-in scalars

Scalars represent leaf values. The spec defines:

Execution completes when every selected field resolves to a scalar (or null where allowed).

Custom scalars

Domains often need dates, decimals, or URLs. Declare a custom scalar in SDL:

1
scalar DateTime

The server must implement:

• serialize — value from resolver → JSON for the response
• parseValue — variable input → internal value
• parseLiteral — AST literal in the query → internal value

Link machine-readable semantics with @specifiedBy(url: "...") when a JSON Schema or RFC defines the format.

In NestJS, register a custom scalar class with @Scalar() and wire it in the module; Apollo Server and Yoga expose similar hooks.

Enumerations

Enums restrict a field or argument to a fixed set of values:

1
enum OrderStatus {
2
  PENDING
3
  SHIPPED
4
  CANCELLED
5
}

Enum values are conventionally ALL_CAPS. Adding a new enum value is usually backward compatible for queries but can break exhaustive switch statements in clients—a theme in the schema evolution chapters.

Lists and non-null

Type modifiers stack:

1
type Example {
2
  requiredList: [String!]!   # list cannot be null; elements cannot be null
3
  optionalList: [String]     # list or elements may be null
4
  nullableField: String      # field may be null
5
}

Misplaced ! is a common source of production errors: a resolver that throws on a non-null field nulls out ancestors per the spec’s bubbling rules.

Interfaces

An interface declares fields implementing types must provide:

1
interface Node {
2
  id: ID!
3
}
4

5
type User implements Node {
6
  id: ID!
7
  email: String!
8
}

Queries can return the interface; clients use inline fragments (... on User) to reach type-specific fields.

Unions

A union expresses “one of these object types” without shared fields:

1
union SearchResult = Book | Author
2

3
type Query {
4
  search(text: String!): [SearchResult!]!
5
}

Clients must query __typename and spread fragments for each member type they care about.

Next: Input types and arguments.