graphql-federation

GraphQL Federation Skill

Create correct GraphQL federation subgraphs following WunderGraph Cosmo composition rules.

Core Concepts

Subgraph: A GraphQL microservice contributing to the federated graph. Federated Graph/Supergraph: The composed GraphQL interface for clients. Router: Plans operations, routes requests to subgraphs, joins data. Entity: A type with @key directive resolvable across subgraphs. Router Schema vs Client Schema: Router sees all fields; clients don't see @inaccessible items.

Essential Directives

@key - Define Entities

# Basic entity
type User @key(fields: "id") {
  id: ID!
  name: String!
}

# Multiple keys
type Product @key(fields: "id") @key(fields: "sku") {
  id: ID!
  sku: String!
  name: String!
}

# Composite key
type Review @key(fields: "author { id } product { id }") {
  author: User!
  product: Product!
  rating: Int!
}

# Non-resolvable key (reference only, can't resolve this entity)
type User @key(fields: "id", resolvable: false) {
  id: ID!
}

Key Rules:

• Key fields cannot have arguments
• Key fields cannot be abstract types (interfaces/unions)
• Key fields must select leaf scalars or nested objects with selections
• Multiple keys provide alternative resolution paths

@shareable - Allow Multiple Definitions

# When same field exists in multiple subgraphs
type User @key(fields: "id") {
  id: ID!
  name: String! @shareable  # Can be defined in other subgraphs
}

# Object-level shareable applies to all fields
type User @key(fields: "id") @shareable {
  id: ID!
  name: String!
  email: String!
}

Shareable Rules:

• Fields defined in multiple subgraphs MUST be @shareable
• Key fields used in other subgraphs' keys must be @shareable
• Root type fields (Query, Mutation) are implicitly shareable

@external - Reference External Fields

# Mark fields resolved by another subgraph
extend type User @key(fields: "id") {
  id: ID! @external
  name: String! @external
  reviews: [Review!]!  # This subgraph resolves reviews
}