Types: Object, Scalar, and Enum

In this tutorial, you will learn about Types: Object, Scalar, and Enum. We cover key concepts, practical examples, and best practices to help you master this topic.

GraphQL has a strong type system categorizing data into object types with fields, scalar types for leaf values, and enum types for constrained allowed values. Understanding these types is essential for schema design.

What You'll Learn

• Object type structure: fields, arguments, and return types
• Built-in scalar types: String, Int, Float, Boolean, ID
• Custom scalar types for domain-specific values
• Enum types for fixed value sets

Why It Matters

The type system enforces data shape guarantees at the API boundary. Clients never have to guess the type of a field. Custom scalars and enums make schemas self-documenting and reduce validation code.

Real-World Use

Shopify uses custom scalar types like DateTime, JSON, and URL to Express domain semantics. GitHub's schema uses enums for Repository visibility (PUBLIC, PRIVATE, INTERNAL) and issue states (OPEN, CLOSED).

flowchart LR
    TypeSystem[GraphQL Type System] --> ObjectType[Object Type]
    TypeSystem --> ScalarType[Scalar Type]
    TypeSystem --> EnumType[Enum Type]
    ObjectType --> Fields[Fields with types]
    ScalarType --> BuiltIn[Built-in: String Int Float Boolean ID]
    ScalarType --> Custom[Custom: Date JSON URL Email]
    EnumType --> Values[Named values: LOW MEDIUM HIGH]

Teacher Mindset

Object types describe entities with multiple properties. Scalars are leaf nodes that terminate the graph. Enums constrain input to predefined values. Think of scalars as the atoms and objects as the molecules of your schema.

Code Examples

# Example 1: Object type with various field types
type Product {
  id: ID!
  name: String!
  price: Float!
  inStock: Boolean!
  tags: [String!]!
}

# Example 2: Custom scalar definition and usage
scalar Date
scalar Email
scalar JSON

type User {
  id: ID!
  email: Email!
  registeredAt: Date!
  metadata: JSON
}

# Example 3: Enum type with values
enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

type Order {
  id: ID!
  status: OrderStatus!
  total: Float!
}

Common Mistakes

• Using String for domain-specific values instead of custom scalars or enums
• Making all fields nullable when non-null (ID!) is more appropriate
• Forgetting to implement serialize, parseValue, and parseLiteral for custom scalars
• Using enums for dynamic values that change frequently
• Naming enum values inconsistently (UPPER_CASE vs PascalCase)

Practice

1. Define an enum Color with values RED, GREEN, BLUE.
2. Create a custom scalar PhoneNumber.
3. Design an object type Review with fields for rating, body, and author.
4. Implement parseValue and parseLiteral for a custom Currency scalar.
5. Challenge: Create a schema for a movie database with types for Movie, Actor, Genre enum, and a custom Year scalar.

FAQ

Mini Project

Extend your library schema from the previous lesson by adding a custom Date scalar for publication dates, an enum Genre, and a custom JSON scalar for book metadata. Ensure all fields use appropriate typing.

What's Next

Next, you will learn how to model relationships between types: one-to-one, one-to-many, and many-to-many associations.