Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Docs
Launch GraphOS Studio

Federated schemas

Overview


A federated uses multiple "types" of GraphQL s:

(Composition succeeds)
(Remove routing machinery)
Subgraph
schema
A
Subgraph
schema
B
Subgraph
schema
C
🛠
Composition
Supergraph schema
(A + B + C + routing machinery)
API schema
(A + B + C)
  • Subgraph schemas. Each subgraph has a distinct that indicates which types and s of your composed supergraph it can resolve.
    • These are the only s that your teams define manually.
  • Supergraph schema. This combines all of the types and s from your schemas, plus some federation-specific information that tells your which s can resolve which s.
    • This is the result of performing composition on your collection of s.
  • API schema. This is similar to the schema, but it omits federation-specific types, s, and s that are considered "machinery" and are not part of your public API.
    • This is the that your exposes to clients, which don't need to know internal implementation details about your graph.

Let's look at an example!

Subgraph schemas

Below are example s for three s in an e-commerce company's . 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.3",
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.3",
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.3",
import: ["@key", "@shareable", "@provides", "@external"])

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

Supergraph schema

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

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

Here's the composed with the subgraph schemas above:

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

API schema

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

type Product {
name: String!
price: Int
reviews: [Review]
upc: String!
}
type Query {
me: User
topProducts(first: Int = 5): [Product]
}
type Review {
author: User
body: String
product: Product
}
type User {
id: ID!
reviews: [Review]
username: String!
}

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

Previous
JetBrains IDE Support
Next
Composition
Edit on GitHubEditForumsDiscord