What do the join__ directives inside a composed federation supergraph schema record?

## What composition has to write down A federation router receives an operation written against the API schema and must turn it into a plan: call these services, in this order, sending these key fields. To do that it needs facts the API schema deliberately does not contain — which service can produce which field, how to address an entity in each service, and where each service actually lives. Composition records those facts as directives in the supergraph document, under a `join__` prefix. Continue with the livestock pedigree graph: a **registry** subgraph owning an animal's identity, a **breeding** subgraph owning lineage, a **shows** subgraph owning competition entries. ## The pieces **`@link` on the schema definition.** The supergraph opens by declaring which specifications it uses and at what version — the link spec itself, and the join spec that defines every `join__` directive below. Anything reading the document reads this first, because the directive set is versioned: what a supergraph looks like is a function of the join version stamped here, not a fixed shape. **The `join__Graph` enum.** Composition generates one enum value per subgraph, each carrying `@join__graph(name:, url:)`. The enum values are the identifiers every other join directive uses to refer to a subgraph, and the URLs are why a router needs no service discovery pass at startup and no runtime introspection of its subgraphs. **`@join__type`.** Repeatable, once per subgraph that declared the type. On an entity it carries that subgraph's `key` as a field-set string. Reading the annotations on `Animal` tells a planner: registry has it with key `id`, breeding has it with key `id`, shows has it with key `id` — so any of the three can be entered given an `id`. **`@join__field`.** Says which subgraph resolves a particular field, and carries the field's federation semantics with it — the `requires` field set when the owning subgraph needs sibling fields fetched first, `provides` when it can supply a neighbour's field inline, `external` when it merely references a field it does not own, and the source subgraph when ownership was moved with an override. **Supporting declarations.** The document also carries the directive definitions themselves and a `join__FieldSet` scalar, so that the supergraph is a valid, self-describing GraphQL document rather than one that only a particular tool can parse. ## Reading one ```graphql type Animal @join__type(graph: BREEDING, key: "id") @join__type(graph: REGISTRY, key: "id") @join__type(graph: SHOWS, key: "id") { id: ID! name: String! @join__field(graph: REGISTRY) birthDate: Date! @join__field(graph: REGISTRY) sire: Animal @join__field(graph: BREEDING) dam: Animal @join__field(graph: BREEDING) showEligible: Boolean! @join__field(graph: SHOWS, requires: "birthDate") } ``` Everything a planner needs is on the page. A document selecting `name` and `sire` needs two services. A document selecting `showEligible` needs the shows subgraph, but only after `birthDate` has been fetched from registry and passed back in the representation — the `requires` argument is what makes that ordering constraint visible without asking any service anything. Note what `id` does **not** carry: no `@join__field` at all. A field with no annotation is resolvable from every subgraph that declares the type, so the planner may take it from whichever subgraph it is already visiting rather than adding a hop. Key fields are the usual case; a value type declared identically everywhere is the other. ## The two things people get wrong **These are not GraphQL.** No `join__` directive appears in the GraphQL specification. They are Apollo Federation's composition output — a convention layered on ordinary SDL, which is precisely why an ordinary GraphQL parser can read the document without understanding a word of it. Saying "the spec defines join__type" in an interview is a tell. **They are not stable across versions.** The join specification has moved: earlier editions expressed ownership differently, including a separate owner directive that later versions dropped in favour of putting the graph on each field. Any tool that reads supergraph documents must branch on the version in the `@link`, and a supergraph composed by one version is not guaranteed to be consumable by a router built for another. ## Why you might ever read one by hand You should not edit a supergraph — it is a build artefact, and the next composition overwrites it. But reading one is the fastest answer to "which service is actually behind this field?", which is the first question worth asking when one field in a pedigree query is slow, or when a field a team swears they own turns out to be annotated with a different graph.