Which literal value forms can a GraphQL argument take inline in a document?

## Literal syntax is not JSON, and that is the whole lesson Most engineers meet GraphQL argument values after years of writing JSON, and the two look close enough that the differences read as typos rather than as a different grammar. They are a different grammar. The specification defines one `Value` production, and every place a value can be written uses it: a field argument, a directive argument, an element inside a list, a field inside an input object, and a default value in a definition. Learn the eight forms once and they apply everywhere. ## The eight forms **Int.** An optional minus sign and digits, with no decimal point, no exponent, and no leading zeros. `4`, `-27` and `1200` are Int literals; `007` is a syntax error. The built-in `Int` scalar is a signed 32-bit integer, so a literal outside that range is rejected rather than silently wrapped. **Float.** Digits with a fractional part, an exponent, or both: `3.5`, `-0.25`, `1.2e3`. A trailing dot with nothing after it is not legal. **String.** Double quotes only: `"SEC-4471"`. Single quotes are not string syntax in GraphQL at all; they are an illegal character in a document. There is a second string form, the **block string**, written with triple quotes. **Boolean.** The bare keywords `true` and `false`, lower case and unquoted. `"true"` is a String literal, and a `Boolean` argument rejects it. **Null.** The bare keyword `null`. It is a real value the caller can send, distinct from leaving the argument out. **Enum value.** A bare name: `WAITLISTED`, `ENROLLED`, `DROPPED`. Never quoted. The grammar deliberately excludes `true`, `false` and `null` from being enum values, so those three keywords can never be mistaken for enum names. **List.** Square brackets around zero or more values: `["SEC-4471", "SEC-4472"]`, or `[]`. Because the elements are themselves values, lists nest and may hold input objects. **Input object.** Braces containing `name: value` pairs, where the names are bare: `{ termCode: "2026-SPRING", credits: 4 }`. Quoting the field names, as JSON requires, is a syntax error. Order is not significant and a field name may appear at most once. ## Commas are decoration Commas in a GraphQL document are insignificant, exactly like spaces and line breaks. `[4 8 15]` is a legal list literal and `{ termCode: "2026-SPRING" credits: 4 }` is a legal input object literal. The comma exists so that humans can read a long line; nothing in the grammar needs it. That is the cleanest tell that you are not looking at JSON. ## Block strings A block string is delimited by three double quotes and may span lines. Common leading indentation is stripped from the value, so an argument written inside an indented selection set does not inherit the document's indentation. The only escape sequence inside a block string is an escaped triple quote, which is why a block string is a comfortable place to put text that is full of quotes and backslashes. The same syntax is used for descriptions in schema definition text, which is where most people see it first. ## A literal need not match the declared type exactly Two leniencies are specified, and they are the ones worth remembering: * Where a `Float` is expected, an **Int literal is accepted** and coerced — `credits: 4` satisfies a `Float` argument. The reverse does not hold: a Float literal is not a valid `Int`. * Where an `ID` is expected, both a **String literal and an Int literal** are accepted, because identifiers are opaque and servers differ on whether they look numeric. Custom scalars decide for themselves which literal kinds they accept, and the specification does not prescribe that. A custom date scalar conventionally takes a String literal, but that is a decision made by whoever defined the scalar, not a rule you can rely on across schemas. ## Who checks the literal, and when Literal values are checked statically, before anything executes, by the validation rule that requires values to be of the correct type. A quoted enum value or a Float literal in an Int position therefore fails the request outright: the response carries errors and no `data` key, and no resolver ran. This is a pleasant property — a typo in a constant fails identically for every caller, which means it fails in your own test run rather than for one unlucky user. ## Worked example Consider a course-enrolment graph whose `enroll` field takes an ID, an enum, a list and an input object. One document can exercise every literal form at once: ```graphql mutation { enroll( sectionId: "SEC-4471" status: WAITLISTED preferences: { notify: true, maxCredits: 18, note: null } alternateSectionIds: ["SEC-4472" "SEC-4489"] weighting: 0.75 ) { enrollmentId status } } ``` Note the four tells: the enum is bare, the input object's keys are bare, one list has no comma between its elements, and `null` is written as a keyword rather than as the string `"null"`. ## The two traps that actually show up The first is `status: "WAITLISTED"`. It reads correctly to anyone coming from JSON and is rejected, because a String literal is not an enum value. The second is `preferences: { "notify": true }`, which is a parse failure rather than a type failure — the document does not even reach validation. Both have the same cure: remember that the document is GraphQL source text, not a JSON payload, and that only actual text goes in quotes.