CODEWITHSUNDEEP
jsonswaggeropenapimojoliciousjsonlines
Skeeve
Skeeve

Reputation: 8262

How to define a json-lines response in OpenAPI?

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.

Upvotes: 7

Views: 1480

Answers (2)

Erik Martino
Erik Martino

Reputation: 4245

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.

Upvotes: 0

alphaloop
alphaloop

Reputation: 1167

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.

Upvotes: 2

Related Questions