✨ Proposal: Use github actions to publish the specs

[AxelNennker]

Describe the inspiration for your proposal

I noticed that OpenAPI references some expired Internet Draft for json-schema.
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#data-types

I have not found a place OpenAPI could link to. Neither on json-schema.org nor on this github repo.

Describe the proposal

Please consider creating a github action that calls xml2rfc and creates the spec and then publishes the files to e.g. github pages or somewhere else.

I wished json-schema.org did something like https://github.com/ietf-tools/xml2rfc/blob/main/.github/workflows/docs-publish.yml . That is, use github actions to run xml2rfc and then publish the result(s). Either on github pages, or on json-schema.org or as a github release.
Then there would be a file (txt, html, ...) for each version of the "standard" and could link to the version OpenAPI needs.
There seems to be something similar https://github.com/json-schema-org/json-schema-spec/actions in ci.yml but the artififacts are not "published".

If those "standards" are then published as IETF RFC, then all the better. But that is extra work.

Describe alternatives you've considered

No response

Additional context

No response

[gregsdennis]

Hey, @AxelNennker. Thanks for the input. A few notes:

1. We've moved away from IETF to a self-publishing model. This decision was made a couple years ago, and we're still kind of figuring out how we want to publish. First, we need to have something that we can publish.
2. The main branch is the current WIP. It's not something that we want automatically pushed (which seems to be what you're suggesting).
3. We do currently host the specifications at https://json-schema.org/specification. They were originally published as part of the IETF draft system which requires an expiration date, but these documents and the requirements they specify do not actually expire. You can consider the "draft" moniker for these to be equivalent to "version". Future versions will not have this label.

We do have a project board where we're tracking all of the things we want to do for the next version. You're welcome to have a look there to see what's planned. While several of the team had the opportunity to work on this project full time for a while, we're all volunteer now, so progress has slowed somewhat.

When we get to a point where we want to publish something, we'll definitely have a process in place for that, but I doubt it'll be anything as sophisticated as an automated publishing CI. We do have builds that check for various things, but publishing is and will likely stay a manual process.

[AxelNennker]

Nothing too automatic. In my OSS project I have a release.yaml that we run manually which then builds the artifacts and publishes them to Sonatype. In internal projects I have dedicated branches and the pipeline that is tagged with that branch does publishing whenever I merge something into that release branch.

OpenAPI spec is linking to the expired IETF draft and I just do not like linking to something expired.
OAI/OpenAPI-Specification#4127
I think that OAI could link to https://json-schema.org/draft/2020-12 instead.
OAI/OpenAPI-Specification#3934 (comment)

I like what ietf-tools is doing and I think publishing to github pages could work for json-schema-org/json-schema-spec as well. If the published pages automatically have "versions" then others could link to them.
https://github.com/ietf-tools/xml2rfc/blob/main/.github/workflows/docs-publish.yml

Maybe that could be https://json-schema-spec.github.io/2012-12 and https://json-schema-spec.github.io/draft-7 and ...

[gregsdennis]

As mentioned before, the specs should not be considered expired. That's merely an artifact of us using the IETF draft system to publish. The JSON Schema specs are used in production systems globally without issue.

Regarding having OpenAPI change their links, you'll need to talk to them. I know they're already underway on making their new version, and so are we. What that means as far as references to JSON Schema, I can't say.

The spec documents we're hosting on our site are duplicates of the IETF documents. They're unchanged, so pointing to our site or pointing to IETF makes no difference in the end.

Lastly, we do have a build that renders the spec markdown. But it wouldn't flow to the site. The site comes from the website repo. Our process for publishing would be to have it rendered here (which we currently do) and then copy the rendered version to the website repo.

I really think you need to read through our plans before you continue with this conversation, as I feel much of what you're suggesting has already been considered and documented.

https://github.com/orgs/json-schema-org/discussions/671 is a good place to start. Then have a look through some of those issues in the project board I linked to earlier.

[karenetheridge]

What do you feel is lacking on https://json-schema.org/specification ?

[AxelNennker]

What do you feel is lacking on https://json-schema.org/specification ?

Nothing really. Maybe I was blind, I did not find it from this repo's main page. Now I saw the link. I guess I should read the Readme more closely. I came from OAI, found the link to the expired drafts, searched for alternatives and newer versions, ended up in this repo, found the branches with the versions, but no "readable" documents here, no releases page.
I remembered that other github hosted standards use github actions to run xml2rfc and publishing.
Thought you might safe time if you run a github action either manually or when something is merged into main to create readable standards. Or run the publish.yaml on the versions.

But OAI can link to https://json-schema.org/draft/2020-12
Which OAI might do or not.

Thank you all for json-schema.

[ralfhandl]

But OAI can link to https://json-schema.org/draft/2020-12

OAI simply uses the Specref entries

• [json-schema-2020-12]
• [json-schema-validation-2020-12]

These Specref entries are owned by the JSON Schema team, and if they decide to update them, the OAI spec build process will pick up that change the next time it runs.

Whether the updated references point to the -01 IETF drafts or directly to the (non-expiring) documents on https://json-schema.org/ is up to the JSON Schema team.