Skip to main content

Module jsonl

Module jsonl 

Source
Available on crate feature streaming only.
Expand description

JSON Lines: one resource per line, streamed as rows arrive.

A JSON:API collection document is a single value: the closing bracket cannot be written until the last row is known, so the whole page is held in memory and the client waits for all of it. That is the right trade for a page of twenty-five. It is the wrong one for an export of a million rows, where the document never fits in memory on either end.

JSONL inverts it. Each line is a complete resource object, so the server writes a row and forgets it, and the client parses a row and acts on it — neither holds more than one at a time, and the first row arrives in milliseconds rather than after the last one is found.

{"type":"todo","id":"t_1","attributes":{"message":"buy milk"}}
{"type":"todo","id":"t_2","attributes":{"message":"write docs"}}

§Asking for it

Accept: application/jsonl on the ordinary collection URL. There is no second route: the collection is one resource, and how it is rendered is what Accept is for — so a cache keyed on Vary: Accept already knows these are two representations of one thing.

Anything else — including no Accept at all — gets the JSON:API document, so this cannot change what an existing client receives.

§What is lost

A JSONL response carries no links, no meta and no included: there is no document to hang them on. It is a row stream, not a document, and a client that needs pagination links should ask for the document instead. Errors are the exception — see ERROR_LINE.

Constants§

ERROR_LINE
The shape of a failure that happens after the first line is sent.
LINE_MEMBER
The member carrying an input line’s 1-based number on a result line.
MEDIA_TYPE
The media type: application/jsonl.
MEDIA_TYPE_NDJSON
The other spelling clients use for the same thing.

Functions§

is_jsonl_request
Whether a request body is JSONL, from its Content-Type.
wants_jsonl
Whether an Accept header asks for JSONL.