How to define a json-lines response in OpenAPI?

Question

Is there a way to describe a json-lines with OpenAPI?

Besides the fact that there seems to be no MIME type for it yet, I'm wondering if it's possible to describe such a response.

In theory my response could be an array of objects, but I received the question whether or not I could deliver as json-lines, meaning: just the objects, one per line.

Since I'm using OpenAPI to describe my API I'm puzzled as how to describe this response. I could simply define the response as being of type "string", but this is not very helpful for readers of my API spec.

Twobyfour

You might get a better answer by posting this in the OpenAPI Specification repo: github.com/OAI/OpenAPI-Specification/discussions – Northeast

Unfortunately the responses there are fewer than here… – Twobyfour

I suspect it would be just type: string because it doesn't have a registered MIME type and it's not vanilla JSON. But it would be nice to have a confirmation from OpenAPI maintainers. – Northeast

Answer 1

I don't believe there's a well-defined way to do this, given that there's no official MIME type of json-lines, and no clear way to document a schema in OpenAPI that consists of a line-delimited list of records.

When I've documented APIs like this, I've either used application/octet-stream or application/x-ndjson as the MIME type, and then specified in the API description that the schema definition applies to each record in the request / response.

Polaris

Answer 2

jsonl is often just a work-around for limitations in JSON parsers and serializers. If you have a streaming parser, like https://www.npmjs.com/package/stream-json, you can use standard JSON arrays.

Carnahan