Merge branch 'main' into next

docs/source/building-supergraphs/supported-subgraphs.md

@@ -16,7 +16,6 @@ The following open-source GraphQL server libraries and hosted solutions support
 | ❌                                                                                                                                                                                 | Critical functionality is NOT supported              |
 | 🔲                                                                                                                                                                                 | Additional federation functionality is NOT supported |
 
-
 ## Ballerina
 
 <table>
@@ -38,7 +37,7 @@ Github: <a href="https://github.com/ballerina-platform/module-ballerina-graphql"
 <br/>
 Type: Code first<br/>
 Stars: 144 ⭐<br/>
-Last Release: 2024-02-21<br/>
+Last Release: 2024-05-03<br/>
 <br/>
       </td>
       <td>
@@ -88,7 +87,7 @@ Last Release: 2024-02-21<br/>
 Github: <a href="https://github.com/graphql-dotnet/graphql-dotnet">graphql-dotnet/graphql-dotnet</a><br/>
 <br/>
 Type: Code first | SDL first<br/>
-Stars: 5.7k ⭐<br/>
+Stars: 5.8k ⭐<br/>
 Last Release: 2024-02-06<br/>
 <br/>
       </td>
@@ -125,8 +124,8 @@ Last Release: 2024-02-06<br/>
 Github: <a href="https://github.com/ChilliCream/graphql-platform">ChilliCream/graphql-platform</a><br/>
 <br/>
 Type: Code first | SDL first<br/>
-Stars: 4.8k ⭐<br/>
-Last Release: 2024-03-02<br/>
+Stars: 4.9k ⭐<br/>
+Last Release: 2024-04-22<br/>
 <br/>
 Federation Library: <a href="https://github.com/apollographql/federation-hotchocolate">apollographql/federation-hotchocolate&nbsp;&nbsp;<img style="display:inline-block; height:1em; width:auto;" alt="Maintained by Apollo" src="https://raw.githubusercontent.com/apollographql/apollo-federation-subgraph-compatibility/d7829ef89441c337749bf6538711a642cfa2689c/docs/assets/horizon_logo.png"/></a>
       </td>
@@ -202,7 +201,7 @@ Federation Library: <a href="https://github.com/DivvyPayHQ/absinthe_federation">
           <tr><th><code>@override</code></th><td>🟢</td></tr>
           <tr><th><code>@inaccessible</code></th><td>🟢</td></tr>
           <tr><th><code>@composeDirective</code></th><td>🟢</td></tr>
-          <tr><th><code>@interfaceObject</code></th><td>🔲</td></tr>
+          <tr><th><code>@interfaceObject</code></th><td>🟢</td></tr>
         </table>
       </td>
     </tr>
@@ -229,8 +228,8 @@ Federation Library: <a href="https://github.com/DivvyPayHQ/absinthe_federation">
 Github: <a href="https://github.com/99designs/gqlgen">99designs/gqlgen</a><br/>
 <br/>
 Type: SDL first<br/>
-Stars: 9.5k ⭐<br/>
-Last Release: 2024-02-15<br/>
+Stars: 9.6k ⭐<br/>
+Last Release: 2024-03-11<br/>
 <br/>
       </td>
       <td>
@@ -317,8 +316,8 @@ Last Release: 2022-11-11<br/>
 Github: <a href="https://github.com/netflix/dgs-framework/">netflix/dgs-framework</a><br/>
 <br/>
 Type: SDL first<br/>
-Stars: 2.9k ⭐<br/>
-Last Release: 2024-02-28<br/>
+Stars: 3.0k ⭐<br/>
+Last Release: 2024-04-30<br/>
 <br/>
 Core Library: <a href="https://github.com/graphql-java/graphql-java">GraphQL Java</a><br/>
 Federation Library: <a href="https://github.com/apollographql/federation-jvm">apollographql/federation-jvm&nbsp;&nbsp;<img style="display:inline-block; height:1em; width:auto;" alt="Maintained by Apollo" src="https://raw.githubusercontent.com/apollographql/apollo-federation-subgraph-compatibility/d7829ef89441c337749bf6538711a642cfa2689c/docs/assets/horizon_logo.png"/></a>
@@ -396,7 +395,7 @@ Github: <a href="https://github.com/ExpediaGroup/graphql-kotlin">ExpediaGroup/gr
 <br/>
 Type: Code first<br/>
 Stars: 1.7k ⭐<br/>
-Last Release: 2024-01-25<br/>
+Last Release: 2024-04-18<br/>
 <br/>
 Core Library: <a href="https://github.com/graphql-java/graphql-java">GraphQL Java</a><br/>
       </td>
@@ -434,7 +433,7 @@ Github: <a href="https://github.com/spring-projects/spring-graphql">spring-proje
 <br/>
 Type: SDL first<br/>
 Stars: 1.5k ⭐<br/>
-Last Release: 2024-02-21<br/>
+Last Release: 2024-04-16<br/>
 <br/>
 Core Library: <a href="https://github.com/graphql-java/graphql-java">GraphQL Java</a><br/>
 Federation Library: <a href="https://github.com/apollographql/federation-jvm">apollographql/federation-jvm&nbsp;&nbsp;<img style="display:inline-block; height:1em; width:auto;" alt="Maintained by Apollo" src="https://raw.githubusercontent.com/apollographql/apollo-federation-subgraph-compatibility/d7829ef89441c337749bf6538711a642cfa2689c/docs/assets/horizon_logo.png"/></a>
@@ -486,8 +485,8 @@ Federation Library: <a href="https://github.com/apollographql/federation-jvm">ap
 Github: <a href="https://github.com/apollographql/apollo-server">apollographql/apollo-server&nbsp;&nbsp;<img style="display:inline-block; height:1em; width:auto;" alt="Maintained by Apollo" src="https://raw.githubusercontent.com/apollographql/apollo-federation-subgraph-compatibility/d7829ef89441c337749bf6538711a642cfa2689c/docs/assets/horizon_logo.png"/></a><br/>
 <br/>
 Type: SDL first<br/>
-Stars: 13.6k ⭐<br/>
-Last Release: 2024-01-02<br/>
+Stars: 13.7k ⭐<br/>
+Last Release: 2024-04-18<br/>
 <br/>
 Core Library: <a href="https://www.npmjs.com/package/graphql">GraphQL.js</a><br/>
 Federation Library: <a href="https://www.npmjs.com/package/@apollo/subgraph">Apollo Subgraph&nbsp;&nbsp;<img style="display:inline-block; height:1em; width:auto;" alt="Maintained by Apollo" src="https://raw.githubusercontent.com/apollographql/apollo-federation-subgraph-compatibility/d7829ef89441c337749bf6538711a642cfa2689c/docs/assets/horizon_logo.png"/></a>
@@ -565,7 +564,7 @@ Github: <a href="https://github.com/dotansimha/graphql-yoga/">dotansimha/graphql
 <br/>
 Type: SDL first<br/>
 Stars: 8.0k ⭐<br/>
-Last Release: 2024-02-04<br/>
+Last Release: 2024-03-29<br/>
 <br/>
 Core Library: <a href="https://www.npmjs.com/package/graphql">GraphQL.js</a><br/>
 Federation Library: <a href="https://www.npmjs.com/package/@apollo/subgraph">Apollo Subgraph&nbsp;&nbsp;<img style="display:inline-block; height:1em; width:auto;" alt="Maintained by Apollo" src="https://raw.githubusercontent.com/apollographql/apollo-federation-subgraph-compatibility/d7829ef89441c337749bf6538711a642cfa2689c/docs/assets/horizon_logo.png"/></a>
@@ -603,7 +602,7 @@ Federation Library: <a href="https://www.npmjs.com/package/@apollo/subgraph">Apo
 Github: <a href="https://github.com/contra/graphql-helix">contra/graphql-helix</a><br/>
 <br/>
 Type: SDL first<br/>
-Stars: 832 ⭐<br/>
+Stars: 831 ⭐<br/>
 Last Release: 2022-07-09<br/>
 <br/>
 Core Library: <a href="https://www.npmjs.com/package/graphql">GraphQL.js</a><br/>
@@ -643,7 +642,7 @@ Github: <a href="https://github.com/mercurius-js/mercurius">mercurius-js/mercuri
 <br/>
 Type: SDL first<br/>
 Stars: 2.3k ⭐<br/>
-Last Release: 2023-12-26<br/>
+Last Release: 2024-04-22<br/>
 <br/>
 Core Library: <a href="https://www.npmjs.com/package/graphql">GraphQL.js</a><br/>
 Federation Library: <a href="https://www.npmjs.com/package/@apollo/subgraph">Apollo Subgraph&nbsp;&nbsp;<img style="display:inline-block; height:1em; width:auto;" alt="Maintained by Apollo" src="https://raw.githubusercontent.com/apollographql/apollo-federation-subgraph-compatibility/d7829ef89441c337749bf6538711a642cfa2689c/docs/assets/horizon_logo.png"/></a>
@@ -760,7 +759,7 @@ Github: <a href="https://github.com/hayes/pothos">hayes/pothos</a><br/>
 <br/>
 Type: Code first<br/>
 Stars: 2.2k ⭐<br/>
-Last Release: 2024-03-02<br/>
+Last Release: 2024-04-17<br/>
 <br/>
 Core Library: <a href="https://www.npmjs.com/package/graphql">GraphQL.js</a><br/>
       </td>
@@ -812,7 +811,7 @@ Github: <a href="https://github.com/nuwave/lighthouse">nuwave/lighthouse</a><br/
 <br/>
 Type: SDL first<br/>
 Stars: 3.3k ⭐<br/>
-Last Release: 2024-03-01<br/>
+Last Release: 2024-05-01<br/>
 <br/>
 Core Library: <a href="https://github.com/webonyx/graphql-php">webonyx/graphql-php</a><br/>
       </td>
@@ -850,7 +849,7 @@ Github: <a href="https://github.com/webonyx/graphql-php">webonyx/graphql-php</a>
 <br/>
 Type: Code first<br/>
 Stars: 4.6k ⭐<br/>
-Last Release: 2024-01-25<br/>
+Last Release: 2024-03-11<br/>
 <br/>
 Federation Library: <a href="https://github.com/Skillshare/apollo-federation-php">Skillshare/apollo-federation-php</a>
       </td>
@@ -902,7 +901,7 @@ Github: <a href="https://github.com/mirumee/ariadne">mirumee/ariadne</a><br/>
 <br/>
 Type: SDL first<br/>
 Stars: 2.1k ⭐<br/>
-Last Release: 2024-02-29<br/>
+Last Release: 2024-03-18<br/>
 <br/>
 Core Library: <a href="https://github.com/graphql-python/graphql-core">GraphQL-core 3</a><br/>
       </td>
@@ -939,7 +938,7 @@ Core Library: <a href="https://github.com/graphql-python/graphql-core">GraphQL-c
 Github: <a href="https://github.com/graphql-python/graphene">graphql-python/graphene</a><br/>
 <br/>
 Type: Code first<br/>
-Stars: 7.9k ⭐<br/>
+Stars: 8.0k ⭐<br/>
 Last Release: 2023-07-26<br/>
 <br/>
 Core Library: <a href="https://github.com/graphql-python/graphql-core">GraphQL-core 3</a><br/>
@@ -978,8 +977,8 @@ Federation Library: <a href="https://github.com/graphql-python/graphene-federati
 Github: <a href="https://github.com/strawberry-graphql/strawberry">strawberry-graphql/strawberry</a><br/>
 <br/>
 Type: Code first<br/>
-Stars: 3.7k ⭐<br/>
-Last Release: 2024-02-06<br/>
+Stars: 3.8k ⭐<br/>
+Last Release: 2024-05-01<br/>
 <br/>
 Core Library: <a href="https://github.com/graphql-python/graphql-core">GraphQL-core 3</a><br/>
       </td>
@@ -1133,8 +1132,8 @@ Last Release: 2022-11-28<br/>
 Github: <a href="https://github.com/ghostdogpr/caliban">ghostdogpr/caliban</a><br/>
 <br/>
 Type: Code first<br/>
-Stars: 925 ⭐<br/>
-Last Release: 2024-02-17<br/>
+Stars: 939 ⭐<br/>
+Last Release: 2024-04-16<br/>
 <br/>
       </td>
       <td>
@@ -1222,7 +1221,7 @@ Federation Library: <a href="https://github.com/sangria-graphql/sangria-federate
 Github: <a href="https://github.com/GraphQLSwift/Graphiti">GraphQLSwift/Graphiti</a><br/>
 <br/>
 Type: SDL first<br/>
-Stars: 521 ⭐<br/>
+Stars: 523 ⭐<br/>
 Last Release: 2023-11-15<br/>
 <br/>
       </td>
@@ -1374,8 +1373,8 @@ Last Release: 2024-02-23<br/>
 Github: <a href="https://github.com/Urigo/graphql-mesh">Urigo/graphql-mesh</a><br/>
 <br/>
 
-Stars: 3.1k ⭐<br/>
-Last Release: 2024-02-28<br/>
+Stars: 3.2k ⭐<br/>
+Last Release: 2024-04-30<br/>
 <br/>
       </td>
       <td>
@@ -1411,8 +1410,8 @@ Last Release: 2024-02-28<br/>
 Github: <a href="https://github.com/neo4j/graphql">neo4j/graphql</a><br/>
 <br/>
 Type: Code first | SDL first<br/>
-Stars: 467 ⭐<br/>
-Last Release: 2024-02-27<br/>
+Stars: 485 ⭐<br/>
+Last Release: 2024-04-30<br/>
 <br/>
 Core Library: <a href="https://www.npmjs.com/package/graphql">GraphQL.js</a><br/>
 Federation Library: <a href="https://www.npmjs.com/package/@apollo/subgraph">Apollo Subgraph&nbsp;&nbsp;<img style="display:inline-block; height:1em; width:auto;" alt="Maintained by Apollo" src="https://raw.githubusercontent.com/apollographql/apollo-federation-subgraph-compatibility/d7829ef89441c337749bf6538711a642cfa2689c/docs/assets/horizon_logo.png"/></a>

docs/source/config.json

@@ -31,8 +31,8 @@
       "Composition": "/federated-types/composition",
       "Federated directives": "/federated-types/federated-directives",
       "Sharing types (value types)": "/federated-types/sharing-types",
-      "Entities (basics)": "/entities",
-      "Entities (advanced)": "/entities-advanced",
+      "Introduction to entities": "/entities",
+      "Advanced entities": "/entities-advanced",
       "Entity interfaces": "/federated-types/interfaces",
       "Migrating from schema stitching": "/migrating-from-stitching"
     },

docs/source/entities-advanced.mdx

@@ -23,7 +23,8 @@ type User @key(fields: "username domain") {
 
 #### Nested fields in compound `@key`s
 
-Compound keys can also include nested fields. In the following example, the `User` entity's `@key` consists of both a user's `id` and the `id` of that user's associated `Organization`:
+Nested fields are often used in compound keys.
+In the following example, the `User` entity's `@key` consists of both a user's `id` and the `id` of that user's associated `Organization`:
 
 ```graphql {1} title="Users subgraph"
 type User @key(fields: "id organization { id }") {
@@ -36,6 +37,12 @@ type Organization {
 }
 ```
 
+<Note>
+
+Though nested fields are most commonly used in compound keys, you can also use a nested field as a single `@key` field.
+
+</Note>
+
 ### Multiple `@key`s
 
 When different subgraphs interact with different fields of an entity, you may need to define multiple `@key`s for the entity. For example, a Reviews subgraph might refer to products by their ID, whereas an Inventory subgraph might use SKUs.

docs/source/errors.mdx

@@ -4,13 +4,19 @@ description: Learn the error codes you can receive if composition fails.
 toc: false
 ---
 
-When Apollo Gateway attempts to compose the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, it confirms that:
+When GraphOS attempts to compose the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, it confirms that:
 
-- The subgraphs are valid
+- The subgraphs have valid GraphQL and Federation syntax
 - The resulting supergraph schema is valid
-- The gateway has all of the information it needs to execute operations against the resulting schema
+- The graph router or gateway has all of the information it needs to execute operations against the resulting schema
 
-If Apollo Gateway encounters an error, composition fails. This document lists subgraph validation and composition error codes, along with their root causes.
+If composition fails, a new supergraph schema cannot be generated. This document lists subgraph validation and composition error codes, along with their root causes.
+
+<Note>
+
+Composition may flag potential improvements or _hints_ on schemas which are technically valid. These hints aren't  errors, and are instead logged as part of the composition build step.
+To learn more, see the [composition hints doc](/federation/hints/).
+</Note>
 
 ### Errors
 
@@ -1633,4 +1639,4 @@ Subgraph definitions for a union are now merged by composition.
 </td>
 </tr>
 </tbody>
-</table>
+</table>

docs/source/federated-types/federated-directives.mdx

@@ -102,7 +102,7 @@ For more information on `@link`, see the [official spec](https://specs.apollo.de
 directive @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE
 ```
 
-Designates an object type as an [entity](../entities/) and specifies its key fields (a set of fields that the subgraph can use to uniquely identify any instance of the entity).
+Designates an object type as an entity and specifies its key fields. Key fields are a set of fields that a subgraph can use to uniquely identify any instance of the entity.
 
 ```graphql {1}
 type Product @key(fields: "id") {
@@ -112,7 +112,16 @@ type Product @key(fields: "id") {
 }
 ```
 
-You can apply multiple `@key` directives to a single entity (to specify multiple valid sets of key fields), if your subgraph library supports repeatable directives:
+<Tip>
+
+To learn best practices and advanced use cases for `@key`, refer to the following guides:
+
+- [Introduction to entities](../entities#1-define-a-key)
+- [Advanced entities](../entities-advanced)
+
+</Tip>
+
+You can apply multiple `@key` directives to a single entity to specify multiple valid sets of key fields, if your subgraph library supports repeatable directives:
 
 ```graphql {1}
 type Product @key(fields: "upc") @key(fields: "sku") {
@@ -122,8 +131,12 @@ type Product @key(fields: "upc") @key(fields: "sku") {
 }
 ```
 
+<Note>
+
 To check whether your subgraph library supports repeatable directives, see the `repeatable @key` item in [Federation-compatible subgraph implementations](../building-supergraphs/supported-subgraphs/).
 
+</Note>
+
 In Apollo Federation 2.3 and later, you can also apply `@key` to `interface` definitions to create [entity interfaces](./interfaces/). If you apply `@key` to an `interface` in earlier versions of Federation 2, a composition error occurs.
 
 #### Arguments
@@ -235,9 +248,15 @@ In Federation 1, every subgraph must extend the `Query` and `Mutation` types (if
 </MinVersion>
 
 ```graphql
-directive @shareable on FIELD_DEFINITION | OBJECT
+directive @shareable repeatable on FIELD_DEFINITION | OBJECT
 ```
 
+<Note>
+
+`@shareable` is only `repeatable` in [v2.2](../federation-versions#v22) and later.
+
+</Note>
+
 Indicates that an object type's field is allowed to be resolved by multiple subgraphs (by default in Federation 2, object fields can be resolved by only one subgraph).
 
 ```graphql {2-3}
@@ -748,7 +767,7 @@ Examples:
 </MinVersion>
 
 ```graphql
-directive @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
+directive @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION | SCHEMA
 ```
 
 Applies arbitrary string metadata to a schema location. Custom tooling can use this metadata during any step of the schema delivery flow, including composition, static analysis, and documentation. The GraphOS Enterprise [contracts feature](/graphos/delivery/contracts/) uses `@tag` with its inclusion and exclusion filters.