Supergraph Entity Design

The x-graphql-supergraph-name extension enables JSON Schemas to explicitly declare their role in a federated GraphQL supergraph, identifying base entity subgraphs that own type definitions and serve as query roots.

Problem Statement

In Apollo Federation, base/owner subgraphs define the primary entity type with @key, and extending subgraphs use @extends to add fields. Federation validators must otherwise infer ownership from directives alone — which becomes ambiguous when multiple schemas have @key directives, or when API gateways need explicit routing information.

Schema Extension Properties

Property	Type	Required	Description
`x-graphql-supergraph-name`	string	Yes	Unique subgraph identifier (e.g., `"users-service"`)
`x-graphql-supergraph-type`	enum	Yes	Role: `base-entity` \| `entity-extending` \| `utility`
`x-graphql-supergraph-entity`	string	Yes	Entity type name (e.g., `"User"`). All schemas for the same entity must match.
`x-graphql-supergraph-query-root`	boolean	No	If `true`, this subgraph handles root Query fields for this entity
`x-graphql-supergraph-version`	string	No	Schema version for this subgraph (e.g., `"1.0.0"`)

Usage Examples

Base Entity Subgraph (Owner)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User Entity - Base",
  "x-graphql-supergraph-name": "users-service",
  "x-graphql-supergraph-type": "base-entity",
  "x-graphql-supergraph-entity": "User",
  "x-graphql-supergraph-query-root": true,
  "type": "object",
  "x-graphql-type-name": "User",
  "x-graphql-directives": [
    { "name": "key", "arguments": { "fields": "\"user_id\"" } }
  ],
  "properties": {
    "user_id": { "type": "string", "x-graphql-type": "ID!" }
  }
}

Extending Entity Subgraph

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User Status - Extending",
  "x-graphql-supergraph-name": "user-status-service",
  "x-graphql-supergraph-type": "entity-extending",
  "x-graphql-supergraph-entity": "User",
  "x-graphql-supergraph-query-root": false,
  "type": "object",
  "x-graphql-type-name": "User",
  "x-graphql-directives": [
    { "name": "extends" },
    { "name": "key", "arguments": { "fields": "\"user_id\"" } }
  ],
  "properties": {
    "user_id": {
      "type": "string",
      "x-graphql-type": "ID!",
      "x-graphql-directives": [{ "name": "external" }]
    },
    "status": { "type": "string", "enum": ["ACTIVE", "INACTIVE"] }
  }
}

Utility Subgraph (Non-entity)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Common Scalars",
  "x-graphql-supergraph-name": "shared-types",
  "x-graphql-supergraph-type": "utility",
  "x-graphql-supergraph-entity": null
}

Validation Rules

Base Entity Subgraphs

Must have x-graphql-supergraph-type: "base-entity"
Must have @key directive without @extends
Must define Query type with entity resolver (when query-root: true)
Entity type name must match x-graphql-supergraph-entity

Extending Entity Subgraphs

Must have x-graphql-supergraph-type: "entity-extending"
Must have @extends directive
Must reference existing entity via x-graphql-supergraph-entity
Must use @external for fields from the owner
Must repeat the owner’s @key fields

Utility Subgraphs

x-graphql-supergraph-entity should be null or omitted
No @extends or @key required

Composition Algorithm

1. Identify all schemas with same x-graphql-supergraph-entity
2. Find base entity (x-graphql-supergraph-type: "base-entity")
3. Validate base entity has @key
4. Validate all extenders use @extends with matching @key fields
5. Route Query.entity() to base entity subgraph
6. Generate federation SDL with proper @external markers

Benefits

Benefit	Description
Explicit ownership	Clear which subgraph owns each federated entity type
Better composition	Validators understand entity relationships and dependencies
Gateway routing	API gateways know exactly which subgraph to query for each entity
Self-documenting	Metadata makes federation design explicit and discoverable
Early error detection	Catch composition errors before runtime
Backward compatible	Schemas without this metadata fall back to @key/@extends inference

SDL Linter Guide — validation rules and linting API
Federation Patterns — x-graphql-federation-* usage
ADR 0008: Subgraph/Supergraph Metadata Naming

SDL Linter & Naming Reference