search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
29.08k stars 9.08k forks source link

RFC 7231 has been obsoleted by RFC 9110 #3800

Open dret opened 6 months ago

dret commented 6 months ago

Looking at https://spec.openapis.org/oas/latest.html it still references RFC 7231 when referring to HTTP. But that specification was obsoleted by RFC 9110 in June 2022. I am not confident enough to make the change myself, but if somebody can point me at some "here's how to change the OpenAPI spec" primer, I'd be more than happy to give it a try.

handrews commented 6 months ago

@dret we don't change the published specs (except when something happens like GitHub breaking their own markdown rendering, but in that case we're changing a broken link to work again, not changing the actual contents).

It's not clear to me if updating obsoleted RFCs is something we do in patch releases or if we want to leave those and only change them in a minor release. Process issues related to this:

handrews commented 6 months ago

if somebody can point me at some "here's how to change the OpenAPI spec" primer, I'd be more than happy to give it a try.

We're kind of buried in a backlog of issues trying to define and document this:

dret commented 6 months ago

for that specific case my opinion is: you cannot make IETF's publishing strategy more coherent than it is, and there always are some odd corner cases. your case is special because 1866 never was obsoleted by an IETF spec and that may cause some ripples. but why are you referencing that one and not the latest HTML spec which is for example also what's referenced in the IANA media type registry:

https://www.iana.org/assignments/media-types/media-types.xhtml

my general guideline is: if i reference an RFC and it shows up as "obsoleted", then i'll reference the "obsoleted by" RFC instead. but that's of course assuming everything is nicely cross-referenced...

handrews commented 6 months ago

not the latest HTML spec

I didn't make this reference, so I don't know, but I assume because it's actually in WHATWG's URL "Living Standard" which doesn't even acknowledge the existence of relative URI-references [EDIT: as a syntax independent from a browser-supplied base URI], among many other failures to cover 3986, which claims to "obsolete". And then the author refuses to define relative references because, (and I quote) there is a "lack of browser-related use cases" 🤦

Plus, WHATWG specs are pseudocode tied to browser implementations. They're completely unreadable for anyone else IMNSHO.

While I've been working on the parameter serialization areas, I have debated mentioning WHATWG. But to me, referencing WHATWG URL in an API spec that's based off of RFC3986 is asking for trouble. It introduces a conflicting set of terminology, a dismissive attitude of the work of past spec authors, and an aggressively browser-centric worldview that outright dismisses the utility or relevance of any other context at all.

handrews commented 6 months ago

To be clear: I think the WHATWG specs do a valuable thing by standardizing implementation concerns. If they just did that on top of the existing RFCs and W3C specs that define grammars, syntax, and semantics, it would have been fanstatic. But instead they act like those other concerns, audiences, and environments are so unimportant that they refuse to address them while attempting to prevent anyone else from doing so. We're an API spec, not a browser spec, so we are solidly outside of what they consider valid or relevant, as they've made clear over and over.

handrews commented 6 months ago

Oh and WHATWG URL's encoding set for application/x-www-form-urlencoded is different from RFC6570's form expansion operator, and I can't figure out how to explain that in our spec with out a multi-paragraph digression, and I just do not have any idea how to deal with that (despite my ranting, if someone comes up with a coherent way to refernce and explain all of that, I would happily support. I'm just at a loss with it)

dret commented 6 months ago

On 2024-05-13 12:17, Henry Andrews wrote:

Oh and WHATWG URL's encoding set for |application/x-www-form-urlencoded| is different from RFC6570's form expansion operator, and I can't figure out how to explain that in our spec with out a multi-paragraph digression, and I just do not have any idea how to deal with that (despite my ranting, if someone comes up with a coherent way to refernce and explain all of that, I would happily support. I'm just at a loss with it)

i see clearly now that i shouldn't have mentioned that particular spec. i was lucky and had forgotten about all the details around how it came up and what the general attitude is. so thanks for reminding me, please accept my apologies for mentioning it, and i do agree that referencing what's basically a browser implementation in pseudo code may not be the most appropriate thing for an API specification.

handrews commented 6 months ago

@dret thanks – my reaction was probably excessive so I apologize for that. Honestly, it's mostly that I don't know what to do with the mess. There's just no good answer.

Anyway, if you want to keep this focused on 7231 vs 9110 you're welcome to hide or delete this digression (or if you don't have permissions, lmk and I'll do it), or close this and re-file the main point.

handrews commented 6 months ago

@OAI/tsc review request: Should we replace obsoleted RFC references in patch releases, or can we only do that in a point release? They are obsoleted whether we update them or not, but idk how that's viewed in this context.

lornajane commented 6 months ago

I think we should not update in patch releases, in case there's an impacting change. We reference enough 3rd party docs that it would be significant work to review if any of their wording change could possibly impact ours. Let's stick to doing that in minor versions, would be my recommendation. (with the proviso that all rules can be broken if there are good reasons!)

lornajane commented 5 months ago

Discussed in TDC and there's a weak consensus that we should not make this sort of change in a patch release unless there's a strong reason to. Unless someone can go through in enough detail to be sure we're not unintentionally changing things that might impact our users, this should wait until the minor release or until someone has the bandwidth to carefully check all the implications.

I'll leave this open for us to pick up in 3.2