The standard for delimiting JSON in stream protocols (such as TCP).
This is a minimal specification for sending and receiving JSON objects over a stream protocol, such as TCP.
The JSON Stream framing is so simple that no specification had previously been written for what (to us) seemed the ‘obvious’ way to do it.
There is currently no standard for transporting JSON within a stream protocol (primarily plain TCP), apart from Websockets, which is unneccesarily complex for non-browser applications.
There were numerous possibilities for JSON framing, including counted strings and non-ASCII delimiters (DLE STX ETX or Websocket’s 0xFFs).
The primary use case for JSON Stream delimiting is an unending stream of JSON objects, delivered at variable times, over TCP, where each object needs to be processed as it arrives. e.g. a stream of stock quotes or chat messages.
2. Philosphy / Requirements
The specification must be trivial to implement in multiple programming languages, flexible enough to handle arbitrary whitespace (pretty-printed JSON), and yet not contain non-printable characters.
3. Functional Specification
Each JSON object MUST be written to the stream followed by the new line character 0x0A. The JSON objects MAY contain newlines, carriage returns and any other permitted whitespace. See www.json.org for the full spec.
All serialized data MUST use the UTF8 encoding.
The receiver MUST accumulate received lines. Every time a line ending is encoutered, it must attempt to parse the accumulated lines into a JSON object.
The receiver MUST accept all common line endings: ‘0x0A’ (Unix), ‘0x0D’ (Mac), ‘0x0D0xA’ (Windows).
If the parsing of the accumulated lines is successful, the accumulated lines MUST be discarded and the the parsed object given to the application code.
If the amount of unparsed, accumulated characters exceeds 16MiB the receiver MAY close the the stream. Resourse constrained devices MAY close the stream at a lower threshold, though they MUST accept at least 1KiB.