Enabling JSON lines responses
JSON Lines (JSONL) or Newline Delimited JSON (NDJSON) is a simple and efficient format for streaming structured data. Each line in the stream is a valid JSON object, making it ideal for streaming large datasets, log files, or real-time data feeds. This format is particularly useful for processing data line by line without loading the entire response into memory.
INFO
The format is known by two names and content types, which are completely interchangeable:
- JSON Lines (JSONL):
application/jsonl - Newline Delimited JSON (NDJSON):
application/x-ndjson
Either content type can be used in the OpenAPI specification, as they are functionally identical (each line must be a valid JSON object that matches the specified schema).
Here’s an example of using an SDK to stream log data in JSONL/NDJSON format:
INFO
The JSONL/NDJSON streaming feature is currently supported in TypeScript, Python, Go, and Java. Let us know if you’d like to see support for other languages.
Modeling JSONL/NDJSON in OpenAPI
To implement line-delimited JSON streaming in generated SDKs, model an API endpoint that serves a stream in the OpenAPI document. Each line in the response will be a JSON object matching the specified schema. Either application/jsonl or application/x-ndjson can be used as the content type.
Basic implementation
The example below shows an operation that streams log events:
Endpoints with multiple response types
For APIs that support both batch and streaming responses, use URL fragments to define separate paths for each response type:
Use the appropriate method based on the requirements:
Last updated on