Skip to content

Comments

use mime-type application/jsonl to align with openapi 3.2#51668

Merged
thaJeztah merged 1 commit intomoby:masterfrom
ndeloof:jsonl
Dec 17, 2025
Merged

use mime-type application/jsonl to align with openapi 3.2#51668
thaJeztah merged 1 commit intomoby:masterfrom
ndeloof:jsonl

Conversation

@ndeloof
Copy link
Contributor

@ndeloof ndeloof commented Dec 5, 2025

- What I did

while json-lines isn't (yet) an official Mime type (wardi/jsonlines#19), [OpenAPI 3.2 support for JSON streams](https://www.openapis.org/blog/2025/09/23/announcing-openapi-v3-2#sequential-and-streaming-data refers to "application/jsonl" as a commonly used mime type.

- How I did it

- How to verify it

- Human readable description for the release notes

`GET /events` now also supports [`application/jsonl`](https://jsonlines.org/) when negotiating content-type.

- A picture of a cute animal (not mandatory but encouraged)

MediaTypeJSON = "application/json"

// MediaTypeNDJSON is the MIME-Type for Newline Delimited JSON objects streams.
// MediaTypeNDJSON is the MIME-Type for Newline Delimited JSON objects streams (http://ndjson.org/).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably use the GitHub repository for this, as it looks (also see the other discussion) that they let the domain expire, so it's now some unrelated website.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated

@thaJeztah
Copy link
Member

Trying to think what's the best way to implement this; currently this change is not versioned, and the daemon doesn't return an error if a new client would try to get this media-type on an older daemon, in which case it silently falls back to application/json, even if that's not included in the client's list of accepted content-types;

curl -v -H 'Accept: application/jsonl' --unix-socket /var/run/docker.sock http://localhost/v1.52/
events
*   Trying /var/run/docker.sock:0...
* Connected to localhost (/var/run/docker.sock) port 0
* using HTTP/1.x
> GET /v1.52/events HTTP/1.1
> Host: localhost
> User-Agent: curl/8.14.1
> Accept: application/jsonl
>
* Request completely sent off
< HTTP/1.1 200 OK
< Api-Version: 1.52
< Content-Type: application/json
< Date: Mon, 08 Dec 2025 12:38:50 GMT
< Docker-Experimental: false
< Ostype: linux
< Server: Docker/29.1.1 (linux)
< Transfer-Encoding: chunked

Of course, in practice, the response itself should still be fine, but it won't return the expected content-type :thinking_face:

@ndeloof ndeloof force-pushed the jsonl branch 2 times, most recently from a409381 to 3b85c34 Compare December 11, 2025 13:30
@ndeloof
Copy link
Contributor Author

ndeloof commented Dec 11, 2025

@thaJeztah engine does not check Accept header in any place, so I don't expect any client to expect a strict behavior:

curl --unix-socket /var/run/docker.sock -v -H 'Accept: application/xml' http://lcoalhost/containers/json
*   Trying /var/run/docker.sock:0...
* Connected to lcoalhost (/var/run/docker.sock) port 0
> GET /containers/json HTTP/1.1
> Host: lcoalhost
> User-Agent: curl/8.7.1
> Accept: application/xml
> 
* Request completely sent off
< HTTP/1.1 200 OK
< Api-Version: 1.52
< Content-Type: application/json

As long as response's Content-Type is correct, client should be able to parse with the adequate logic

@thaJeztah
Copy link
Member

Derp; missed your comment

Yeah, the Go client doesn't check the response type and just considers them all equal (which they "roughly" are). I was wondering if other clients would check the response type to handle (e.g.) application/json-seq different than application/x-ndjson (or application/jsonl). If such a client would only send application/jsonl as "accept" header, and the daemon would return a different content-type as requested, that would be potentially unexpected.

I seemed to recall that the correct response was a 406 or a 300, but there's been quite some different descriptions throughout specs, and I just found that MDN (which is not the specification, but usually contains useful information) mentions; https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/406

A server may return responses that differ from the request's accept headers. In such cases, a 200 response with a default resource that doesn't match the client's list of acceptable content negotiation values may be preferable to sending a 406 response.

So, yeah, looks like returning a 200 is not uncommon, so probably OK; perhaps we should add a code-comment that links to that page and a short blurb documenting that we've chosen to use 200 instead of 406?

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Comment on lines +20 to 22
* `GET /events` now also supports [`application/jsonl`](https://jsonlines.org/)
when negotiating content-type.
* Deprecated: The `POST /grpc` and `POST /session` endpoints are deprecated and
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did a quick rebase to get a fresh run of CI, and added a snippet here to mention that we added support for this content-type.

Copy link
Member

@thaJeztah thaJeztah left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@thaJeztah thaJeztah merged commit 9c68897 into moby:master Dec 17, 2025
180 checks passed
@thaJeztah thaJeztah added the kind/enhancement Enhancements are not bugs or new features but can improve usability or performance. label Dec 17, 2025
@thaJeztah thaJeztah added this to the 29.2.0 milestone Feb 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/daemon Core Engine area/docs impact/changelog kind/enhancement Enhancements are not bugs or new features but can improve usability or performance. module/api module/client

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants