Schema publishing

[letmaik]

Now that we're getting close to making a first release of the spec and hence JSON schema, we need to decide where to host it under a stable URL (ideally).

The current dev schema is at:
https://raw.githubusercontent.com/covjson/covjson-validator/gh-pages/schema.json.

I was thinking something like:
https://covjson.org/schemas/1.0/coveragejson.json

It's also best practice to include that URL in $id of the schema, which currently is /schemas/coveragejson.

To avoid any doubt, the schema we'd publish is the draft-07 downgraded variant for widest compatibility.

The publication and $id fixing should be automated somehow, though I'm not sure yet exactly on the flow.

[jonblower]

I agree - that URL looks sensible to me.

I was thinking of declaring a release candidate (e.g. 1.0-RC1) and letting people use it for a while - what do you think? If so we could tag the current HEAD with that string.

Not sure how to automate the publication and $id fixing but we won't be publishing new versions very often so in principle I don't mind doing it manually.

[letmaik]

Another thing to think about is that the CovJSON spec has a version, and the validator itself has a version, but they're not necessarily the same. The schema $id should correspond to the spec version. The validator repo may host tools and schemas for supporting multiple spec versions eventually and therefore the validator version may be independent of the rest.

Long story short, I think it's fine to tag this repo with 1.0.0-rc.1 following https://semver.org/. Then, separately from that, we can think about publishing the schema to the website, maybe even unversioned for now until we have a better idea. Maybe https://covjson.org/schema/coveragejson.json?

[jonblower]

Yes, I'll tag the repo as 1.0.0-rc.1, sounds good. It would be good to publish the schema to the website so people can start using it. The URL looks fine, but should the version number be in the URL as well?

Hopefully we're not far from a 1.0 release of the spec itself (via the OGC group) so I guess we can add this to the schema when it's done.

[letmaik]

I would publish the schema to https://covjson.org/schema/dev/coveragejson.json and remove $id from it. This could then always be the latest in-development schema for the upcoming spec version. For 1.0, we can put it under https://covjson.org/schema/1.0/coveragejson.json with $id being that same URL.

[letmaik]

This is done now for dev:
https://covjson.org/schema/dev/coveragejson.json

The playground also consumes that schema now by default. Once 1.0 is out, it can be switched over to that.

Let's leave this issue open until we've documented the process and have gone through the 1.0 release.

[jonblower]

Brilliant, thanks!

[jonblower]

I guess the README is the best place to document the process for building the bundled schema (and publishing it, and finding it)?

Also, should we create a GitHub Release (or pre-release) based on the 1.0.0-rc1 tag? I'm not sure exactly what that entails, but I guess the release bundle only needs to contain the built schema?

[letmaik]

I guess the README is the best place to document the process for building the bundled schema (and publishing it, and finding it)?

Yes, and probably the website repo should have a backlink to this repo in case someone starts looking there first. EDIT: done

Also, should we create a GitHub Release (or pre-release) based on the 1.0.0-rc1 tag? I'm not sure exactly what that entails, but I guess the release bundle only needs to contain the built schema?

Sure, I'll create one. I think automating that with GitHub Actions makes sense, I'll try to do that for the next release. EDIT: postponing this