# federation v1 definition
directive @key(fields: _FieldSet!) repeatable on OBJECT | INTERFACE

# federation v2 definition
directive @key(fields: _FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE

The @key directive is used to indicate a combination of fields that can be used to uniquely identify and fetch an object or interface. Key directive should be specified on the root entity type as well as all the corresponding federated (i.e. extended) types. Key fields specified in the directive field set should correspond to a valid field on the underlying GraphQL interface/object. Federated extended types should also instrument all the referenced key fields with @external directive.

Example: Given following entity type definition

@KeyDirective(FieldSet("id"))
class Product(val id: String, val name: String)

it will generate following schema

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

Entity types can be referenced from other subgraphs without contributing any additional fields, i.e. we can update type within our schema with a reference to a federated type. In order to generate a valid schema, we need to define stub for federated entity that contains only key fields and also mark it as not resolvable within our subgraph. For example, if we have Review entity defined in our supergraph, we can reference it in our product schema using following code

@KeyDirective(fields = FieldSet("id"))
class Product(val id: String, val name: String, val reviews: List<Review>)

// review stub referencing just the key fields
@KeyDirective(fields = FieldSet("id"), resolvable = false)
class Review(val id: String)

which will generate

type Product @key(fields: "id") {
  id: String!
  name: String!
  reviews: [Review!]!
}

type Review @key(fields: "id", resolvable: false) {
  id: String!
}

This allows end users to query GraphQL Gateway for any product review fields and they will be resolved by calling the appropriate subgraph.