Skip to content

hubverse-org/schemas

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Modeling Hub Schemas

JSON Schema Valid

This repository houses JSON schemas for the Consortium of Infectious Disease Modeling Hubs. These schemas define the specifications for the configuration files that are required to be present in a modeling hub. Full documentation about modeling hubs can be found at the Modeling Hub documentation site, with some specific documentation about the schema files.

Versioning

Schemas will be directly versioned, with different versions living in different folders in the root directory of the repo with a name as vx.x.x (for example, v0.0.1). Any finalized change to any of the three schema files that is added to the main branch will result in the addition of a new set of all schema files. To determine an appropriate version number for the next version, follow semantic versioning principles.

Wen creating new versions and making changes to the schema file, make sure to record important user facing changes in NEWS.md.

Schema documentation

The HubDocs documentation site is the primary location for documenting schema usage. It is also versioned by using releases and should track releases in this repository.

After making a new release to the schema repository, ensure hubDocs are also appropriately updated and an associated new release in the hubDocs repository also created.

New schema version development process

  • New schema versions should be developed in a separate branch. Name the branch br-v{version-number} to avoid creating release tags which share the same name as a branch later on.
  • Test out the implications of the changes across the hubverse. Checking that nothing breaks in hubAdmin is the first step but you'll need to think carefully about potential implcations in other areas and explicitly check and test for these implications. The following steps will help you queue up tests for under development schema.
    • Update the development (GitHub) version of hubUtils with the new under development version of the schema by following the instructions provide in the hubUtils CONTRIBUTING guide. Once you install this version locally, you can then use it to start testing the implications of the new schema on other aspects of the hubverse locally first. To make the new development schema available to packages for testing in PRs using CI, the new dev version will need to be merged into the hubUtils main branch. The idea behind the workflow is to merge new under development schema versions into the hubUtils main branch early. If any changes are made to the under developent schema version in the br-v{version-number} branch, just re-update it in hubUtils, create a new PR and merge to make the updates available for CI testing.
    • Once the under development schema version is available in hubUtils, start by re-running all tests in hubAdmin. This should advise you of any breaks introduced to our codebase as a result of schema changes. Address any introduced problems.
    • Next you'll want to ensure that any new properties introduced in the new schema are implemented in the associate create_*() family of functions that enables programmatic creation of config files. For features that should only be available before, after or for specific schema versions, the hubUtils version_*() family of functions can be helpful. When writing new tests for the create_*() family of functions, you can set the version used for testing through global option "hubAdmin.schema_version" and use it in testing by configuring in with withr::with_options().
    • If the changes in the schema result in the requirement for dynamic validation of tasks.json config files (which are not covered by basic json validation), you'll need to write appropriate testing functions and include them in the perform_dynamic_config_validations().
    • You'll finally need to ensure that validation of the new features works as expected by including new tests using new test config files and using the validate_config() function. Make sure you include tests using files that should pass validation as well as that correctly flag config file errors. Note that for testing config files against specific versions you can use the schema_version directly istead of setting global options.
    • Follow a similar proceedure for any other packages/areas of the hubverse which might be affected by the schema changes, i.e. 1) run all tests to make sure nothing breaks and fix anything that does 2) add new functionality and appropriate tests that make use of new schema features.
    • Once you have tested all implcations across the hubverse you are ready to release the schema.
  • New version branches should be merged into main when ready to released.
  • Merging into main should be accompanied by creating an associated formal release in the repository.
  • Once the new schema version is merged into main is released, update the version in hubUtils to use the main branch, open a PR, merge and make a release of hubUtils.
  • Then you can update any pull requests queued up in other packages and ensure they use the latest released hubUtils version as a minimum requirement.
  • Update HubDocs site with any additional relevant information associated with the new schema release.
  • Create a new release on hubDocs using the same version number but without the v (e.g. v0.0.1 would be released as 0.0.1 on hubDocs).
  • Update the hubTemplate config to reflect the most up to date schema. Create a new release using the same version.

Highlighting changes to schema in PRs

To bring attention to the changes in new schema versions, it's useful to include in any PR, a print out of the diffs in the tasks-schema.json and admin-schema.json files compared to the previous version.

Automated Process (via GitHub)

After you create a new Pull Request, if you create a new comment with /diff, GitHub will automatically generate the diffs of the tasks-schema.json and admin-schema.json and comment on the pull request.

If you need to update the schema after review, you can update the diffs by creating another /diff comment.

If this does not work for any reason, you can follow the manual process below.

Manual Process

To print the diffs in each file you can use the following commands in the terminal:

admin-schema.json

diff -u --color=always $(ls -d */ | sort | tail -n 2 | head -n 1)admin-schema.json $(ls -d */ | sort | tail -n 1)admin-schema.json

tasks-schema.json

diff -u --color=always $(ls -d */ | sort | tail -n 2 | head -n 1)tasks-schema.json $(ls -d */ | sort | tail -n 1)tasks-schema.json

💡 Tips

Show diff colours in PR

To show the colour of the diffs in the PR, wrap the output of the commands in a diff code block, e.g.

```diff
- old line
+ new line
```
is rendered in the PR renders as:

- old line
+ new line

Send output directly to clipboard

Depending on your system (macOS or Linux), you can pipe the output of the above commands directly to the clipboard. See examples below:

macOS:
diff $(ls -d */ | sort | tail -n 2 | head -n 1)tasks-schema.json $(ls -d */ | sort | tail -n 1)tasks-schema.json | pbcopy
Linux:

Make sure xclip is installed. You can install it using your package manager, e.g., sudo apt-get install xclip on Debian-based systems.

diff $(ls -d */ | sort | tail -n 2 | head -n 1)tasks-schema.json $(ls -d */ | sort | tail -n 1)tasks-schema.json | xclip -selection clipboard