confusion with schema references in the spec and on the website

[karenetheridge]

https://spec.openapis.org/oas/latest#dialect-schema-id (as of this date, mapping to v3.1.1) references the schema URL https://spec.openapis.org/oas/3.1/dialect/base. This URL does actually resolve, and produces a json schema document with that URL as its $id.

However, my understanding is that the latest version of the dialect schema is in fact https://spec.openapis.org/oas/3.1/dialect/2024-10-25. At the moment these files are semantically equivalent, but this could change over time. We should be clear about which document is canonical, and update all references to it in documents we consider "current". (We shouldn't delete the files from the website entirely, as some implementations may still be using them. It might be useful to get some download stats?)

Further, the spec makes no mention of the schema used to describe the OAD itself, which (I believe) is currently https://spec.openapis.org/oas/3.1/schema/2024-11-14. There are no links to this document (or the dialect schema) on the website anywhere else that I can see either.

We should clearly mention in the spec the URLs of all four of the schemas used by the specification, which are:

• https://spec.openapis.org/oas/3.1/dialect/2024-10-25
• https://spec.openapis.org/oas/3.1/meta/2024-10-25
• https://spec.openapis.org/oas/3.1/schema-base/2024-11-14
• https://spec.openapis.org/oas/3.1/schema/2024-11-14

This would be sufficient given that the link to the specification itself is quite prominent on the website, and I think it would be unlikely that we would revise these schemas in between spec releases (indeed, such a revision would merit a point release of the spec).

There might be some tooling that can help with keeping the dates in sync -- for example using the same placeholders in the spec document as in the schema files itself, and then all files are updated at once when performing the spec-publish action (which I hope is separate from the web-publish action, as we ought to have a copy of the published spec actually in the spec repository, not just in the website).

[ralfhandl]

using the same placeholders in the spec document as in the schema files itself, and then all files are updated at once

We intentionally split spec publishing and schema publishing to allow for faster schema iterations.

The specs are published from main, the schemas are published from vX.Y-dev.

Maybe it is sufficient to use visible YYYY-MM-DD placeholders in the spec text that are not replaced with the volatile schema publication date.

And link to an overview page for the schemas, or the schema section on the landing page.

[karenetheridge]

Side note: it would still be useful for the website to have a page listing all schemas, including historical ones, because it's quite possible that people are using older versions. Although anyone in this situation should have the URL and that URL should continue to resolve, but it would be nice to have an index of all versions we've ever published just for comparison.

In my own implementation, I only bundle the latest versions of the schemas, so if someone is explicitly referring to an older one, they'd need to download that from the website.

I'd move this comment to be an issue for the website itself, but it doesn't seem to have a repository of its own, nor any link on its site for providing feedback.

[handrews]

@karenetheridge don't we already show all historical schemas at the bottom of the page on https://spec.openapis.org/ ?

[karenetheridge]

That's an odd question. Are you asking me or telling me?

[ralfhandl]

it would be nice to have an index of all versions we've ever published just for comparison

I think we have exactly that on https://spec.openapis.org/#openapi-specification-schemas, listing all published schema iterations by spec version.

What is missing?

(Apparently I should have made that link more noticeable in my answer above.)

[ralfhandl]

I'd move this comment to be an issue for the website itself, but it doesn't seem to have a repository of its own

It is built from the gh-pages branch of the spec repo, please open issues in the spec repo.

nor any link on its site for providing feedback

That would be a good issue: add link for providing feedback to the spe publishing site.