0109. The typed client types every part of an operation, or refuses it
- Status: Accepted (Mik, 16 Nov 2026)
- Date: 2026-11-15
- Decided by: domain E fixer (internal only), after the review of PR #36
- Amends: 0104
Context
The first generator (0104) followed any $ref inline, so a schema that referred to itself overflowed the stack and stopped every build. It also left parts out or typed them loosely without saying so: header and cookie parameters were dropped, a {name} in a path with no parameter was sent as it was, {} and not: became unknown, a form or multipart body was typed and sent as JSON, head, options and trace were skipped, and a default answer (usually the error) was taken as the success. The owner's rule is that anything statically knowable fails the build loudly.
Decision
Every part of an operation is typed as the server takes it, or the build fails with a diagnostic that says what to change.
| In the description | Becomes |
|---|---|
A schema under #/components/schemas/<Name> | A named type; it may refer to itself (type Tree = { kids?: (Tree)[] }) |
Any other $ref in the file | Written out where it is used; one that leads back to itself is E0517, with the fix "name it under #/components/schemas" |
A named schema that is itself through $ref, allOf, oneOf or anyOf alone | E0517 (TypeScript cannot write type A = A) |
{}, not:, an array without items, a body or answer with no schema | E0517 |
A schema with only additionalProperties | An object with an index signature |
| A header parameter | headers: { "X-Api-Key": string }, required when any header is; sent as text. Accept, Content-Type and Authorization are ignored, as OpenAPI says |
| A cookie parameter | E0518: browsers drop a Cookie header a script sets, so it could never be sent |
| A required query member | query is required too |
A {name} in the path no parameter declares, or a path parameter the path lacks | E0518 |
| A body with no JSON media type (form, multipart, other) | E0518; JSON is chosen when the body offers it beside others |
| Answers | The union of every 2xx answer (JSON schema, string for text/*, undefined for none); no 2xx answer, including default alone, is E0518 |
head, options | Typed and callable (server.head(...), server.options(...)); head answers void |
trace | E0518: browsers refuse to send it |
At run time typedApi refuses a path parameter that is missing, empty, . or .. (each would change which path is called; servers normalise %2e%2e too), instead of sending it.
Alternatives considered
| Option | Why not |
|---|---|
Type a self-referring inline $ref by naming it after its pointer | A name the description never gives; moving it under components/schemas is one line and gives it a real name |
| Send form and multipart bodies | The generated file holds only types, so the runtime cannot know a path's encoding without shipping a table per operation; fetch with FormData is already the way to send them |
Send cookies by writing document.cookie | Writes a lasting cookie for the whole site as a side effect of one call, and does nothing across origins |
Skip trace with a warning | Every other part fails loudly; a warning would be the one silent exception |
Consequences
A description that used to build may now fail with E0517 or E0518; each message names the part and the fix. The data example's description needed no change.