Publication process for the spec

[gregsdennis]

We need a plan/process for the logistics of publishing the specification. This should cover:

• how we put an artifact on the website
• how we announce the publication
• ensuring consistent design between the spec and the site that hosts it

[gregsdennis]

I think for the first iteration, we just carry on doing things manually.

The website currently has:

• _includes/ - Subfolders are git submodules of this repo for each version, using branches or specific commits to identify the historical point in the repo. We need to add a v1/2026/ submodule that points to a branch that contains our latest.
• pages/ - Contains the markdown for the HTML pages which contain links to all of the static files.
• public/ - Contains all of the static resources. The specifications (both HTML and PDF versions) are pre-built and copied here. We need to build and copy v1/2026 core and validation specs into a subfolder here.

We have also moved away from the meta-schema URI ending in "schema" in favor of a meta-schema URI in the format https://json-schema.org/v1/2026, or https://json-schema.org/v1 to get the latest for v1. This means that we need these addresses to serve the JSON meta-schema file.

So, the process seems to be:

1. Build the specifications HTML pages.
2. Copy them to <website>/public/v1/2026/core.html and <website>/public/v1/2026/validation.html.
3. Copy the meta-schema to <website>/public/v1 and <website>/public/v1/2026.
4. Create <website>/pages/v1/2026/index.md and other supporting files (i.e. *.tsx files, release notes, etc.)
5. Add <website>/_includes/v1/2026 submodule.

This will allow https://json-schema.org/v1/2026 to return the JSON, but a browser navigating to https://json-schema.org/v1/2026/ (with trailing slash) will get the related index.html file. We'll need to be sure we link this properly throughout the site.

If we want to automate this, we should be able to. But it'd be good to get all of the kinks out manually before making that effort.

[jdesrosiers]

I'm fine with doing it manually and matching what we currently do. At least until it gets too annoying.

Something to consider is that I think we should be publishing the living spec as well as the snapshots.

We should also be publishing proposals in the "experimental" phase to the website. I think that's important because the expectation is that implementers should be implementing them at that point.

One thing I think is missing is styling for the spec HTML. I included some temporary styling when I created the build process, but we really should replace that styling with something that matches the website or at least uses our color scheme. It's not a blocker, but it would be nice if something was in place before we release so it doesn't look like it's from 2000.

We'll need to update https://github.com/json-schema-org/website/blob/main/public/_headers so we respond with the right headers for meta-schemas. Because they don't end with /schema anymore, the current rules won't match.

or https://json-schema.org/v1 to get the latest for v1.

I don't think https://json-schema.org/v1 should return a meta-schema. It's really just a dialect identifier and the ones ending a year are just meta-schemas.

[gregsdennis]

I don't think https://json-schema.org/v1 should return a meta-schema. It's really just a dialect identifier and the ones ending a year are just meta-schemas.

This is going to break implementations (*cough* VSCode) that try to do a web request to get the meta-schema even though we've repeatedly told them not to. That compatibility was really my only reason for wanting to support it.

[jdesrosiers]

VSCode only requests the meta-schema if it doesn't have it locally. They just need to map it to the latest meta-schema they support. Their recent partial support of 2020-12 does just that. It maps the 2020-12 URI to a flattened version of the meta schema (removing dynamic references). So, it shouldn't be a problem for them to with v1. Of course they will be making those requests until the support v1, but I don't think that's something we should be worried about.

[Kaushalendra-Marcus]

Thanks for the clarification, this helps a lot.

I’m aligned with treating /v1 strictly as a dialect identifier and keeping the year-based URLs as the actual meta-schemas, even if some implementations temporarily request /v1.

One thing that stood out to me is the note about spec HTML styling. If that’s useful at this stage, I’d be happy to help bring the spec HTML closer to the json-schema.org look and feel (colors, typography, basic layout), without changing any content or build behavior.

Separately, once the manual publication steps are settled, I’d also be interested in helping document or codify that process so it’s easier to automate later, but totally fine to keep that out of scope for now.

Let me know if either of those would be helpful.

[jdesrosiers]

@Kaushalendra-Marcus

One thing that stood out to me is the note about spec HTML styling. If that’s useful at this stage, I’d be happy to help bring the spec HTML closer to the json-schema.org look and feel (colors, typography, basic layout), without changing any content or build behavior.

I'd be happy to see a proposal for styling the spec. I've already started to work on something myself, but this isn't my area of expertise so it's mostly LLM generated and could probably be a lot better. If you want to work something up too, maybe we can take the best elements of both and end up with something better.

[Kaushalendra-Marcus]

@jdesrosiers Thanks! That sounds great.
I’ll put together a minimal styling proposal for the spec HTML that better matches the json-schema.org look and feel, without changing content or build behavior.
If you have any preferences or ideas you’d like me to keep in mind before I start, happy to align.

I’ll share it once it’s ready