Discuss content negotiation #132
Conversation
| 1. the User Agent express preference | ||
| for referenced resources compatible with OAS3.2. | ||
| 1. The server does not support strict content negotiation, | ||
| and responds with the default representation; | ||
| 1. the User Agent processes the content | ||
| and retrieves the referenced resources. |
There was a problem hiding this comment.
Try
curl -v https://raw.githubusercontent.com/OpenAPITools/openapi-generator-cli/refs/heads/master/examples/v3.0/petstore.yamlusing different Accept values.
| Q: Could the server respond with the same content | ||
| using the `application/whatever+yaml` media type? |
There was a problem hiding this comment.
If this is to indicate the JSON Schema media type, then yes. JSON Schema, including draft-04, allows extensions and there is no requirement to use every keyword in every schema.
| application/whatever+yaml; version=https://json-schema.org/draft/2020-12/schema, \ | ||
| application/whatever+yaml; version=https://spec.openapis.org/oas/v3.0.4#schema-object |
There was a problem hiding this comment.
If this is supposed to indicate a JSON Schema media type, it would not have a version parameter as metaschemas are not only used to indicate drafts. In fact, using them to indicate drafts is just an artifact of JSON Schema's perpetually-unfinished state. A schema parameter is the current convention, although in draft-04 it was profile but Erik Wilde told us we were using profile wrong so we took that out. But no matter what, it would not be version.
There was a problem hiding this comment.
@ioggstream since I had not noticed this before bowing out, and you clearly put a lot of work into it, I figured I should go ahead and give it a look.
I appreciate the increased detail, but we still seem to be in exactly the same situation as before.
I have added some further notes on why I think that this RFC should not recapitulate fallback content negotiation behavior. It is purely the domain of the HTTP specification, and encourages far worse behavior than a component parameter, which is just letting the things that end users already do actually work.
By far the most common fragmentary document use case is using a tool to split a document into components arranged in a directory structure that reflects the original document structure. In this case, $refs always point to the root of the fragmentary documents, and the expected component is always known and could be requested in Accept. I don't like this use case, but it's real, it's common, and I don't understand why we don't want to enable self-descriptive content via the media type.
Is that not the point of having a media type? To support what people need rather than what we wish they would do? In each new version of the OAS, I try to push tools and users more and more towards a better parsing and referencing approach. But when creating a media type that is supposed to work for historical deployments, I feel like we should support what's actually done whether we like it or not.
Note that this use case of $ref-ing entire fragmentary documents, and therefore knowing the expected root Object, is briefly acknowledged in the 3rd bullet point of OAS v3.1.1 §4.3.1 Parsing Documents (everything that works there works in 3.0, but that section is not in 3.0 because 3.0 lacks the whole-document parsing requirement).
Also, if you're going to use a fake media type for JSON Schema, it shouldn't be radically different from the way the de-facto JSON Schema media type actually works (meaning it should not have a version parameter that does not match the actual full usage of metaschemas). I know it's unregistered, but it's been in use for over a decade. I feel like you're going through a lot of contortions to avoid reflecting how people actually use things in practice, which involves fragmentary documents and de-facto JSON Schema media types.
As previously noted, it seems best that I just get out of the way as our goals here do not seem to align. Perhaps I am wrong, but it just seems like there is too much of a difference in philosophical perspective. I'm not claiming my perspective is objectively correct, I'm just not willing to abandon it but also don't want to block progress.
| Since JSON Schema has no associated media type, | ||
| the server uses the `application/yaml` media type. |
There was a problem hiding this comment.
Elsewhere you have been using application/whatever+yaml as the associated media type, so to say that there isn't one here feels strange.
| See {{Section 12.1 of HTTP}} | ||
|
|
||
| > A user agent cannot rely on proactive negotiation preferences being consistently honored, | ||
| > since the origin server might not implement proactive negotiation for the requested resource | ||
| > or might decide that sending a response that doesn't conform to the user agent's preferences | ||
| > is better than sending a 406 (Not Acceptable) response. | ||
|
|
||
| ~~~ http: | ||
|
|
||
| GET /OpenAPITools/openapi-generator-cli/refs/heads/master/examples/v3.0/petstore.yaml HTTP/1.1 | ||
| Host: raw.githubusercontent.com | ||
| Accept: application/openapi+yaml; version=3.2 | ||
| ~~~ | ||
|
|
||
| The server responds with the default representation. | ||
|
|
||
| ~~~ http | ||
| HTTP/1.1 200 OK | ||
| Content-Type: text/plain; charset=utf-8 | ||
|
|
||
| openapi: 3.0.0 | ||
| info: | ||
| title: Hotel Booker API | ||
| … | ||
| ~~~ | ||
|
|
||
|
|
There was a problem hiding this comment.
I feel strongly that this should not be included. This sort of failure to support proactive negotiation is strictly an HTTP thing and not specific to the OAS at all. There is no need to recapitulate it, and it does damage by normalizing the behavior.
In fact, if the argument against a component parameter is that it normalizes fragmentary documents and that can't be done in the registration, I cannot understand how normalizing returning text/plain is acceptable to show. It is a far more pathological behavior, and again, not one that has anything to do with OAS at all.
|
To clarify for anyone following along and avoid misunderstandings, I have no problem whatsoever with @ioggstream and would happily collaborate on other things in the future. I just think we have differing goals for this RFC, and to the extent that I can see, more people are aligned with the direction of the text as it is. There's nothing wrong with that, and I am only stepping away because I think the work is in plenty good enough shape to be finished without me. |
|
Thank you for that explanatory comment!
|
This PR
cc: @handrews