Entity Resolution

## The shape on the wire When a query plan needs fields of an object that another service owns, the router does not call that subgraph's ordinary root fields. It calls one reserved root field, `_entities`, and hands it a list of *representations* — its minimal description of the objects it already has a handle on. ```graphql query($representations: [_Any!]!) { _entities(representations: $representations) { ... on Trial { enrollmentTarget primaryOutcome } } } ``` ```json {"representations": [ {"__typename": "Trial", "nctId": "NCT-04471"}, {"__typename": "Trial", "nctId": "NCT-05128"} ]} ``` ## The two things it always carries **`__typename`.** `_entities` returns `[_Entity]!`, and `_Entity` is a union of every type in this subgraph that declares a key. A union member cannot be resolved without knowing which type an object is, so the type name is not optional and the federation specification requires it in every representation. **One key.** The fields of one `@key` selection set that this subgraph declared for that type. A single key field gives `{"__typename": "Trial", "nctId": "NCT-04471"}`. A composite key contributes both fields. A nested key such as `@key(fields: "site { id }")` contributes the nesting itself: ```json {"__typename": "Trial", "site": {"id": "SITE-3308"}} ``` A type may declare several keys, and the router chooses whichever one the subgraph it is coming *from* can produce. A reference resolver therefore has to handle every key its schema advertises as resolvable, not only the first one written. ## The one thing it sometimes carries If the field being fetched declares `@requires`, the router first collects those fields from the subgraph that owns them and folds them into the same representation object, arriving beside the key fields. That is the only legitimate route by which a non-key field appears in a representation, and it is opt-in, declared in the schema. ## What is not in there Everything else. Give the registry graph a `Trial` type with 37 fields, and the representation still carries two keys. The parent subgraph's copies of `title`, `phase` and `status` are not forwarded, even when the router already holds them in memory for the response it is assembling. This is the classic bug in a first reference resolver: reading `representation["title"]` works in the one query shape that was tested and yields nothing in every other, because whether the router happens to have that field is a property of the query plan, not of the entity. The narrowness is the point. A representation is a *pointer*, not a copy. Federation transmits identity between services and nothing else, so each subgraph stays the single source of truth for the fields it owns; the moment representations started carrying data, two services could disagree about a value and the router would have to pick a winner. ## Where the values come from The router does not invent key fields. While planning, it adds the key selections to the *upstream* fetch, so the parent subgraph returns `nctId` for every `Trial` even though the client never selected it; those values become the representations for the next step. Key fields therefore have to be plainly requestable with no arguments and no extra context — how a key is declared is its own subject. ## `_Any` means the schema is not helping you `representations` is typed `[_Any!]!`, and `_Any` is a custom scalar. Scalars are opaque to GraphQL validation, so no validation error is raised for a missing `__typename`, a misspelled key field, a string where an `ID` was expected, or fifty extra keys nobody asked for. The value reaches the resolver as whatever the JSON parser produced. That makes a representation *input from another process*, and it deserves the treatment given to any input: - verify `__typename` names a type this subgraph actually resolves; - read only the key fields you declared, and coerce them; - on anything missing or unrecognised, return a null slot or a field error rather than throwing out of the batch. Two consequences follow. First, `_entities` is a root field like any other, so anything reachable through it is reachable without passing the authorization checks written on your ordinary root fields — a trust boundary worth its own conversation. Second, a representation is never proof that the entity exists; it is a claim by the router that something upstream said it did, and a subgraph that cannot find it has a defined way to say so. ## The interview-sized answer `__typename` plus one declared key, delivered as a scalar the schema does not check, with `@requires` fields folded in when a field asks for them. The follow-up that separates candidates is *why so little* — because the representation identifies an object rather than describing it.