In Apollo Federation, why does composition fail when two subgraphs declare the same field with different types?

## Composition is a merge, and a merge needs one answer Apollo Federation splits one client-facing graph across independently deployed services. Each service publishes a **subgraph schema**; a composition step reads all of them together and produces a single **supergraph schema**, which the router uses to plan queries and from which the client-facing API schema is derived. Composition is not a concatenation of files. Wherever several subgraphs mention the same type, it has to merge those declarations into one, and every merged field carries exactly one type in the result. That is the whole reason a type mismatch is fatal. Take a farm-sensor graph, where a Devices subgraph owns the hardware and an Agronomy subgraph owns readings: ```graphql # Devices subgraph type Sensor @key(fields: "id") { id: ID! lastCalibratedAt: String! } # Agronomy subgraph type Sensor @key(fields: "id") { id: ID! lastCalibratedAt: DateTime! } ``` There is no type the API schema could publish for `lastCalibratedAt` that is honest about both. Publishing `String!` withdraws a parsing and serialization contract Agronomy's clients rely on; publishing `DateTime!` promises validation the Devices subgraph never performs. So composition stops, names the field and the subgraphs that disagree, and produces nothing. This is the property people mean when they say composition **fails closed**: the output is a whole supergraph or a list of errors, never a partial supergraph with the offending field quietly dropped. ## Nullability is a different question from the named type Candidates often collapse the two into one rule — "the types must be identical" — and that overshoots. Wrapper differences (`!` and lists) are handled by a variance rule, because there is a defensible direction for each position: - A field the client **reads**. The published type must describe every value any subgraph could return. If one subgraph says `String!` and another `String`, a client can be handed null, so the safe merge is the nullable one. Outputs widen. - An argument the client **supplies**. The published type must be accepted by every subgraph that will receive the value. If one subgraph takes `Int` and another `Int!`, publishing the nullable form would let a client send null into a subgraph that rejects it, so the safe merge is the non-null one. Inputs narrow. Two different named types never merge under either rule. `String` and `DateTime` are unrelated leaf types; there is no widening that covers both and no narrowing either satisfies. The same is true of an object type against a scalar, or two different enums. ## Arguments drift as well as return types The second family of mismatch is the argument list on a shared field: ```graphql # Devices subgraph readings(since: DateTime, limit: Int = 50): [Reading!]! # Agronomy subgraph readings(since: DateTime, limit: Int = 50, unit: ReadingUnit!): [Reading!]! ``` An argument only some subgraphs declare cannot be honoured everywhere, so it does not survive into the client-facing schema — clients simply cannot pass `unit`, and composition usually says so as a hint rather than an error. If that argument is **required** in the subgraph that declares it, there is no such escape: the router would have to invent a value for the subgraphs that never asked for one, so composition fails outright. Default values that differ are the quiet version of the same problem — the published default is one of them, and the other subgraph's callers change behaviour. ## Where these conflicts actually come from In a 62-subgraph supergraph, most type mismatches are not on entities at all. They are on small shared shapes — a `GeoPoint`, a `Measurement`, a `TimeWindow` — that several teams copied into their own SDL and then edited independently. One team makes `Measurement.unit` non-null after backfilling their store; another adds a field; a third changes a timestamp from `String` to a custom scalar. Nothing is wrong in any single repository, and each subgraph is a perfectly valid GraphQL schema on its own. Composition is the first place the divergence is visible, which is why it should run on every subgraph change rather than at release time. ## What is specified here, and what is not None of this is in the GraphQL specification. GraphQL knows nothing about subgraphs, supergraphs or merging; it validates one schema at a time. Merge rules, satisfiability and the fail-closed behaviour come from Apollo Federation's composition specification, and the exact wording and codes of the errors are implementation detail — quote the rule in an interview, not an error code you half-remember. ## Fixing one The repair is a conversation between the two owners, not a flag. In practice: converge on one type additively — add the new field or the new scalar alongside the old one, migrate clients, then delete the old — because a same-day flip in both subgraphs only works if both deploy at once. Or give the field a single owner and let the other subgraph reference the entity by key instead of redeclaring the field. For the copied value types, the durable fix is one generated source of truth for the shared shapes, so there is only ever one definition to drift from.