<article><h1>Versions</h1><p>When discussing GraphQL Federation, it is most commonly understood that there are two versions of the protocol: Version 1 (V1) and Version 2 (V2). On the surface level, this is indeed true. However, it may be more accurate to reimagine this dichotomy as a trichotomy. But to explain why, we first need to take a glance at Federation history and some of the most important differences between versions.</p><h2>What is GraphQL Federation Version 1 (V1)</h2><p>Although it is probably older as a concept, the Federation package was made public in 2019, with 1.0 released at the end of 2020. While V1 contains many of the concepts familiar to users of modern Federation, it was much more rigid and inflexible. Let's take a look.</p><h3>What is an entity?</h3><p>Many of the differences between V1 and V2 revolve around the backbone of any federated graph, namely, &quot;the entity&quot;. If you are not sure what an entity is, you can read about them in depth <a href="/learn/graphql-federation/entities">here</a>. However, a simple definition might be the following:</p><ul><li>An entity is a GraphQL Object type that defines a &quot;@key&quot; directive.</li><li>The &quot;@key&quot; directive requires the &quot;fields&quot; argument, the value of which corresponds to one (or more) fields defined on that object.</li><li>A &quot;@key&quot; directive states that the subgraph in which this object is defined includes an &quot;entity reference resolver&quot; for this primary key.</li><li>This entity reference resolver accepts the primary key as an input and is able to uniquely identify an object based on this primary key.</li><li>This allows for the resolving of an object over multiple services.</li></ul><p>For example, imagine the following subgraphs named &quot;users&quot; and &quot;posts&quot; respectively:</p><pre data-language="graphql"># users subgraph (V1)
type Query {
   users: [User!]!
}

type User @key(fields: &quot;id&quot;) {
   id: ID!
   name: String!
}
</pre><pre data-language="graphql"># posts subgraph (V1)
extend type User @key(fields: &quot;id&quot;) {
    id: ID! @external
    hasPosts: Boolean!
}
</pre><p>And the client makes this query:</p><pre data-language="graphql">query {
    users {
        id # resolved from users
        name # resolved from users
        hasPosts # resolved from posts
    }
}
</pre><p>In simplified terms, the users service sends the primary key (in this case <code>id</code>) to the posts service for each <code>User</code> entity. The posts service is then able to use this id to identify the specific user that needs to be resolved and return the relevant data (in this case <code>hasPosts</code>) for that specific user.</p><h3>Origin and extension entities</h3><p>You may have noticed in the example schemas above that the users subgraph defines an <code>Object type definition</code> for <code>User</code> while the posts subgraph defines an <code>Object type extension</code>.</p><p>In V1, there exists the concept of &quot;origin entities&quot;. Each entity must exist as a type definition (the origin) in exactly one subgraph; and all other definitions in any other subgraphs must be defined as extensions.</p><p>Unfortunately, some GraphQL providers did/do not support &quot;extension orphans&quot; (extensions that are defined without a base definition in the same subgraph). Consequently, a workaround is provided through the <code>@extends</code> directive. Where such limitations are imposed, the entity extension can be defined thus:</p><pre data-language="graphql"># posts subgraph (V1)
type User @extends @key(fields: &quot;id&quot;) {
    id: ID! @external
    hasPosts: Boolean!
}
</pre><p>An extension or an <code>@extends</code> directive makes it clear that an entity is <em>not</em> the origin.</p><p>In addition to this extension requirement, any primary keys must be defined as <code>@external</code>. However, an important note is that key fields that are defined <code>@external</code> on an extension <em>are</em> resolvable by that subgraph, unlike the usual interpretation of <code>@external</code>, <em>i.e.</em>, &quot;this field or type is not resolvable by this subgraph&quot;.</p><h3>Entity field contribution</h3><p>While entity primary key fields can be defined across multiple subgraphs with <code>@external</code>, other non-key fields can be contributed without the <code>@external</code> directive. However, any such contributed fields must not be shared; they can only be defined in one subgraph. In the example schemas above, <code>hasPosts</code> exists on <code>User</code> in only the posts subgraph. It is not part of a primary key, so it cannot be included in another subgraph. Consequently, the posts service must have <em>sole responsibility</em> for resolving the <code>hasPosts</code> field.</p><h3>Entity stubs</h3><p>If an entity does not contribute non-key fields, it is considered an &quot;entity stub&quot;. Stubs provide the minimal data to identify an entity so that other fields defined in other subgraphs can be resolved. For instance, consider the following subgraphs named &quot;api&quot; and &quot;users&quot; respectively.</p><pre data-language="graphql"># api subgraph (V1)
 type Query {
    accounts: [User!]!
 }

&quot;&quot;&quot;
This is an entity stub.
Only minimal data to identify and reference the entity is included.
In this case, just the key field 'id'.
&quot;&quot;&quot;
extend type User @key(fields: &quot;id&quot;) {
    id: ID! @external # non-origin key fields must be declared @external
    # no further fields are contributed
}
</pre><pre data-language="graphql"># users subgraph (V1)
 type User @key(fields: &quot;id&quot;) {
    id: ID!
    &quot;&quot;&quot;
    The 'name' field exists only in the users subgraph.
    Consequently, 'Query.accounts' (defined in the api subgraph) must be able to
    reach the users subgraph ('jump' through an entity reference resolver) to
    resolve the field.
    &quot;&quot;&quot;
    name: String!
}
</pre><p>And this query:</p><pre data-language="graphql">query {
    accounts { # Query.accounts is defined in api
        id # resolved from api
        name # resolved from users 
    }
}
</pre><p>Here, the entity stub <code>User</code> defined in the api subgraph provides exactly enough data to identity each user through the entity reference resolver in the users subgraph. This entity &quot;jump&quot; provides the operation entry point (<code>Query.accounts</code>) defined in the api subgraph a route to resolve the <code>User.name</code> field from the users subgraph.</p><h3>Value types (shared types)</h3><p>A &quot;value type&quot; is a type that is defined in more than one subgraph and has no &quot;origin&quot;; instead, each subgraph in which the value type is defined shares ownership for that type. Enums, Input Objects, Interfaces, Objects*, Scalars, and Unions can each be value types.</p><p><em>*Except entities, which cannot be value types, because non-key fields must be defined only once.</em></p><p>However, in V1, value types must be <em>identical</em> across the subgraphs that define them. For example, consider the following subgraph schema:</p><pre data-language="graphql">enum MyEnum {
    A
    B
}

type MyObject {
    age: Int!
    name: String!
}
</pre><p>Each subgraph that defines <code>MyEnum</code> must only define the enum values <code>A</code> and <code>B</code>. Similarly, each subgraph that defines <code>MyObject</code> must also only define the fields <code>age</code> and <code>name</code>. Moreover, each field's return type, nullability, and defined arguments (if any) must also be identical; <em>e.g.</em>, a object field that returns <code>String</code> would be incompatible with another instance of that field that returns <code>String!</code>.</p><h3>Shareability</h3><p>The <code>@shareable</code> directive was introduced in V2 and does not exist in V1. However, something extremely important to note is that <em>all</em> V1 GraphQL Object fields are considered to be intrinsically <code>@shareable</code>. This is a pivotal feature that allows V1 subgraphs to be compatible with V2 subgraphs.</p><p><em>You can find an in-depth discussion of <code>@shareable</code> <a href="/learn/graphql-federation/shareable">here</a>.</em></p><h3>@external directive</h3><p>As previously mentioned, entity key fields that are declared <code>@external</code> on a type extension will still be considered resolvable from that subgraph. However, any other <code>@external</code> declarations will be considered unresolvable from that subgraph. Moreover, in V1, there are very few rules dictating where and how <code>@external</code> can be used. The <code>@requires</code> and <code>@provides</code> directives do not require their field set references to be declared <code>@external</code> in V1 (changed in V2).</p><p><em>You can find an in-depth discussion of <code>@external</code> <a href="/learn/graphql-federation/external">here</a>.</em></p><h2>What is GraphQL Federation Version 2 (V2)</h2><p>The Graphql Federation Version 2 alpha was announced in late 2021 with 2.0 released the following year. One of the main intentions of V2 was to enhance the developer experience. V2 introduced simpler syntax, and more flexibility, in addition to important measures both to encourage cooperation across teams and protect against subgraph changes that could lead to unintended consequences (more on this in another post).</p><h3>What causes a subgraph to be interpreted as a V2 subgraph?</h3><p>The rules that govern whether a subgraph is interpreted to be a V2 subgraph a fairly straight forward:</p><ol><li>The subgraph defines an <code>@link</code> directive that imports version <code>2.0</code> or higher.</li><li>The subgraph defines/uses at least one V2 specific directive, <em>e.g.</em>, <code>@override</code> or <code>@inaccessible</code> (each V2 directive will have its own dedicated learn page).</li></ol><p>If a subgraph includes one (or both!) of these features, the subgraph will be interpreted to be a V2 subgraph (and V2 composition rules will apply to it).</p><h3>Origin entities</h3><p>The concept of an &quot;origin entity&quot; no longer exists in V2. The <em>requirement</em> of special syntax (<code>extend</code> keyword/<code>@extends</code> directive and <code>@external</code> key fields) to define an entity in more than one subgraph is no longer necessary (but still permitted for backwards compatibility). Consequently, each entity can simply be defined as a type definition, regardless of whether it contributes new fields or acts as an entity stub. Moreover, the restriction that non-key entity fields must only be defined in a single subgraph is removed.</p><h3>@external directive</h3><p>V2 composition tightens the rules behind valid use of <code>@external</code>. Types and fields that are defined <code>@external</code> must conform to one of the following rules:</p><ol><li>The field is a key field on an entity (an object that defines a <code>@key</code> directive).</li><li>The field or type is &quot;provided&quot; through a <code>@provides</code> directive on at least one path.</li><li>The field or type is &quot;required&quot; through a <code>@requires</code> directive on at least one path.</li><li>The field exists on its type to satisfy an interface.</li></ol><p>As in V1 (and to support backwards compatibility), key fields that are declared <code>@external</code> on entity extensions will be considered resolvable from the current subgraph.</p><p>Failure to conform to one of these rules will produce a composition error.</p><p><em>You can find an in-depth discussion of <code>@external</code> <a href="/learn/graphql-federation/external">here</a>.</em></p><h3>Value types (shared types)</h3><p>The restriction that value types must be identical in all subgraphs that define them is removed in V2. However, there <em>are</em> still some special composition rules (of particular note for enums, which you can read about <a href="/learn/graphql-federation/enums">here</a>) that govern whether different value types are compatible with one another. For example, consider the following two subgraphs:</p><pre data-language="graphql"># api subgraph (V2)
type Query {
  users: [User!]!
}

type User @key(fields: &quot;id&quot;) {
  id: ID!
  name: String @shareable
  age: Int!
}
</pre><pre data-language="graphql"># users subgraph (V2)
type User @key(fields: &quot;id&quot;) {
  id: ID!
  name: String! @shareable
  isAuthenticated: Boolean!
}
</pre><p>When composed, the federated graph would look like so:</p><pre data-language="graphql">type Query {
  users: [User!]!
}

type User {
  id: ID!
  name: String
  age: Int!
  isAuthenticated: Boolean!
}
</pre><p>Although the users service returns <code>String!</code> from <code>User.name</code>, the api service returns <code>String</code>. Consequently, the least restrictive return type will be the type that appears in the federated graph (to support possible nullability from the api service). However, each instance of a single shared field must be a superset (equally or less restrictive) of the most restrictive return type. For instance, while <code>[Int]</code> and <code>[Int!]!</code> would be compatible with one another, <code>[Int!]</code> and <code>[Int]!</code> would not be compatible (and would result in a composition error).</p><p><em>You can read more about field merging <a href="/learn/graphql-federation/fields">here</a>.</em></p><p>Furthermore, should, for example, an Object type be differently defined across subgraphs, all fields defined on that object, no matter the subgraph in which the field is defined nor the operation path that requests the field, must be fully resolvable at <em>all</em> times.</p><p><em>For an in depth discussion on field resolvability, see <a href="/learn/graphql-federation/resolvability">this page</a>.</em></p><h2>FieldSet validity changes</h2><p>The are (currently) three directives that use the <code>FieldSet</code> scalar: <code>@key</code>, <code>@provides</code>, and <code>@requires</code>. A <code>FieldSet</code> is essentially a GraphQL selection set without the first set of encompassing curly braces (<code>{</code> and <code>}</code>). In V1, a <code>FieldSet</code> could define top-level composite types. For example:</p><pre data-language="graphql">type User @key(fields: &quot;account&quot;) {
  account: Account!
  name: String!
}

type Account {
  id: ID!
  name: String!
}
</pre><p>However, in V2, composite types within a <code>FieldSet</code> without selections are invalid and will result in a composition error. Each and every selection within a <code>FieldSet</code> must end with a leaf type (an Enum or a Scalar). Consequently, this would be a breaking change when composing a V1 subgraph that defines such a <code>FieldSet</code> with V2 composition. So, to fix the schema above, we would now be required to select at least one leaf on <code>User.account</code>. For example:</p><pre data-language="graphql">type User @key(fields: &quot;account { id }&quot;) {
  account: Account!
  name: String!
}

type Account {
  id: ID! # this is field is a Scalar type, so it is a leaf, and is valid to end the selection in the FieldSet
  name: String! # another possibility
}
</pre><h2>The &quot;third&quot; GraphQL Federation version</h2><p>Up to this point, we've discussed the GraphQL Federation version dichotomy. So what is this elusive &quot;third version&quot;? This is a concept to which we at WunderGraph refer as &quot;Version 1.5&quot;.</p><p>When Federation Version 2 was announced, it was advertised to be backwards compatible, requiring no major changes to existing subgraphs. But as we have already discussed, V1 was much more rigid and inflexible than V2. So, in order to accommodate for the disparity of rules (and their strictness), some compromises had to be made. This might be broken down like so:</p><h3>&quot;True&quot; Version 1</h3><p>A subgraph that is compatible with the routers and gateways that existed before (or do not support) the concept of GraphQL Federation Version 2.</p><h3>Version 1.5</h3><p>A subgraph that is interpreted to be a V1 subgraph by a V2 router/gateway but would not be compatible with non-V2 router and gateways.</p><h3>Version 2</h3><p>A subgraph that is interpreted to be a V2 subgraph by a V2 router/gateway.</p><h2>An example of Version 1.5 subgraphs</h2><p>Consider the following two (composable) subgraphs named &quot;users&quot; and &quot;posts&quot;, respectively:</p><pre data-language="graphql"># users subgraph
type Query {
    users: [User!]!
}

type User @key(fields: &quot;id&quot;) {
    id: ID!
    username: String!
    details: Details!
}

type Details {
    age: Int!
    name: String!
    region: Region!
}

enum Region {
    NORTH
    SOUTH
}
</pre><pre data-language="graphql"># posts subgraph
type User @key(fields: &quot;id&quot;) {
    id: ID!
    details: Details!
    posts: [Post!]!
}

type Post {
    id: ID!
    content: String!
    region: Region!
}

type Details {
    favoritePost: Post
}

enum Region {
    EAST
    WEST
}
</pre><p>Both of these subgraphs would be interpreted to be V1 subgraphs for the following reasons:</p><ol><li>No <code>@link</code> directive that imports from <code>2.0</code> or higher.</li><li>No usage of &quot;V2-only&quot; directives, <em>e.g.</em>, <code>@inaccessible</code>.</li></ol><p>You may also have noticed that <code>User.details</code> does not require the <code>@shareable</code> directive to successfully compose, which corresponds with rules that all V1 fields are intrinsically considered to be <code>@shareable</code>. However, these subgraphs also exhibit features that would not be permissible under strict V1 composition rules. For instance:</p><ol><li>The <code>User</code> entity defines a non-key field in more than one subgraph (<code>User.details</code>).</li><li>The <code>Details</code> object is a value (shared) type but is not identically defined across subgraphs.</li><li>The <code>Region</code> enum is a value (shared) type but is not identically defined across subgraphs.</li><li>Both subgraphs appear to define an &quot;origin entity&quot;; <em>i.e.</em>, neither subgraph defines an entity extension nor any <code>@external</code> key fields.</li></ol><p>So, while these two subgraphs would be interpreted to be V1 subgraphs by V2 composition, they would not be compatible with V1 composition. What results is a sort of hybridization that is not quite V1 and not quite V2; hence, &quot;V1.5&quot;.</p><h1>Conclusion</h1><p>If you're using a router/gateway that supports GraphQL Federation Version 2 (such as WunderGraph Cosmo), you probably don't need to worry about your V1-interpreted subgraphs' being &quot;true&quot; V1 subgraphs. However, if you ever needed to use or test against legacy software and versions, it <em>is</em> important to bear in mind that V1-interpreted subgraphs that V2 composition deems valid are not necessarily valid with &quot;true&quot; V1. So, in certain cases, modifications to subgraphs would be necessary for V1 composition to be successful.</p><p>On the other hand, it is always necessary to understand when and why a subgraph would be interpreted as either V1 or V2. When migrating a V1 subgraph over to V2, the simple addition of a V2-only directive could break composition due to rules surrounding <code>@shareable</code> and <code>@external</code>. And in some cases, a V1 subgraph that was compatible with V1 composition might need tweaks to be composable with V2 composition (for example, a <code>FieldSet</code> that defines composite types without leaf selections).</p></article>

What is a GraphQL Federation version? How many versions are there?

GraphQL Federation Versions

<article><h1>@shareable Directive</h1><p>The <code>@shareable</code> directive is a federation V2-only directive. Examples and usages are outlined herein.</p><h2>Definition</h2><pre data-language="graphql">directive @shareable ON FIELD_DEFINITION | OBJECT
</pre><h2>FIELD_DEFINITION declaration</h2><p>If the <code>@shareable</code> directive is declared on a field definition, the same field can be defined on the same named type from multiple subgraphs. All subgraphs that define a field in this way must be be capable of resolving that field. The resolver should also be identical across the subgraphs. For example:</p><pre data-language="graphql"># subgraph 1
directive @shareable ON FIELD_DEFINITION | OBJECT

type User {
  id: ID! @shareable
}

# subgraph 2
directive @shareable ON FIELD_DEFINITION | OBJECT

type User {
  id: ID! @shareable
}
</pre><p>In the example above, two subgraphs define the type <code>User</code> with the field <code>id</code>. This is valid because <code>id</code> has been declared <code>@shareable</code>; <em>i.e</em>, that the field <code>id</code> can be resolved from multiple subgraphs.</p><h2>OBJECT declaration</h2><p>If the <code>@shareable</code> directive is declared on an object type, all fields currently* defined on that type will be declared <code>@shareable</code>. This is the same as declaring the <code>@shareable</code> directive separately on each current* field definition.</p><p>*If an object is extended, unless a field definition on the object extension is explicitly declared <code>@shareable</code>, it will not be considered shareable on the original object. This is true even if that object was originally declared <code>@shareable</code>. An example is shown below:</p><pre data-language="graphql"># subgraph 1
directive @shareable ON FIELD_DEFINITION | OBJECT

# The whole object is declared shareable
type User @shareable {
    name: String!
}

extend type User {
    age: Int!
}

extend type User {
    id: ID! @shareable
}

# normalized subgraph
directive @shareable ON FIELD_DEFINITION | OBJECT

# Although the original object was declared shareable, because the extension does
# not declare the field &quot;age&quot; as shareable, the object-wide shareable directive
# is no longer applied
type User {
    name: String! @shareable
    age: Int!
    id: ID! @shareable
}
</pre><p>In the example above, the <code>User</code> object has been declared <code>@shareable</code>. However, the first extension with the field age is not declared <code>@shareable</code>. The second extension with the field id is declared <code>@shareable</code>.</p><p>Consequently, when these extensions are applied, the OBJECT location <code>@shareable</code> declaration is no longer applied, and the declarations are moved only to the relevant fields. This produces the normalized <code>User</code> type where <code>name</code> and <code>id</code> are shareable but <code>age</code> is not.</p><h2>Federation V1 subgraphs and shareable</h2><p>By default, all field definitions in a V1 subgraph are treated as <code>shareable</code>. For example:</p><pre data-language="graphql"># V1 subgraph
type User {
    name: String!
}

# V2 subgraph 1
directive @shareable ON FIELD_DEFINITION | OBJECT

type User {
    name: String! @shareable
}

# V2 subgraph 2
directive @shareable ON FIELD_DEFINITION | OBJECT

type User @shareable {
    name: String!
}
</pre><p>In the example above, the V1 subgraph cannot declare anything as <code>@shareable</code> (this directive is V2 exclusive). Consequently, for compatibility with V2 subgraphs, it is considered shareable by default. However, any V2 subgraph that declares a field that exists on the same type in another subgraph must declare the <code>@shareable</code> directive on the object or on that field definition. Failure to do so will lead to a composition error.</p><h2>Entity keys and shareable</h2><p>Fields that comprise part of at least one of the entity's primary keys are automatically considered shareable. For example:</p><pre data-language="graphql"># subgraph 1
directive @key(fields: String!) repeatable ON OBJECT
directive @shareable ON FIELD_DEFINITION | OBJECT

type User @key(fields: &quot;id&quot;) {
    id: ID!
    name: String! @shareable
}

# subgraph 2
directive @key(fields: String!) repeatable ON OBJECT
directive @shareable ON FIELD_DEFINITION | OBJECT

type User @key(fields: &quot;id&quot;) {
    id: ID!
    name: String! @shareable
}
</pre><p>In the example above, <code>id</code> is part of at least one of the entity's primary key. Consequently, <code>id</code> is automatically considered shareable without any further declaration. However, the field name, which is not part of a primary key, must be declared with the <code>@shareable</code> directive.</p><h2>Shared root type fields: resolving differently defined objects</h2><p><em>Caveat: It is highly recommended only to use <a href="/learn/graphql-federation/entities">entities</a> to resolve an object type over multiple subgraphs.</em></p><p>Imagine we have the following two subgraphs:</p><pre data-language="graphql"># subgraph-1
type Query {
    friends: [Friend!]!
}

type Friend {
    name: String!
}
</pre><pre data-language="graphql"># subgraph-2
type Friend {
    age: Int!
}
</pre><p>These subgraphs will fail to produce a federated graph. This is because the field <code>age</code> cannot be resolved for <code>Friend</code> when querying friends from subgraph-1.</p><p>If a non-entity object type is defined differently across subgraphs, there is only one solution that ensures the type is always fully resolvable: shared root type fields.</p><p>In the example above, each subgraph that differently defines the type <code>Friend</code> should include all root type fields that can resolve <code>Friend</code>. Consequently, the following changes would allow a federated graph to be composed:</p><pre data-language="graphql"># subgraph-1
type Query {
    friends: [Friend!]! @shareable
}

type Friend {
    name: String!
}
</pre><pre data-language="graphql"># subgraph-2
type Query {
    friends: [Friend!]! @shareable
}

type Friend {
    age: Int!
}
</pre><p>First, the <code>Query.friends</code> root type field defined in subgraph-1 is declared <code>@shareable</code>; <em>i.e.</em>, it can be resolved from multiple subgraphs. Next, this shareable root type field is added to subgraph-2. Now it is possible to resolve all fields of <code>Friend</code> from the <code>Query.friend</code> root type field.</p><p>Note that all such root type fields that can resolve <code>Friend</code> (be it nested or otherwise) would need to be defined (with <code>@shareable</code>) in each subgraph.</p></article>

What is the V2 @shareable directive? How does it work?

GraphQL Federation Version 2 @shareable Directive

GraphQL Federation Entities

What are enums? How do enums defined across subgraphs compose into a federated graph?

Enums

What is the V2 @external directive? How does it work?

GraphQL Federation Version 2 @external Directive

What are fields? How do instances of the same field defined across subgraphs compose into a federated graph?

Fields

What is resolvability? When is a field unresolvable? What could cause a field to be unresolvable?

GraphQL Federation Resolvability

Topics that deep-dive into all things GraphQL Federation-related.

Everything GraphQL Federation

What you’ll learn

Prerequisites

Chapters