Federated schemas

Overview

A federated supergraph uses multiple "types" of GraphQL schemas:

Subgraph schemas. Each subgraph has a distinct schema that indicates which types and fields of your composed supergraph it can resolve.
- These are the only schemas that your teams define manually.
Supergraph schema. This schema combines all of the types and fields from your subgraph schemas, plus some federation-specific information that tells your gateway which subgraphs can resolve which fields.
- This schema is the result of performing composition on your collection of subgraph schemas.
API schema. This schema is similar to the supergraph schema, but it omits federation-specific types, fields, and directives that are considered "machinery" and are not part of your public API.
- This is the schema that your gateway exposes to clients, who don't need to know internal implementation details about your graph.

Let's look at an example!

Subgraph schemas

Below are the schemas for three subgraphs in a basic e-commerce application. Each subgraph is implemented as a separate GraphQL API:

Users

type Query {
  me: User
}

type User @key(fields: "id") {
  id: ID!
  username: String! @shareable
}

# (Subgraph schemas include
# this to opt in to
# Federation 2 features.)
extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.0",
        import: ["@key", "@shareable"])

Products

type Query {
  topProducts(first: Int = 5): [Product]
}

type Product @key(fields: "upc") {
  upc: String!
  name: String!
  price: Int
}

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

Reviews

type Review {
  body: String
  author: User @provides(fields: "username")
  product: Product
}

type User @key(fields: "id") {
  id: ID!
  username: String! @external
  reviews: [Review]
}

type Product @key(fields: "upc") {
  upc: String!
  reviews: [Review]
}

# (This subgraph uses additional
# federated directives)
extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.0",
        import: ["@key", "@shareable", "@provides", "@external"])

As these schemas show, multiple subgraphs can contribute unique fields to a single type. For example, the Products subgraph and the Reviews subgraph both contribute fields to the Product type.

Supergraph schema

The supergraph schema is the output of schema composition. It serves the following purposes:

It provides your gateway with the name and endpoint URL for each of your subgraphs.
It includes all types and fields defined by all of your subgraphs.
It tells your gateway which of your subgraphs can resolve which GraphQL fields.

Here's the supergraph schema composed with the subgraph schemas above:

1
schema
2
  @link(url: "https://specs.apollo.dev/link/v1.0")
3
  @link(url: "https://specs.apollo.dev/join/v0.2", for: EXECUTION)
4
{
5
  query: Query
6
}
7

8
directive @join__field(graph: join__Graph!, requires: join__FieldSet, provides: join__FieldSet, type: String, external: Boolean, override: String, usedOverridden: Boolean) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION
9

10
directive @join__graph(name: String!, url: String!) on ENUM_VALUE
11

12
directive @join__implements(graph: join__Graph!, interface: String!) repeatable on OBJECT | INTERFACE
13

14
directive @join__type(graph: join__Graph!, key: join__FieldSet, extension: Boolean! = false, resolvable: Boolean! = true) repeatable on OBJECT | INTERFACE | UNION | ENUM | INPUT_OBJECT | SCALAR
15

16
directive @link(url: String, as: String, for: link__Purpose, import: [link__Import]) repeatable on SCHEMA
17

18
scalar join__FieldSet
19

20
enum join__Graph {
21
  PRODUCTS @join__graph(name: "products", url: "http://localhost:4003/graphql")
22
  REVIEWS @join__graph(name: "reviews", url: "http://localhost:4002/graphql")
23
  USERS @join__graph(name: "users", url: "http://localhost:4001/graphql")
24
}
25

26
scalar link__Import
27

28
enum link__Purpose {
29
  """
30
  `SECURITY` features provide metadata necessary to securely resolve fields.
31
  """
32
  SECURITY
33

34
  """
35
  `EXECUTION` features provide metadata necessary for operation execution.
36
  """
37
  EXECUTION
38
}
39

40
type Product
41
  @join__type(graph: PRODUCTS, key: "upc")
42
  @join__type(graph: REVIEWS, key: "upc")
43
{
44
  upc: String!
45
  name: String! @join__field(graph: PRODUCTS)
46
  price: Int @join__field(graph: PRODUCTS)
47
  reviews: [Review] @join__field(graph: REVIEWS)
48
}
49

50
type Query
51
  @join__type(graph: PRODUCTS)
52
  @join__type(graph: REVIEWS)
53
  @join__type(graph: USERS)
54
{
55
  topProducts(first: Int = 5): [Product] @join__field(graph: PRODUCTS)
56
  me: User @join__field(graph: USERS)
57
}
58

59
type Review
60
  @join__type(graph: REVIEWS)
61
{
62
  body: String
63
  author: User @join__field(graph: REVIEWS, provides: "username")
64
  product: Product
65
}
66

67
type User
68
  @join__type(graph: REVIEWS, key: "id")
69
  @join__type(graph: USERS, key: "id")
70
{
71
  id: ID!
72
  username: String! @join__field(graph: REVIEWS, external: true) @join__field(graph: USERS)
73
  reviews: [Review] @join__field(graph: REVIEWS)
74
}

As you can see, the supergraph schema includes a lot of Federation-specific additions! These additions are used only by the gateway, and you'll never need to add them manually.

The gateway uses its supergraph schema to produce an API schema, which it exposes to clients as your actual GraphQL API. This schema cleanly and logically represents the combination of your subgraph schemas:

1
type Product {
2
  name: String!
3
  price: Int
4
  reviews: [Review]
5
  upc: String!
6
}
7

8
type Query {
9
  me: User
10
  topProducts(first: Int = 5): [Product]
11
}
12

13
type Review {
14
  author: User
15
  body: String
16
  product: Product
17
}
18

19
type User {
20
  id: ID!
21
  reviews: [Review]
22
  username: String!
23
}

Unlike the supergraph schema, this schema hides the fact that your GraphQL API is composed of multiple distinct GraphQL APIs.

Edit on GitHub

Graph router/gateway

Composition