Proposal: Simplified Key Definition in GraphQL Composite Schemas

[smyrick]

Copying from graphql/composite-schemas-wg#440

Introduction

This proposal suggests starting with a simpler definition of keys in GraphQL composite schemas by restricting keys to a single value. This approach aims to simplify the composite schema specification, the gateway-subgraph contract, and gateway implementations.

Proposal

Simplified Key Definition
Instead of complex key definitions, we propose using a single scalar value for keys:

type Foo {
    id: ID! @key
    v: String
}

or

type Foo implements Node {
    id: ID!
    v: String
}

Handling Complex Keys

For cases where the underlying model requires a more complex key, subgraph tooling can provide a helper method to create the composite-schemas key. An object-level key directive could be used as a convenience, interpreted only by the subgraph server:

type Foo @key(fields: "fooId") {
    fooId: String!
    v: String
}

The subgraph's GraphQL framework can automatically add the composite key:

type Foo {
    id: ID! # auto-generated
    fooId: String!
    v: String
}

This feature would be optional and could help subgraphs using the current spec to be grandfathered in.

Pros

• Simpler Composite Schema Spec: Easier to understand and implement.
• Simpler Gateway-Subgraph Contract: Reduces complexity in interactions. Easier troubleshooting.
• Simpler Gateway Implementations: Less complex, potentially fewer bugs.
• Batch Lookup: Simplifies batch lookup, eliminates need for GraphQL spec changes
• Simple cases are easy. Complex cases are possible: Only subgraphs that desired complex keys need to take on any additional complexity

Cons

• Server-Side Tooling: In order to have the same level of key flexibility and convenience, additional tooling is required.
• Compatibility with Fed2: Subgraphs using complex keys with current Fed2 spec would need adaptation (though this could be done automatically through tooling).