Define and document our schema publishing process

[handrews]

We need to figure this out, so I'm extracting the recent/relevant comments from #151 as it is so old and long that potential contributors are discouraged from figuring out where they might help.

In addition to what's discussed below, we might want to think about how people might find different schema versions readily visible in GitHub on main that differ from the gh-pages-published ones. This will be less of a concern if schema work moves to release branches as is being considered in #3677 and #3716. Separately, see also #2400 for discussion of publishing the schemas through NPM; this issue is just for publishing them ourselves.

---

From @handrews (#151 (comment))

I think we agreed this should be the issue tracking how/when we deploy schema updates. Including deploying new revisions of the OAS 3.1 JSON Schema vocabulary and dialect meta-schemas which don't currently have dates in their $ids. Which I think happened because I wrote them as tentative proposals and then by the time OAS 3.1 shipped I wasn't around to catch that sort of thing.

---

From @jdesrosiers (#151 (comment))

I've been handling schema deployment. I don't usually prepare a deployment for every change, but tend to wait a little while in case more changes come in (they usually come in waves). There are currently two changes that have been merged but not deployed yet and one open PR.

Here's the process I've been following for deployment

1. Update release dates in
   • schema.yaml
   • schema-base.yaml (Don't forget the one in the $ref)
   • tests/v3.1/test.js
2. Generate the JSON versions from the YAML versions
   • The README says to only modify the YAML version, but contributors usually include changes to both. So, this step is usually just a sanity check.
3. Run the tests
   • The tests are very minimal and haven't been added to since they were first added, but I make sure that we at least don't break what we have.
4. Deploy the schemas
   • Add the schemas to the gh-pages branch
   • Update the latest symlink to point to the newest version
5. Other stuff I'm forgetting about ???

Here's an example of a deploy I've done in the past

• Publish v3.1 schemas version 2022-10-07 #3042
• Publish 3.1 schemas for version 2022-10-07 #3043

Including deploying new revisions of the OAS 3.1 JSON Schema vocabulary and dialect meta-schemas which don't currently have dates in their $ids. Which I think happened because I wrote them as tentative proposals and then by the time OAS 3.1 shipped I wasn't around to catch that sort of thing.

Actually, I wrote those meta-schemas. I didn't include a date in the schema for the same reasons we don't include one in JSON Schema meta-schemas. The $ids of meta-schemas are what schemas authors use in $schema to indicate the version of JSON Schema their schema is using. If we version meta-schemas, users would need to update all of their schemas that declare this dialect every time we release a bugfix. There are lots of reasons that's not a good user experience.

To avoid this, at JSON Schema, any time we need to make a fix in the meta-schema, we've always just fixed it and kept the same $id. This has never cause a problem. I intended for these meta-schemas to be maintained the same way, but so far, there hasn't been a need to update the vocabulary/dialect meta-schemas.

Ideally, I'd think that meta-schemas probably should be versioned, but there should also be an unversioned URI that's effectively a redirect to latest version that the vast majority of users would use for $schema rather than the versioned URI.

I'm happy to hand the schema maintenance and deployment process over to whoever wants it. I've always just done the minimum to keep it afloat, so it would benefit from someone actually putting effort into improving this process.

---

from @handrews (#151 (comment))

The date-in-$id policy should be the same for all the OAS schemas (whether they are JSON Schema meta-schemas or not). I'm fine with whatever policy @OAI/tsc wants (date or no date), as long as it is consistent. Having two different policies is worse UX than either individual policy. (Also, my apologies for mis-remembering who wrote those!)

[handrews]

Consolidating #2794 here as well: We need to decide which schemas, if any, get "latest" links, and make sure they work as expected. The fact that there are currently different behaviors for different schema documents is related to how some schema documents need date-containing $ids but don't currently have them.

Since a "latest" link to a schema means you will get different schemas (and therefore different outcomes) depending on when you reference the link, I generally oppose them. In theory 300 Multiple Choices with the date-containing-URI of the latest version placed in the Location header and other URIs in Link headers with rel=alternate would be the ideal way to handle that, although idk how many clients would be able to make sense of it.

[TakahikoKawasaki]

The following scripts can alleviate the workload of the bugfix and publication processes to some extent.

• scripts/update-schema-id (PR [new] scripts/update-schema-id #3790)
• scripts/update-schema-latest (PR [new] scripts/update-schema-latest #3791)

[ralfhandl]

• Update the latest symlink to point to the newest version

This comment suggests that

we should not have a "latest" schema symlink because refining the constraints to be more accurate could cause automated systems to suddenly invalidate previously-valid OADs which is not a nice thing to do

This PR will remove the "latest" download link on the landing page:

• gh-pages: no download link for "latest" schema #4133

[ralfhandl]

Note

The new publishing process MUST rename the wrapper markdown pages for date-named schema files to match the most recent schema file.

[lornajane]

Some outlines of schema publishing are now in the contributing file https://github.com/OAI/OpenAPI-Specification/blob/main/CONTRIBUTING.md#publishing but it doesn't cover everything in scope for this issue.

[ralfhandl]

it doesn't cover everything in scope for this issue

What is missing, and where?

Contributing to the schemas seems to be covered in CONTRIBUTING.md.

The publishing process itself, including details discussed above, is codified in the schema-publish workflow and its components.