Introduction to GraphQL Scalars: Primitive Types Explained

Previously in this course, we explored Understanding the GraphQL Schema: Building Your API Contract, where we established that the Schema Definition Language (SDL) acts as the source of truth for your API. Now that you know how to define custom object types, we need to focus on the "leaves" of your data tree: Scalars.

In GraphQL, scalars are the primitive types that cannot have sub-fields. They are the data types that actually hold your values, like the title of a blog post or the status of a user account. Without them, your schema would be an infinite nesting of objects with no actual data to return.

The Five Built-in GraphQL Types

GraphQL comes with five default scalars. When you design your schema, you map your data requirements to these specific GraphQL types to ensure your API remains predictable and strictly typed.

Using Scalars in Your SDL

To assign a scalar to a field, you use the colon syntax you learned previously. If you are building a product catalog for our running project, your schema definitions would look like this:

GraphQL
type Product {
  id: ID!
  name: String
  price: Float
  stockCount: Int
  isAvailable: Boolean
}

• ID: We use this for unique keys. While it is serialized as a string, using ID signals to the client and tools that this field should be used for identification and caching, rather than human-readable text.
• String: Used for names, descriptions, or any textual data.
• Float: Essential for currency, coordinates, or precise measurements.
• Int: Perfect for counts or whole numbers that don't require decimal precision.
• Boolean: The standard choice for flags, toggles, or binary state.

Hands-on Exercise: Refining the User Profile

Let’s advance our running project. Imagine we are building a User profile system. Based on what we've learned, update your schema definition to include the following fields:

1. username (Text)
2. age (Whole number)
3. isVerified (True/False flag)
4. accountBalance (Decimal number)
5. uuid (Unique identifier)

Try this: Write out the type User block using the correct GraphQL scalars before reading further.

GraphQL
# Your solution should look like this:
type User {
  uuid: ID
  username: String
  age: Int
  accountBalance: Float
  isVerified: Boolean
}

Common Pitfalls

Even senior engineers encounter these common traps when working with scalars:

• Treating IDs as Integers: Even if your database uses numeric IDs (like 1, 2, 3), always define them as ID in GraphQL. This prevents issues if you ever migrate to UUIDs or string-based identifiers later.
• Precision Loss with Floats: While Float is fine for most scenarios, it is not suitable for high-precision financial calculations. In production, you would eventually use a custom scalar for money, but for now, sticking to Float is the standard beginner practice.
• Ignoring Nullability: Note that simply writing String means the field can be null. We will cover this in depth in upcoming lessons, but keep in mind that these scalars can be marked as non-nullable using an exclamation point (String!).

Frequently Asked Questions

Can I create my own scalars? Yes, but that is an advanced topic. For now, stick to the built-in five. If you need a specific type like a Date or Email, you will eventually learn how to implement custom scalars to validate those specific formats.

Why is ID serialized as a string? To ensure flexibility. Many modern systems use non-numeric identifiers (like MongoDB's ObjectId or UUIDs), which cannot be represented as standard 32-bit integers.

Is there a character limit on the String type? No, GraphQL does not impose a length limit on the String scalar. However, your underlying database or server memory limits will dictate the practical maximum.

Recap

Scalars are the fundamental building blocks of your API. By using String, Int, Float, Boolean, and ID correctly, you ensure your schema provides a clean, predictable contract for the client. These types represent the final destination of every query, marking the transition from the schema structure to actual data values.

Up next: We will take these primitive types and combine them into custom Object Types to build more complex, nested data structures.