versioning for schemas, suggest that instances of the schema reference the versioned schema

[elray1]

I think we would like the schemas that are defined in this repository to be versioned -- that way, a configuration file like admin.json in a hub repository can reference the version of the admin-schema.json file that it is based on, and if we ever make changes to the schema definition, downstream tools can still process the hub's admin config settings correctly.

I'm not sure if there is a standard way to do this, but maybe we can use naming conventions like admin-schema-v0.0.1?

Then, we might expect the file like admin.json in a hub to look like this:

{
    "$schema": "https://raw.githubusercontent.com/Infectious-Disease-Modeling-Hubs/schemas/main/admin-schema-v0.0.1.json",
    "name": "Simple Forecast Hub",
    "maintainer": "Consortium of Infectious Disease Modeling Hubs",
    "contact": {
        "name": "Joe Bloggs",
        "email": "j.bloggs@cidmh.com"
    },
    "repository_url": "https://github.com/Infectious-Disease-Modeling-Hubs/example-simple-forecast-hub",
    "hub_models": [{
        "team_abbr": "simple_hub",
        "model_abbr": "baseline",
        "model_type": "baseline"
    }]
}

And in turn, admin-schema-v0.0.1.json would need to specify that such a $schema property is expected:

{
    "$schema": "http://json-schema.org/draft-07/schema",
    "title": "Hub administrative settings",
    "description": "This JSON file provides a schema for modeling hub administrative information.",
    "type": "object",
    "properties": {
        "$schema": {
            "description": "The version of the schema file used to define the administrative settings config file",
            "type": "string",
            "example": "https://raw.githubusercontent.com/Infectious-Disease-Modeling-Hubs/schemas/main/admin-schema-v0.0.1.json"
        },
        "name": {
            "description": "The name of the hub.",
            "type": "string",
            "example": "US COVID-19 Forecast Hub​"
        },
    ...
}

[nickreich]

@elray1 suggests that we enforce that URLS point to versions, and not point to a file that could be updated without the filename changing.

[elray1]

Pasting here some links that Harry had found previously:

• https://stackoverflow.com/questions/61077293/is-there-a-standard-for-specifying-a-version-for-json-schema
• https://stackoverflow.com/questions/70772942/json-schema-semantic-versioning
• https://gist.github.com/mattyod/3608613

[annakrystalli]

Agree with the general approach that can be summarised from the discussion and above links. This is what I'm proposing to do:

• Rather than keeping everything in the root of the schemas repo, we have a directory for each version e.g:
  • v0-0-1
  • v0-0-2
  • etc
• Within each directory files have their standard schema names:
  • tasks-schema.json
  • admin-schema.json
  • model-schema.json
  • etc
• In any given schema file, we use the url to the file in the repo as the $id property (which therefore includes the version).
• We add a schema_version property in all hub json config files to specify which version of the schema a hub is based on.

• We follow the following conventions in versioning schema: https://snowplow.io/blog/introducing-schemaver-for-semantic-versioning-of-schemas/. which can be summarised by:

  

Considerations:

• It will be important for ensuring breaking changes are clearly indicated through semantic versioning.
• We will also need a strategy to monitor that changes to schema do not break any hubUtils functionality.
• We will also need to monitor whether changes in hubUtils break compatibility with previous schema versions. In the case (not likely something to worry about any time soon) think about how much back compatibility we will be prepared to support.