When is GraphQL's query shorthand, a bare selection set with no keyword, legal?

## What the shorthand actually is The shorthand form is a document that consists of nothing but a selection set: ```graphql { clinician(id: "c-3319") { fullName appointmentsToday { startsAt } } } ``` There is no `query` keyword and no operation name. This is not a special dialect; the specification defines it as an ordinary query operation with two pieces of syntax elided, and the parser produces exactly the same operation definition it would have produced from `query { ... }`. ## The exact conditions The shorthand is legal only when all of the following hold: 1. The document contains **one** operation. Not one query alongside a mutation — one operation, full stop. 2. That operation is a **query**. Never a mutation, never a subscription. 3. It defines **no variables**. 4. It carries **no directives on the operation itself**. Candidates routinely give condition 1 and stop. Conditions 3 and 4 are the ones that separate someone who has read the grammar from someone who has only seen the shorthand in an explorer. The reason for them is mechanical rather than philosophical: variable definitions and operation directives are written in the syntactic slot between the operation name and the selection set, and once you delete the keyword and the name there is nowhere left to put them. `($id: ID!) { ... }` is not a legal document. Condition 2 has the same character. The keyword is the *only* thing in the syntax that says which operation type you meant, so a bare selection set has to mean something by default, and the specification says it means a query. There is consequently no shorthand for a write. ## The neighbouring rule: lone anonymous operation Shorthand is one way to end up with an anonymous operation, but not the only one: `query { ... }` — keyword, no name — is anonymous too. A separate validation rule governs all anonymous operations, however they were written. If a document contains an anonymous operation, that operation must be the only operation in the document. So this document is invalid: ```graphql { clinician(id: "c-3319") { fullName } } query ClinicianLoad($id: ID!) { clinician(id: $id) { appointmentCount } } ``` It fails validation before anything executes, and the response carries an `errors` entry with no `data` key. Note what the rule does *not* say: it is not 'at most one anonymous operation'. One anonymous operation plus one named operation is just as invalid as two anonymous ones, because the anonymous one is no longer alone. Fragment definitions are a common source of confusion here and the answer is reassuring: a fragment definition is a top-level definition but it is not an operation, so a document holding one anonymous query and three fragment definitions is fine. ## Why it is a liability in an application Shorthand is what an explorer hands you, what a bug report pastes, and what a curl one-liner uses. In all three settings it is exactly right — you have one operation, you are typing it by hand, and ceremony would be noise. In application code it costs you two things that are hard to recover later. First, **selectability**. An anonymous operation cannot be picked out by name, so the moment a build step wants to bundle several documents together, or a client wants to send one document containing more than one operation, every anonymous operation has to be rewritten. Second, and more expensively, **attribution**. Server-side metrics, logs and traces key on the operation name. A fleet of anonymous operations arrives at the server as an undifferentiated stream: every request is nameless, so per-operation latency, per-operation error rate and per-operation call volume all collapse into one bucket. When a single expensive read starts timing out under peak load, a nameless bucket tells you that *something* is slow and nothing else. The usual remedy is a lint rule in the client repository that requires every operation to carry the keyword and a unique name. Note that this is a **convention** enforced by tooling; the specification requires operation names to be unique only within a document, and does not require them at all when the document holds one operation. Adopting the stricter rule early is cheap; retrofitting it across a large client codebase, after the metrics you needed were already lost, is not.