Value types in Apollo Federation

In a federated graph, it's common to want to reuse a GraphQL type in multiple subgraphs.

For example, suppose you want to define and reuse a generic Position type in different subgraphs:

1
type Position {
2
  x: Int!
3
  y: Int!
4
}

Types like this are called value types. This article describes how to share value types and their fields in federated graph, enabling multiple subgraphs to define and resolve them.

Sharing object types

By default in Federation 2 subgraphs, a single object field can't be defined or resolved by more than one subgraph schema.

Consider the following Position example:

❌

type Position {
  x: Int!
  y: Int!
}

type Position {
  x: Int!
  y: Int!
}

Attempting to compose these two subgraph schemas together will break composition. The gateway doesn't know which subgraph is responsible for resolving Position.x and Position.y. To enable multiple subgraphs to resolve these fields, you must first mark that field as @shareable.

Using @shareable

The @shareable directive enables multiple subgraphs to resolve a particular object field (or set of object fields).

To use @shareable in a subgraph schema, you first need to add the following snippet to that schema to opt in to Federation 2:

1
extend schema
2
    @link(url: "https://specs.apollo.dev/federation/v2.0",
3
          import: ["@key", "@requires", "@shareable", "@provides", "@external"])

Then you can apply the @shareable directive to an object type, or to individual fields of that type:

✅

type Position @shareable {
  x: Int!
  y: Int!
}

type Position {
  x: Int! @shareable
  y: Int! @shareable
}

Both subgraphs A and B can now resolve the x and y fields for the Position type, and our subgraph schema will successfully compose into a supergraph schema.

⚠️ Important considerations for @shareable

• If a type or field is marked @shareable in any subgraph, it must be marked @shareable or @external in every subgraph that defines it. Otherwise, composition fails.
• If multiple subgraphs can resolve a field, make sure each subgraph's resolver for that field behaves identically. Otherwise, queries might return inconsistent results depending on which subgraph resolves the field.

Varying shared object fields

Shared fields can differ between subgraphs in specific ways:

• The return type of a shared field can vary in nullability (String / String!).
  • A shared field's return type can't vary in its core type (Int vs. String) or in whether it returns a list (Int vs. [Int]).
• A shared field can be omitted from a subgraph entirely if that field is always resolvable.

For example, take a look at the shared Food type below:

type Food @shareable {
  name: String!
  cost: Int!
}

type Food @shareable {
  name: String!
  cost: Int # Nullable
  inStock: Boolean! # Not in A
}

The above Food types differ in the nullability of their fields and the fields included in each type.

Differing return types

Let's say two subgraphs both define an Event object type with a timestamp field:

❌

type Event @shareable {
  timestamp: Int!
}

type Event @shareable {
  timestamp: String!
}

Subgraph A's timestamp returns an Int, and Subgraph B's returns a String. This is invalid. When composition attempts to generate an Event type for the supergraph schema, it fails due to an unresolvable conflict between the two timestamp field definitions.

Next, look at these varying definitions for the Position object type:

✅

type Position @shareable {
  x: Int!
  y: Int!
}

type Position @shareable {
  x: Int
  y: Int
}

The x and y fields are non-nullable in Subgraph A, but they're nullable in Subgraph B. This is valid! Composition recognizes that it can use the following definition for Position in the supergraph schema:

1
type Position {
2
  x: Int
3
  y: Int
4
}

This definition works for querying Subgraph A, because Subgraph A's definition is more restrictive than this (a non-nullable value is always valid for a nullable field). In this case, composition coerces Subgraph A's Position fields to satisfy the reduced restrictiveness of Subgraph B.

Omitting fields

Look at these two definitions of a Position object type:

⚠️

type Position @shareable {
  x: Int!
  y: Int!
}

type Position @shareable {
  x: Int!
  y: Int!
  z: Int!
}

Subgraph B defines a z field, but Subgraph A doesn't. In this case, when composition generates the Position type for the supergraph schema, it includes all three fields:

type Position {
  x: Int!
  y: Int!
  z: Int!
}

This definition works for Subgraph B, but it presents a problem for Subgraph A. Let's say Subgraph A defines the following Query type:

type Query {
  currentPosition: Position!
}

According to the hypothetical supergraph schema, the following query is valid against the supergraph:

❌

query GetCurrentPosition {
  currentPosition {
    x
    y
    z # ⚠️ Unresolvable! ⚠️
  }
}

And here's the problem: if Subgraph B doesn't define Query.currentPosition, this query must be executed on Subgraph A. But Subgraph A is missing the Position.z field, so that field is unresolvable!

Composition recognizes this potential problem, and it fails with an error. So how do we fix it? Check out Solutions for unresolvable fields.

Enums, unions, and interfaces

In Federation 2, enum, interface, and union type definitions can be shared between subgraphs by default, and those definitions can differ:

union Media = Book | Movie

enum Color {
  RED
  GREEN
  BLUE
}

interface User {
  name: String!
}

union Media = Book | Podcast

enum Color {
  CYAN
  MAGENTA
  YELLOW
}

interface User {
  name: String!
  age: Int!
}

Compositional logic merges these definitions in your supergraph schema:

1
union Media = Book | Movie | Podcast
2

3
enum Color {
4
  RED
5
  GREEN
6
  BLUE
7
  CYAN
8
  MAGENTA
9
  YELLOW
10
}
11

12
# The object types that implement this interface are
13
# responsible for resolving these fields.
14
interface User {
15
  name: String!
16
  age: Int!
17
}

This can be useful when different subgraphs are responsible for different subsets of a particular set of related types or values.