Migrating from Schema Stitching to Hot Chocolate Fusion

This page covers the steps required to migrate a backend service from the legacy schema stitching approach to Hot Chocolate Fusion.

Background

Previously, Suite used schema stitching to federate GraphQL schemas into a unified gateway. Each backend service was registered in the BFF's federation.json, which defined how its schema was merged, including type renaming and schema extensions. The gateway was responsible for fetching and stitching schemas at runtime.

Fusion replaces this with a build-time composition model. Each backend service owns its subgraph configuration and declares which BFFs it publishes to, removing the need for the gateway to have any explicit knowledge of its downstream services.

Migration Steps

1. Register the service in application.yaml

Add a graphql.publish entry for the BFF being migrated. For each BFF the service publishes to, declare the gateway name and any extension files:

spec:
  build:
    dotnet:
      graphql:
        publish:
          - gateway: admin-center-bff
            extensions:
              - admin-center.fusion.extensions.graphql

2. Create the Fusion extension file

The extension file replaces the stitching configuration previously declared in federation.json. It is a GraphQL schema file that applies gateway-specific customizations to the subgraph.

Type renaming

In stitching, type renaming was configured in federation.json under RenameTypes:

{
  "TypeName": "Address",
  "NewTypeName": "amos_Address"
}

In Fusion, renaming is expressed directly in the extension file using @rename:

extend schema
  @rename(coordinate: "Address", newName: "amos_Address")

Check the service's federation.json entry for the target BFF and translate each RenameTypes entry into a corresponding @rename directive.

3. Remove @delegate directives

In stitching, @delegate directives were used in the BFF schema to resolve fields from a remote subgraph:

type Query {
  address(id: ID!): Address @delegate(schema: "addresses", path: "address(id: $id)")
}

In Fusion, field resolution across subgraphs is handled automatically during composition. Remove all @delegate directives from the BFF schema — they are no longer needed and will cause errors if left in place.

4. Remove @suiteAuthorize directives

Remove any @suiteAuthorize directives from the subgraph schema. Authorization support in Fusion is currently under review.

5. Run the compose command

Once the extension file is in place and application.yaml is updated, run the compose command for the target BFF to validate the migration:

suite graphql compose admin-center-bff

If composition succeeds without errors, the migration for this service is complete. Any schema conflicts — such as missing renames or type collisions — will surface as CLI errors at this step.

Reference: federation.json to Fusion mapping

Stitching (federation.json)	Fusion equivalent
FederationName	gateway in application.yaml
SchemaExtensionFiles	extensions in application.yaml
RenameTypes	@rename in the extension file
IgnoreRootTypes	Handled automatically by Fusion
@delegate in BFF schema	Removed — resolved automatically during composition
@authorize	Pending review