Make the "latest" schema accessible programmatically

[handrews]

trafficstars

We don't want schema URIs with latest in place of the date because schema contents should not change unexpectedly. However, we need some way for folks to access the latest schemas, preferably without pulling all of the dates and sorting them.

Unfortunately, GitHub pages does not support HTTP redirects (or setting media types independent of file extensions) so we need to figure out a workarond. Or move to Netlify or Cloudflare Pages or something else with actual proper HTTP support.

[LasneF]

another alternative would be to push it to a code repo like npm that handle this kind of versionning policy

[cboitel]

From a user perspective, i would expect to be able to access the latest schema for a specific OpenAPI version so i can validate an OpenAPI specification document from it.

E.g. :

1. open document, extract version
2. download schema for version (/vX.Y.Z/schema)
3. validate doc with downloaded schema

NPM targets only Javascript ecopsystems: what about rust/golang/c++/... ?

Having an OpenAPI documented API which describes all operations available at specs.openapis.org would also be a must-have.

Hope it helps.

[seriousme]

Hi,

If you use a symbolic link in the GH-pages branch (say from latest to 2024‑11‑14 then toolmakers that poll latest will notice that there is a new version and can work from there, also via HTTPS.

Currently my tooling just checks out the GH-pages branch once a week and compares what I have to what is there to find updates. Every now and then I need to tune the mechanism a bit to accomodate for slight changes in the branch structure.

For me it would be brilliant if:

• schema files explicitly have the .json extension, or are not surrounded by other , non-schema files. (e.g. I now need to filter out HTML files)
• there would be a single folder with all the latest patch versions per minor version (e.g. like https://github.com/seriousme/openapi-schema-validator/tree/master/schemas) with a either a distinct folder or clear naming convention between base and full schema.
• archived versions are in a separate folder.

Even better would indeed be an NPM/Python/Go package, but I can see that this could become messy for the OAI project. So you could argue that packaging it up should be left to the community of the specific language. I'd be happy to publish the schema's on NPM, separated from the rest of my tooling.

Alternatively there's sites like: https://www.schemastore.org/ which just publish the schema.

Hope this helps!

Kind regards, Hans

[ralfhandl]

@seriousme Hi Hans,

I like your proposals. Unfortunately I don't see how we could implement them with Jekyll, so this issue depends on

• #4153

[AaronNGray]

What about using Astro ?

https://docs.astro.build/en/guides/deploy/github/

https://github.com/withastro/github-pages

[ralfhandl]

What about using Astro ?

Scanning the Astro documentation it seems that server-side redirect from a „latest“ schema URL to the date-stamped schema URL requires server-side rendering and deploying to Netlify or Cloudflare Pages and does not work with Github Pages.

https://docs.astro.build/en/reference/configuration-reference/#redirects

If we decide to host the site on Netlify or CloudFlare, then Astro is a possible alternative to Jekyll.

[lornajane]

I expect us to move away from GitHub pages, agree that Astro should definitely be a candidate!

[jdesrosiers]

FYI, JSON Schema solves this problem by deploying to Cloudflare Pages instead of Github Pages. They have a couple of well-known files you can place in your static site that the platform will use to do redirects and apply headers. For example, see the _headers and _redirects files in the JSON Schema website repo.

This solution doesn't require any anything server-side that you have to host, so it can be implemented with or without rewriting the site to use a new framework. Just add the files.

[karenetheridge]

A 307 redirect combined with a Cache-Control: max-age=3600 response header would be most welcome.

(The existence of the caching header should be documented next to the existence of a .../latest link itself, so that implementors know that they should internally cache the resulting file somewhere as well as its longevity. Schema files should never be used "live" from a download as they can and do change in surprising ways sometimes -- users should always know what exactly what edition of a file they're working with.)

[seriousme]

Hi,

My automation used to clone the OAS Github pages branch to detect any OAS schema updates and/or new versions. I used this to add new/updated OAS versions to https://github.com/seriousme/openapi-schema-validator/ That GitHub pages branch is gone now and the specs folder has been archived.

In theory I could parse the HTML at https://spec.openapis.org/oas/ but that sounds rather britle to me.

Is there any way I can give my automation access to the JSON files again ?

Kind regards, Hans

[ralfhandl]

The GitHub Pages source has moved to repository https://github.com/OAI/spec.openapis.org, which is linked from the page footer on each page of https://spec.openapis.org.

The OpenAPI schemas are in subfolders of folder oas, by spec minor version.

Exactly the same layout as the former gh-pages branch.

Sorry for the inconvenience!

[seriousme]

Many thanks for the quick reply, I have the automation working again.

Kind regards, Hans