About
A spec is a document with rules about itself
Last updated 22 November 2026
Most formats ask you to be careful. OpenAPI writes down what it expects and then waits to be checked against it, which is an unusual thing for a file to do.
Three readers, no library
The first reader is YAML. It walks the text line by line, keeping the indentation that gives the document its shape, and understands the parts a real spec uses: block and flow collections, plain and quoted scalars, block scalars with their chomping, comments, anchors and aliases, and the merge key. It is not a general YAML 1.2 implementation, and it says so when it meets something it does not know.
The second reader is JSON, through the browser's own parser. When that refuses the text, a small reader written here walks the same text again, because the browser's message names the problem but not the place, and a place is what you need.
The third and last reader is the checker. It does not parse anything. It walks the tree the first two readers built and compares it with the rules the specification sets for paths, operations, parameters, responses and references.
What the checker reads
A path that does not start with a slash, an operation with no responses, a response key that is not a status, a parameter with no name or no place, a path parameter that is not required, a template brace with no parameter behind it, a parameter declared for a place the path does not have, an operationId used twice, a security scheme that is not declared, a tag that is used but never described, and a local reference that resolves to nothing. Each finding names the operation it belongs to and the pointer into the document.
Two checks depend on the version. A 3.1 document that still writes nullable, and a 3.0 document that writes a list of types, are both reported, because each one is the other version's habit.
Where the trees come from
Every reference inside the document is resolved before a schema is drawn, so an Order that appears in five responses is read once and shown in five places. A reference that points at itself stops after one turn and is marked as a cycle rather than followed forever. A reference to another file or another host is not resolved at all: that would be a network request, and this page makes none.
The three writers
The cURL snippet fills the path from the parameter's example, or from the first value its schema suggests, and adds the query pairs and the declared headers. The fetch snippet is the same call in a form you can paste into a module. The TypeScript writer walks the request and response schemas, writes an interface for every named schema they touch, and then a function that returns the response type rather than any. None of the three is a client generator: they are a way to see what the document says, in the shape you will actually type.
Where it stops
- It does not call the API, so it cannot tell you that an endpoint is down, slow, or refuses your token.
- It checks the document against the specification, not against your server's behaviour. A document can be perfect and still describe an API that does something else.
- A sample value in a snippet is a value the schema allows, not one your database has.
- External references are named and left alone, by design.
Who made it
Pikkola Lab builds small tools that keep the work in the browser. This is tool No. 64. Write to hello@pikkola.com with a document that reads badly, and say which line the reader lost.