• Docs
  • Schema Stitching
  • Federation to Stitching

Federation SDL to Stitching SDL

federationToStitchingSDL utility converts an Apollo Federation SDL string into a Schema Stitching SDL string.

Schema Stitching supports freeform service bindings that may integrate with any GraphQL query, including the _entities query setup by Federation services. That means Federation SDLs may be converted to a Stitching SDL and added to a stitched gateway...

Federation SDL
type Widget @key(fields: "id") {
  id: ID! @external
  name: String
  price: Int @external
  shippingCost: Int @requires(fields: "price")
  parent: Widget @provides(fields: "price")
Converted Stitching SDL
type Widget @key(selectionSet: "{ id }") {
  id: ID!
  name: String
  shippingCost: Int @computed(selectionSet: "{ price }")
  parent: Widget
scalar _Any
union _Entity = Widget
type Query {
  _entities(representations: [_Any!]!): [_Entity]! @merge

The translated SDL is configured for the Schema Stitching query planner, see complete translation logic.


Fetch the SDL from a Federation service:

query {
  _service {

Convert the Federation SDL to a Stitching SDL:

const { federationToStitchingSDL, stitchingDirectives } = require('@graphql-tools/stitching-directives')
// config is only needed when customizing stitching directive names...
const config = stitchingDirectives()
const stitchingSDL = federationToStitchingSDL(federationSDL, config)


A working example can be found in the Schema Stitching Handbook. A compact summary of the major parts looks like this:

const { stitchSchemas } = require('@graphql-tools/stitch')
const { federationToStitchingSDL, stitchingDirectives } = require('@graphql-tools/stitching-directives')
const { buildSchema, print } = require('graphql')
const { fetch } = require('@whatwg-node/fetch')
const stitchingConfig = stitchingDirectives()
const executor = async ({ document, variables }) => {
  const query = typeof document === 'string' ? document : print(document)
  const response = await fetch('http://localhost:4001/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, variables })
  return response.json()
const federationSDL = await executor({ document: '{ _service { sdl } }' })
const stitchingSDL = federationToStitchingSDL(federationSDL, stitchingConfig)
const gatewaySchema = stitchSchemas({
  subschemaConfigTransforms: [stitchingConfig.stitchingDirectivesTransformer],
  subschemas: [
      schema: buildSchema(stitchingSDL),

Translation Logic

Federation and Stitching use fundamentally similar patterns to combine underlying subservices (in fact, both tools have shared origins in Apollo Stitching). However, Federation SDLs are nuanced because they are incomplete (they omit their own spec), they may contain baseless type extensions (which are invalid GraphQL), and they may contain fields that the service has no data for (the "external" fields). These nuances are normalized for Schema Stitching as follows:

  1. Prepend a directives type definition string.
  2. Turn all baseless type extensions into base types.
  3. Rewrite @key(fields: "id") as @key(selectionSet: "{ id }").
  4. Rewrite @requires(fields: "price") as @computed(selectionSet: "{ price }").
  5. Remove fields with an @external directive unless they are part of the @key. Stitching expects schemas to only publish fields that they actually have data for. Remove any remaining @external directives.
  6. Remove all @provides directives. They are no longer necessary once the indirection of @external fields is eliminated. Stitching's query planner can automate the optimal selection of as many fields as possible from as few services as possible.
  7. Collect the names of all types marked with @key (Entities). If there are one or more names:
    • Add an _Any scalar.
    • Add an _Entity union populated with all unique names.
    • Add an _entities(representations: [_Any!]!): [_Entity]! @merge query.
Last updated on October 4, 2022