About
A document is a tree before it is text
Last updated 21 November 2026
GraphQL looks like JSON with the values left out. It is not: it is a small language with a grammar, and every reader on this page starts by turning your text into a tree of that grammar.
Three passes, no library
The first pass is the lexer. It walks the text one character at a time and cuts it into tokens: names, numbers, strings, block strings, punctuators and comments. It drops the two things GraphQL ignores, commas and whitespace, which is why the same query typed on one line and typed across twenty lines formats to the same bytes. An unterminated string, a bad escape or a number with a leading zero is rejected here, with the line and the column of the character that broke it.
The second pass is the parser: a recursive descent over those tokens that builds a document, definitions, operations, selection sets, arguments, values and, in the schema case, types. It does not know what a field means, only how it is written, which is the point. The third pass is a printer that walks the tree in order and writes it back out, four ways.
Two readers over one tree
The TypeScript writer and the mock writer both need the schema, and the schema is read with the same parser, in its definition language. From it they build a small map: type name to kind, field to type, enum to values, interface to the objects that implement it. The TypeScript writer prints that map as interfaces. The mock writer walks the query against it, choosing a value for each leaf and a shape for each selection set.
What depth and cost count
Depth is a property of the document alone: one level for a root field, one more for every selection set inside it. Cost counts fields, and here a list with a first, last or limit argument multiplies everything beneath it by that number, capped at ten so one careless first: 1000 does not drown the number. Neither is a rule. A limit is a conversation with the server team, and this page only puts a number in front of you before that conversation.
Where the checker stops
It can compare a document with a schema: a field that does not exist, a selection set on a scalar, an object field with no selection set, a variable used and never declared, a fragment spread with no definition. It cannot run a resolver, so it cannot tell you that user(id: "nobody") returns null, and it will not pretend a mock is a test result. The mock is a shape that matches the types, which is what a form field or a loading skeleton needs.
What it leaves to you
- Which of the two indents your repository uses. Both are here because teams disagree, usually loudly.
- The depth and cost limits. The page suggests seven and two hundred and fifty, and never enforces them.
- Whether a mock should be a fixture or a guide. A fixture has to be maintained; a guide is read once.
- The schema itself. Without one, TypeScript needs a guess and the mock guesses with it, which the page says out loud instead of hiding.
Who made it
Pikkola Lab builds small tools that keep the work in the browser. This is tool No. 54. Write to hello@pikkola.com with a document that formats badly, and say which part of the grammar it was.