Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Start for Free
You're viewing documentation for a previous version of this software. Switch to the latest stable version.

Value types

Define the exact same type in multiple services

It's common to reuse a type across multiple subgraphs. For example, you might define a generic Error interface and an ErrorCode enum:

interface Error {
code: ErrorCode!
message: String!
enum ErrorCode {

These value types don't "originate" in a particular . Instead, all of the that define a value type share ownership.

Most importantly, a value type must be defined identically in every subgraph that defines it. Otherwise, your federated schema will fail . Not every subgraph needs to define a particular value type.

Any of the following can be a value type:

  • s
  • Objects
  • Interfaces
  • Inputs
  • Enums
  • Unions

Specific considerations for each of these are listed below.

Type-specific considerations


If you define a custom scalar as a value type, make sure all of your subgraphs use the exact same serialization and parsing logic for it. The schema composition process does not verify this.

Objects, interfaces, and inputs

For types with definitions, all fields and their types must be identical (including nullability).

If an is an entity, it cannot be a value type.

Enums and unions

For enums and unions, all possible values must match across all defining subgraphs. Even if a particular subgraph doesn't use a particular value, that value still must be defined in the schema. Otherwise, your federated schema will fail composition.

Modifying a value type

As mentioned, a value type must be defined identically in every subgraph that defines it. This means that if you want to modify a value type's definition in one subgraph, you must make that same modification in each other defining subgraph. Otherwise, a composition error occurs.

While you are actively deploying your updated subgraphs, your value type's definition will temporarily differ between subgraphs. During this time, GraphQL might produce validation errors.

If you aren't using managed federation, you must wait until all of your defining subgraphs are deployed with the updated value type before you restart your gateway to compose the new .

Migrating from schema stitching
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy