Guide for authoring Apollo Federation subgraph schemas. Use this skill when: (1) creating new subgraph schemas for a federated supergraph, (2) defining or modifying entities with @key, (3) sharing types/fields across subgraphs with @shareable, (4) working with federation directives (@external, @requires, @provides, @override, @inaccessible), (5) troubleshooting composition errors, (6) any task involving federation schema design patterns.
Apollo Federation enables composing multiple GraphQL APIs (subgraphs) into a unified supergraph.
Every Federation 2 subgraph must opt-in via @link:
extend schema
@link(url: "https://specs.apollo.dev/federation/v2.12",
import: ["@key", "@shareable", "@external", "@requires", "@provides"])
Import only the directives your subgraph uses.
| Directive | Purpose | Example |
|---|---|---|
@key | Define entity with unique key | type Product @key(fields: "id") |
@shareable | Allow multiple subgraphs to resolve field | type Position @shareable { x: Int! } |
@external | Reference field from another subgraph | weight: Int @external |
@requires | Computed field depending on external fields | shippingCost: Int @requires(fields: "weight") |
@provides | Conditionally resolve external field | @provides(fields: "name") |
@override | Migrate field to this subgraph | @override(from: "Products") |
@inaccessible | Hide from API schema | internalId: ID! @inaccessible |
@interfaceObject | Add fields to entity interface | type Media @interfaceObject |
Detailed documentation for specific topics:
type Product @key(fields: "id") {
id: ID!
name: String!
price: Int
}
# Products subgraph
type Product @key(fields: "id") {
id: ID!
name: String!
price: Int
}
# Reviews subgraph
type Product @key(fields: "id") {
id: ID!
reviews: [Review!]!
averageRating: Float
}
type Product @key(fields: "id") {
id: ID!
size: Int @external
weight: Int @external
shippingEstimate: String @requires(fields: "size weight")
}
type Money @shareable {
amount: Int!
currency: String!
}
type Product @key(fields: "id", resolvable: false) {
id: ID!
}
@link directive@shareable without ensuring all subgraphs return identical values for that field@key with single ID field for simple entity identificationrover supergraph compose to validate composition locallyrover subgraph check to validate against production supergraph