Versioning in JSON Schema

[Jesus89]

In GeoParquet, the geo metadata contains a field version which is the version of the spec. We are following the semantic versioning style. This is the JSON Schema currently implemented to validate the version:

{
  "version": {
    "type": "string",
    "pattern": "^0\\.2\\.[0-9]+$",
    "description": "The version of the geoparquet metadata standard used when writing."
  }
}

The purpose of using a regular expression was to be flexible regarding patch releases until 1.X. Should we keep regex or should we use fixed value instead? Should we wait for fixed values after 1.X?

Another thing to discuss is how to keep previous versions. We can use GitHub tags, or we can store all the versions in folders (like in tilejson-spec). Using GitHub tags seems to be the proper/modern way of versioning, however, using folders has advantages too, for example, easy checking between versions.

[brendan-ward]

From an implementer standpoint, having the description of each spec in a dedicated markdown file is very helpful; I've often used this for reference of the tilejson-spec. Hower, that can serve more the role of a visible archive than having to preserve all the associated assets, so a combination of tagging and adding to a previous versions folder is helpful. Tags for managing all the assets that should change on each version, then each time a version is rolled out, moving the previous format-specs/geoparquet.md to format-specs/previous/geoparquet-<version>.md.

Then once 1.x is available, maybe move previous folder to pre-1.0 just to keep that clear, and previous then receives the contents of updates within that major version.

This keeps the spec itself very visible, but if someone needs the validator for a given version, they can easily use git tags to get it.

[kylebarron]

I'm in favor of fixed const version numbers, because that prevents you from using one version of the spec's json schema against another version's data file. If the const check fails, then that's a very quick way to see where your issue lies. It's a lot harder if the json schema fails elsewhere to realize "oh this is failing because my version number isn't matching". In terms of prior work, the STAC json schema uses const.