@multitableReference was the legacy generator’s escape hatch for fields returning a multi-table interface or union, where a single FK path could not describe the join because each implementation lived in a different table. The schema author declared a separate @reference-shaped routes entry per implementation type. The rewrite no longer supports the directive: multi-table interface dispatch is generated from @discriminate / @discriminator (with @reference for the FK-driven join), without a separate per-route description.

The directive name is still parsed (so existing schemas don’t fail with "unknown directive @multitableReference`"), but every application is rejected at classify time with a clear message: `@multitableReference is no longer supported. Remove the directive; the rewrite generates multi-table interface dispatch from @discriminate / @discriminator without an explicit multitable-reference path. For a per-participant join path that auto-discovery cannot derive, use @referenceFor(type:, path:) instead (one application per participant). Remove every occurrence from your schema and model the dispatch through @discriminate / @discriminator, using @referenceFor where a participant’s join is not auto-discoverable.

SDL signature

directive @multitableReference(
    routes: [ReferencesForType!]
) on FIELD_DEFINITION

Migration

Drop the directive (and its ReferencesForType argument tree) and model the multi-table dispatch through @discriminate / @discriminator. How-to: Polymorphic types covers the supported shapes:

  • @discriminate on the interface or union picks the right implementation per row.

  • @discriminator on the implementation declares the row-level discriminator value.

  • For a single-table interface reached through an FK chain, @reference on the field describes the FK-driven join (single hop, or multiple hops when the path traverses join tables). For a multi-table interface or union child field, the per-branch join is auto-discovered from FK metadata and a field-level @reference is instead rejected (a single stated path cannot express a distinct join per participant); see How-to: Polymorphic types.

  • When auto-discovery cannot derive a participant’s join, @referenceFor is the successor to @multitableReference’s per-route paths: one application per participant, stating that participant’s complete path (multi-FK disambiguation, same-table self-FK, condition, and multi-hop routes). Unlike the retired `routes: input-wrapper list, @referenceFor states one fact at its natural grain (type: + path:).

For the multi-table child case the rewrite resolves the per-implementation join paths automatically from the catalog’s FK metadata (one unique single-hop FK from each participant table back to the parent); the schema author does not enumerate them and does not add a field-level @reference. Where auto-discovery is insufficient, @referenceFor states the path for that participant only.

Diagnostic

Any application of @multitableReference produces a build-time rejection:

@multitableReference is no longer supported. Remove the directive; the rewrite generates multi-table interface dispatch from @discriminate / @discriminator without an explicit multitable-reference path. For a per-participant join path that auto-discovery cannot derive, use @referenceFor(type:, path:) instead (one application per participant).

The rejection fires before the rest of the field’s classification runs, so the message is the first thing the build emits for that field. Schemas that still carry @multitableReference annotations must remove every occurrence to compile under the rewrite.

Constraints

  • Every application is rejected at build time, regardless of position. There is no "warn-only" mode and no migration shim, the surface is hard-removed.

  • The directive is still parsed (the schema still validates against the SDL), so the migration is a one-step delete-and-rebuild, not a two-step "first remove, then add @multitableReference back later".

  • The directive is mentioned in the rewrite’s directives.graphqls SDL only because removing the declaration would cause "unknown directive" parse errors on legacy schemas. Once your schema is fully migrated, the declaration is purely cosmetic.

See also

← Reference index