What is our authoritative spec URL and how do people find it?

[handrews]

Currently, some official citation sites point to the rendered HTML rather than the authoritative markdown files. There is also confusion over what the official, authoritative URL for the authoritative markdown actually is. Is it the location on main? Or is it the URL that uses a tag value? And that brings up the question of whether a URL that is tied to GitHub internals and structure (which can be tricky to update when, for example, we have broken external links when other people move their documents) and domain is appropriate for a "stable" URL.

So, what is the authoritative URL, and how to we ensure that people find that, know what it is, and cite it appropriately?

[LasneF]

just an opinion

i would expect to have the official version here https://spec.openapis.org/oas/latest.html
but here we have only the latest

why because it's a URL fully under control , it can refer to github , it could have a better SCO than the github

it provides more flexibility as hidding the technical implementation (ie branch versionning vs main + folder )

[lornajane]

I would suggest that the rendered HTML is the correct place for most use cases (and this URL is under our control, importantly), perhaps we should link to the source markdown in GitHub from the HTML rendering.

[handrews]

@LasneF formal citations need to cite a specific version, so the "latest" URL is only ever a convenience for human readers. The formal URLs must have the version in them, but (as you note) preferably tnot the GitHub details.

@lornajane I tend to agree with you on the rendered HTML. I believe the rationale for making the markdown authoritative was that it's the thing we directly edit and review, while the HTML-generating script could in theory introduce errors. I would prefer to do something to be confident that the rendered HTML is correct. But failing that we could at least put the markdown on our own domain.

[lornajane]

I like this idea. Let's put the markdown files onto our site alongside the HTML. URLs should go to the HTML, but the markdown can be linked from each version. I agree that the markdown is authoritative (but the HTML is the correct format for the majority of users, most people just looking something up I think)

[LasneF]

@handrews is there a plan to have in addition to
https://spec.openapis.org/oas/latest.html

a dedicated URL for the 3.1.0 like
https://spec.openapis.org/oas/3.1.0.html
or https://spec.openapis.org/oas/3.1.html ( :( )
or https://spec.openapis.org/oas/3.1.latest.html

and per extension
https://spec.openapis.org/oas/3.0.4.html or 3.0.html or 3.0.latest.html

lastly it would be nice to add somewhere in the HTML a link to the github

[handrews]

Note also that only the HTML renderings have the normative/informative references citation, which IMO is a very strong reason to cite them and not the markdown in GitHub. Plus separating our cite-able URLs from our repository structure, which is definitely a good thing.

@LasneF all of those already exist, the URLs are just slightly different (includes a v and relies on HTTP content negotiaton rather than file extensions, as Fielding intended 😉 :

• https://spec.openapis.org/oas/v2.0
• https://spec.openapis.org/oas/v3.0.0
• https://spec.openapis.org/oas/v3.0.1
• https://spec.openapis.org/oas/v3.0.2
• https://spec.openapis.org/oas/v3.0.3
• https://spec.openapis.org/oas/v3.1.0

[LasneF]

This looks very nice ! one remaining point would be to show on the https://www.openapis.org/ pushing on spot the latest but still having option to look at the past , and may be sooner or later to see the beta of the moonwalk (but that s another story)

[handrews]

@LasneF that site is managed by the Linux Foundation. You'll want to talk with @ncaidin or @swaldron58, probably on the #outreach channel on slack to see about getting those menus changed. We can't do anything about it in this repo (spec.openapis.org is run out of here, www.openapis.org is run by LF).