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).

[handrews]

@LasneF I do agree that we should make it easier for people who want to cite a specific version of the OAS to find that version and know what URI to cite. And while that URI can be a URL to a namespace we fully control (spec.openapis.org), it should not be a URL into GitHub repos that we need to be free to reorganize.

[darrelmiller]

I would prefer the HTML version to the be official URL. It is also what specref currently points to, so... https://www.specref.org/?q=openapi

[mikekistler]

It seems that I'm in the minority here -- I actually prefer to link directly into the markdown docs on GitHub -- but I can be persuaded to switch to the rendered HTML. My key concern there is how the HTML content is source-controlled. I think the "authoritative" reference must be source-controlled in some way.

[darrelmiller]

We convinced Mike that HTML is cool :-) Consensus in the TDC meeting is to use these links https://spec.openapis.org/oas/v3.1.0 etc as the normative reference.

[lornajane]

With the decision that HTML is the correct link destination, are more actions needed here?

[handrews]

@lornajane we need to add links to the past specifications on the spec site (which anyone can do - needs a bit of thought to organize for multiple specs), and add links on the LF-maintained site to the page with all of the spec links (which @swaldron58 was going to do, IIRC).

[Eusinho1985]

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]

Add links to the older versions to the spec pages (in GitHub pages)

[ralfhandl]

The Specref database entries for OpenAPI point to https://www.openapis.org/.

We probably want to add versions 3.0.0 and 3.0.1 for completeness and cross-check the authors list of each version:

• Complete OpenAPI Specification versions tobie/specref#807

@OAI/tsc please review this PR

[handrews]

@ralfhandl @lornajane I know I said I could fix the spec.openapis.org site but I keep getting bogged down in Jekyll/Liquid limitations - that is why I had semi-abandoned the branch I posted as a PR and then had to take down. I think I need to hand this off to someone else.

[lornajane]

That's fine, we can pick it up between us

[ralfhandl]

Here's a first attempt, listing all deployed spec versions on the landing page: https://ralfhandl.github.io/OpenAPI-Specification/.

This approach is dynamic and relies on available metadata:

• gh-pages: specification version lists on landing page #4013

Alternatively we could go for a static approach as we don't add new specification versions that often.