What data belongs on a GraphQL connection's edge rather than on the node it wraps?

## The edge is the relationship, not a wrapper Newcomers read `edges { node { ... } }` as pure ceremony — two levels of unwrapping to get at the thing you wanted. That reading is why edge fields are the most under-used part of the connection convention. The correct reading comes from the graph vocabulary the names were taken from: a node is a vertex, an edge is the line joining two vertices, and an edge can carry its own attributes. In a GraphQL connection, the parent object is one vertex, each item is another, and the edge object standing between them is the place to describe the *link*. ## A worked example An airline seat-map graph has two obvious types, and one non-obvious question. ```graphql type Seat { designator: String! pitchInches: Int! hasPower: Boolean! isExitRow: Boolean! } ``` These are facts about a physical seat in an aircraft's cabin configuration. Seat `14C` has 31 inches of pitch on every flight that aircraft ever operates. Now: what does seat 14C *cost*, and is it *available*? Neither is a property of the seat. Both are properties of "seat 14C **on flight KJ118 departing 06:42**". Put them on the edge: ```graphql type FlightSeatEdge { node: Seat! cursor: String! priceCents: Int! status: SeatStatus! heldUntil: DateTime } ``` Now the same `Seat` can appear under two flights with different prices, and nothing contradicts itself. A well-known everyday example of the same modelling is a membership: a person's `joinedAt` and `role` belong to the person-in-that-group pairing, not to the person. ## The decision test Ask: **does this value change depending on which parent I traversed from?** - *Yes* → edge field. Price per flight, status per flight, the cursor itself, a relevance score from the search that produced this page, the timestamp the link was created. - *No* → node field. Designator, pitch, power outlet, exit-row. - *Neither — it describes the whole slice* → connection field, not edge and not node. ## What goes wrong when you get it wrong **Pushing relationship data onto the node** is the common error, usually because a resolver already has the joined row in hand and it is one line cheaper to expose it there. The damage shows up later: - The same object now answers differently depending on the path taken to reach it, which is precisely the invariant a **normalized client cache** relies on. Such a cache stores one entry per object identity and merges fields into it; two flights writing different `priceCents` into the same `Seat` entry means the last write wins and one screen silently shows the other flight's price. This is one of the nastiest bug classes in a GraphQL client because it is invisible in the network payloads — both responses were correct. - The field cannot be answered when the object is fetched on its own, outside any connection, so it must be nullable and mysteriously null in half the contexts it appears in. **Hiding intrinsic data on the edge** is the rarer, milder mistake. It means clients cannot reuse a fragment on `Seat` — a fragment can only select edge fields inside a connection, so a seat-detail component and a seat-list component stop sharing one selection. ## Costs of edge fields, honestly Edge fields are not free, which is why some teams avoid them: - **They are unreachable outside a connection.** If a client already has a seat and wants its price on a given flight, there is no edge to select; it must re-page the connection or you must add another field. Object-refetch mechanisms return the object, and an edge is not one. - **They fragment client code.** A component that renders a seat now needs data from two levels of the response, so the fragment it declares must be spliced in at the edge level rather than the node level. - **Some tooling ignores them.** Codegen and cache normalization handle nodes well because nodes have identity; edges usually do not, so an edge is treated as an anonymous embedded object. ## The alternative: promote the relationship to a type When the relationship grows enough fields, behaviour, or an identity of its own, the honest move is to stop treating it as edge decoration and make it a first-class object. A `SeatAssignment` type — with its own identifier, its own price, its own status, and a `seat: Seat!` field — becomes the connection's node, and the edge falls back to just `node` and `cursor`. The signal to do this is when you want to fetch, mutate or subscribe to the pairing directly. Mutations are the clearest tell: you can return an updated `SeatAssignment` from a mutation, but there is no sensible way to return "an edge" from one. ## In an interview The question is usually asked as "what is the edge for?" and a weak answer is "to hold the cursor". A strong answer names the cursor as one instance of a general rule — the edge holds facts about the link — gives a concrete second example, and then shows judgement about when the relationship deserves its own type instead.