Make the "latest" schema accessible programmatically

[handrews]

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

• Consider alternatives to GitHub Pages spec.openapis.org#31

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