Shared types across subgraphs in GraphQL - Deep Dive

Overview - Shared types across subgraphs

What is it?

Shared types across subgraphs are data structures or schemas used in multiple parts of a distributed GraphQL system called subgraphs. Each subgraph is like a small service that handles part of the overall data. Sharing types means these subgraphs agree on common data shapes to communicate smoothly. This helps keep data consistent and avoids confusion when different parts of the system talk to each other.

Why it matters

Without shared types, each subgraph might define the same data differently, causing errors and confusion when combining data. This would make the system fragile and hard to maintain. Shared types solve this by creating a common language, so all subgraphs understand the data the same way. This leads to reliable, scalable systems where teams can work independently but still fit their work together perfectly.

Where it fits

Before learning about shared types, you should understand basic GraphQL concepts like schemas, types, and queries. You should also know what subgraphs and federated GraphQL architectures are. After this, you can explore advanced federation features, schema stitching, and how to optimize queries across multiple subgraphs.

Mental Model

Core Idea

Shared types across subgraphs are like a common dictionary that all parts of a distributed GraphQL system use to speak the same language about data.

Think of it like...

Imagine a group of friends from different countries who want to play a game together. They all agree to use the same rulebook written in a language everyone understands. This rulebook is like the shared types, ensuring everyone plays by the same rules and understands each other perfectly.

┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│   Subgraph A  │      │   Subgraph B  │      │   Subgraph C  │
│  (uses types) │      │  (uses types) │      │  (uses types) │
└──────┬────────┘      └──────┬────────┘      └──────┬────────┘
       │                      │                      │
       │                      │                      │
       │      ┌───────────────▼───────────────┐      │
       └─────▶│       Shared Types Library     │◀─────┘
              │  (common definitions/schema)  │
              └───────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding GraphQL Subgraphs

Concept: Introduce what subgraphs are in a federated GraphQL system.

A subgraph is a small GraphQL service that owns part of the overall data schema. Instead of one big GraphQL server, the system is split into multiple subgraphs, each responsible for specific data. These subgraphs work together to form a complete API.

Result

You know that a federated GraphQL system is made of multiple subgraphs, each with its own schema part.

Understanding subgraphs is essential because shared types exist to connect these separate pieces into one smooth system.

2

Foundation

Basics of GraphQL Types

Concept: Explain what GraphQL types are and why they matter.

GraphQL types define the shape of data, like objects, fields, and their data types (string, number, etc.). They tell clients what data they can ask for and what to expect back. Types make APIs clear and predictable.

Result

You understand that types are the blueprint for data in GraphQL schemas.

Knowing types helps you see why sharing them across subgraphs avoids confusion and errors.

3

Intermediate

Why Share Types Across Subgraphs

🤔Before reading on: do you think each subgraph should define its own types independently or share common types? Commit to your answer.

Concept: Introduce the need for shared types to keep data consistent across subgraphs.

If each subgraph defines the same data differently, combining data from multiple subgraphs becomes error-prone. Shared types create a single source of truth for common data, so all subgraphs agree on what the data looks like.

Result

You see that shared types prevent mismatches and make the system reliable.

Understanding the problem shared types solve helps you appreciate their role in federated GraphQL.

4

Intermediate

How Shared Types Are Defined

🤔Before reading on: do you think shared types are copied into each subgraph or referenced from a central place? Commit to your answer.

Concept: Explain the methods to define and share types across subgraphs.

Shared types can be defined in a common schema file or package that each subgraph imports. Alternatively, GraphQL federation uses directives like @key and @extends to mark types as shared and extend them across subgraphs.

Result

You learn practical ways to implement shared types in your GraphQL projects.

Knowing how shared types are defined helps you design federated schemas that scale and stay consistent.

5

Intermediate

Extending Shared Types in Subgraphs

Concept: Show how subgraphs can add fields to shared types without breaking consistency.

Subgraphs can extend shared types by adding new fields using federation features. For example, one subgraph owns the User type, and another adds an email field. This lets teams work independently while sharing core data.

Result

You understand how to grow shared types safely across subgraphs.

Knowing how to extend shared types prevents duplication and supports modular development.

6

Advanced

Resolving Conflicts in Shared Types

🤔Before reading on: do you think conflicts in shared types cause errors or are automatically resolved? Commit to your answer.

Concept: Discuss what happens when subgraphs disagree on shared type definitions and how to handle it.

Conflicts can occur if subgraphs define the same type differently or with incompatible fields. Tools like Apollo Federation detect these conflicts during schema composition and require developers to fix them by aligning definitions or using directives properly.

Result

You know how to identify and fix shared type conflicts in federated schemas.

Understanding conflict resolution is key to maintaining a healthy federated GraphQL system.

7

Expert

Performance Implications of Shared Types

🤔Before reading on: do you think shared types improve or slow down query performance? Commit to your answer.

Concept: Explore how shared types affect query planning and execution in federated GraphQL.

Shared types enable the gateway to plan queries efficiently by knowing which subgraph owns which fields. However, complex shared types with many extensions can increase query planning time and network calls. Experts balance shared type design to optimize performance.

Result

You appreciate the trade-offs between shared type richness and system speed.

Knowing performance impacts guides better schema design and system tuning in production.

Under the Hood

Underneath, shared types are merged during schema composition by the GraphQL gateway. The gateway reads each subgraph's schema, identifies shared types marked with federation directives, and combines their fields into a single unified type. This merged schema is what clients query against. The gateway also routes parts of queries to the correct subgraph based on ownership of fields in shared types.

Why designed this way?

This design allows teams to own parts of the schema independently while still presenting a single API to clients. It balances modular development with a unified interface. Alternatives like schema stitching were more brittle and less scalable. Federation with shared types was created to solve these problems in large distributed systems.

┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│  Subgraph A   │      │  Subgraph B   │      │  Subgraph C   │
│  Schema with  │      │  Schema with  │      │  Schema with  │
│  shared types │      │  shared types │      │  shared types │
└──────┬────────┘      └──────┬────────┘      └──────┬────────┘
       │                      │                      │
       │                      │                      │
       ▼                      ▼                      ▼
    ┌───────────────────────────────────────────────┐
    │           Gateway Schema Composition           │
    │  Merges shared types into unified schema       │
    └───────────────────────────────────────────────┘
                           │
                           ▼
                ┌─────────────────────┐
                │  Unified GraphQL API │
                └─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think shared types mean copying the same type code into every subgraph? Commit yes or no.

Common Belief: Shared types require duplicating the same type definitions in every subgraph's schema.

Reality: Shared types are defined once and referenced or extended by subgraphs, avoiding duplication.

Why it matters: Duplicating types leads to inconsistencies and harder maintenance, defeating the purpose of sharing.

Quick: Do you think shared types automatically merge conflicting fields without errors? Commit yes or no.

Common Belief: The system automatically resolves any conflicts in shared types between subgraphs.

Reality: Conflicts cause schema composition errors that must be fixed by developers.

Why it matters: Ignoring conflicts can break the API and cause runtime failures.

Quick: Do you think shared types slow down the GraphQL system significantly? Commit yes or no.

Common Belief: Using shared types always makes the system slower due to complexity.

Reality: Shared types help optimize query planning but can add overhead if overused or poorly designed.

Why it matters: Misunderstanding this can lead to avoiding shared types and creating fragile schemas.

Quick: Do you think shared types mean all subgraphs must share all their data? Commit yes or no.

Common Belief: Shared types force all subgraphs to expose the same data fields everywhere.

Reality: Subgraphs share only agreed types and can extend or limit fields independently.

Why it matters: Believing otherwise limits flexibility and modular design.

Expert Zone

1

Shared types can be extended with @key directives to define ownership and enable entity resolution across subgraphs.

2

The gateway uses shared types to split queries intelligently, but complex extensions can cause query plan bloat.

3

Versioning shared types carefully is crucial to avoid breaking downstream subgraphs and clients.

When NOT to use

Avoid shared types in small, simple GraphQL setups where federation adds unnecessary complexity. Instead, use a single schema or schema stitching for simpler composition.

Production Patterns

In production, teams define core shared types in a central package and use federation directives to extend them. CI pipelines validate schema compatibility to prevent conflicts before deployment.

Connections

Microservices Architecture

Shared types in GraphQL federation are similar to shared contracts or interfaces in microservices.

Understanding shared types helps grasp how microservices communicate with agreed contracts to avoid integration errors.

API Versioning

Managing shared types relates closely to API versioning strategies to maintain backward compatibility.

Knowing how to evolve shared types without breaking clients mirrors best practices in API versioning.

Linguistics - Common Language

Shared types act like a common language or dialect that different groups use to understand each other.

Recognizing this connection highlights the importance of agreed definitions for clear communication in any system.

Common Pitfalls

#1 Defining the same type differently in multiple subgraphs causing schema conflicts.

Wrong approach:

type User { id: ID! name: String! } in Subgraph A

type User { id: ID! username: String! } in Subgraph B

Correct approach:

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

extend type User @key(fields: "id") { username: String! }

Root cause:

Misunderstanding that shared types must have a single source of truth and consistent definitions.

#2 Copy-pasting shared type definitions into each subgraph instead of referencing or extending.

Wrong approach:

Each subgraph has a full copy of the User type schema without federation directives.

Correct approach:

Define User type once with @key directive and extend it in other subgraphs as needed.

Root cause:

Lack of knowledge about federation directives and schema composition.

#3 Ignoring schema composition errors caused by conflicting shared types.

Wrong approach:

Deploying subgraphs with incompatible shared type fields without fixing errors.

Correct approach:

Run schema composition checks and resolve conflicts before deployment.

Root cause:

Assuming the system will handle conflicts automatically.

Key Takeaways

Shared types are the common data definitions that multiple GraphQL subgraphs use to communicate clearly and consistently.

They prevent errors and confusion by ensuring all parts of a federated system agree on data shapes.

Shared types are defined once and extended or referenced by subgraphs using federation directives like @key and @extends.

Proper management of shared types, including conflict resolution and versioning, is essential for a healthy, scalable GraphQL federation.

Understanding shared types connects to broader concepts like microservices contracts and API versioning, highlighting their role in system integration.