Which parts of a GraphQL document's text does the parser ignore?

## Two layers: lexing, then parsing GraphQL's grammar is defined in two stages. A **lexical** stage turns the raw source text of a document into a stream of tokens, and a **syntactic** stage assembles those tokens into definitions, selection sets, arguments and so on. The lexical stage is where the question of "what does the parser ignore" is settled, and the specification answers it with an explicit list. The **ignored tokens** are: a Unicode byte-order mark at the start of the source, whitespace (space and horizontal tab), line terminators, comments, and commas. Ignored tokens may appear between any two real tokens and are discarded — they never become part of the parsed document. Everything that is left is meaningful: punctuators (`{` `}` `(` `)` `[` `]` `:` `$` `@` `!` `|` `&` `=` and the spread `...`), names, and the literal forms for integers, floats, strings, booleans, null and enum values. ## The comma surprise Because the comma sits on that list, a comma in a GraphQL document means precisely what a space means: nothing. All of these are the same operation over a real-estate listings graph: ```graphql query { listing(id: "LST-4417") { streetAddress priceCents } } ``` ```graphql query { listing(id: "LST-4417") { streetAddress, priceCents } } ``` ```graphql query { listing(id: "LST-4417") { streetAddress,, priceCents, } } ``` A doubled comma is legal. A trailing comma is legal. A comma between an argument list and the selection set that follows it is legal. None of them changes the token stream that reaches the parser. This is the reverse of JSON, where a missing comma and a trailing comma are both syntax errors, and it catches out anyone who assumes the two formats share a grammar because they both use braces. The design is deliberate and it pays off in machine-generated text. A tool that concatenates selected fields, or a person editing a long selection set by hand, does not have to track which element is last. Reordering two lines produces a one-line diff instead of a three-line one. Formatters can therefore normalise commas however a team likes, and the behaviour of the request is untouched. ## Comments A comment begins with `#` and runs to the next line terminator. There is no `/* ... */` form; writing one is a syntax error. Because a comment is an ignored token, it may appear wherever whitespace may — inside an argument list, between a field and its selection set, above an operation. What matters operationally is that a comment does not survive. It is discarded when the document is lexed, so it never appears in a response, never reaches a resolver, and is not visible through introspection. Commentary that has to be readable by consumers of the API is written as a **description** — a string attached to a definition in the schema's SDL, which is retained and exposed — not as a `#` line. Confusing the two is the usual beginner mistake: `#` is for whoever opens the file, a description is for whoever reads the schema. ## Layout is free, inside string literals it is not Since whitespace and line terminators are ignored, a document may be minified onto one line — which is exactly what most clients send over the wire — or spread across forty indented lines in a repository. The two parse identically. That freedom has one boundary: **inside a string literal, characters are content, not layout.** A space inside `"221B Baker Street"` is part of the value. The other boundary is that two adjacent names still need something between them: `streetAddress priceCents` is two fields, `streetAddresspriceCents` is one name. One practical consequence of free layout is worth carrying into the next topic: when a server reports the line and column of a syntax error, those numbers index the text the server actually received, which for a minified document is usually line 1. ## Names are not free The tokens that are *not* ignored come with their own strictness. A GraphQL **Name** — used for operations, fields, arguments, types, fragments, directives and enum values — matches `[_A-Za-z][_0-9A-Za-z]*`. Letters, digits and underscores only; never a leading digit; no hyphens, dots or spaces; and names are case-sensitive, so `priceCents` and `pricecents` are different. A legacy column called `list-price` or `2024_total` cannot become a field name verbatim; it has to be renamed in the schema. Names beginning with two underscores are reserved by the specification for the introspection meta-fields, so a schema must not define its own. ## How this comes up in an interview Usually as a fast filter: "are commas required?", "how do you comment a query?", or a snippet with a doubled comma and the question of whether it compiles. The point of the question is not the trivia — it is whether you have read the grammar rather than pattern-matched GraphQL onto JSON. Answer with the category, not the anecdote: commas are ignored tokens, alongside whitespace, line terminators, a leading byte-order mark and `#` comments.