Enums & Input Objects

## An enum type is a closed set of names An enum type definition lists the values a field or argument of that type may take, and nothing else is legal: ```graphql enum ParcelState { AWAITING_DROP STORED COLLECTED EXPIRED } ``` In a parcel-locker graph this says a `Parcel.state` is one of four names. The values are **names**, not strings: they follow the same name grammar as a field or type name (a leading letter or underscore, then letters, digits or underscores), and the three names `true`, `false` and `null` are excluded because the document grammar already reads those as the boolean and null tokens. SCREAMING CASE is a very widespread convention, not a rule - `Stored` would be a legal value name and a bad one. ## Two languages, two spellings of the same value The confusion this question probes comes from the fact that a GraphQL request travels in two languages at once. The **document** is written in the GraphQL language, which has an enum-value token, so the value is a bare word. The **variables map** and the **response body** are usually JSON, and JSON has exactly six kinds of value - object, array, string, number, boolean, null - none of which is an enum. So the transport spells the value with the closest thing it has: a string that carries the value's name. ## Input coercion: literal versus variable Both of these are correct, and they look different: ```graphql { parcelsAtLocker(lockerId: "4217", state: STORED) { id state } } ``` ```json { "query": "query($state: ParcelState!) { parcelsAtLocker(lockerId: \"4217\", state: $state) { id state } }", "variables": { "state": "STORED" } } ``` In the first, `STORED` is an enum-value literal inside the document. In the second, the document names a variable and the value arrives in JSON, so it is the string `"STORED"`, which the server coerces by matching it against the enum's value names. Two mistakes follow directly. Writing `state: "STORED"` **inside the document** supplies a String where a `ParcelState` is expected, and the request never runs. And declaring the variable as `query($state: String!)` and then using `$state` for a `ParcelState!` argument is rejected too: a variable's declared type has to be usable at the position it is used, and String is not ParcelState, however identical the JSON looks. ## Result coercion: back out as a name On the way out the direction reverses. The server holds the state in whatever form it likes - a single-character column, a small integer, a language-level enum - and result coercion maps that internal value onto one of the declared value names, then serializes the name as a JSON string: ```json { "data": { "parcelsAtLocker": [ { "id": "p-38", "state": "STORED" } ] } } ``` If the internal value maps to nothing in the set - a downstream service in an 11-service graph returns a status nobody added to the schema - coercion cannot invent a name. That field raises a field error instead of returning a made-up value, which is the whole point of a closed set: the schema's promise is that a client will only ever see one of the four names. ## Why the names, and only the names, are the contract Nothing positional ever reaches the wire. There is no ordinal, no index, no numeric mapping - so reordering the values in SDL is invisible to every client, while renaming one is a change every client sees. Internal numbers are an implementation detail of one server, and two servers behind the same schema may number them differently without anyone noticing. Because the set is closed and introspectable, tooling can read it: a typed client generator turns `ParcelState` into a four-member union or a language enum and makes an unhandled case a compile error. That is the practical difference between an enum field and a `String` field carrying the same letters. A String promises nothing; the enum promises the set. Individual enum values can also carry a description and can be marked deprecated with the built-in `@deprecated` directive, and a deprecated value is hidden from introspection listings unless the caller explicitly asks to include deprecated entries. ## What to keep hold of Bare name in the document, quoted name in JSON, and a name - never a number - is what the schema promises. Everything a candidate gets wrong here is a variation on forgetting that the document and the variables map are two different languages describing the same value.