5

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.

Helen
  • 87,344
  • 17
  • 243
  • 314
Skeeve
  • 7,188
  • 2
  • 16
  • 26
  • 1
    You might get a better answer by posting this in the OpenAPI Specification repo: https://github.com/OAI/OpenAPI-Specification/discussions – Helen Sep 09 '21 at 20:42
  • Unfortunately the responses there are fewer than here… – Skeeve Sep 14 '21 at 07:01
  • 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. – Helen Sep 14 '21 at 08:31

1 Answers1

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.

alphaloop
  • 1,127
  • 12
  • 22