diff --git a/README.md b/README.md
index 4630c04b..98ab7861 100644
--- a/README.md
+++ b/README.md
@@ -92,7 +92,11 @@ To use Live Server:
4. To disconnect the server, click on :no_entry_sign:.
+# Versioning
+Documentation is [versioned by using releases](https://docs.readthedocs.io/en/stable/versions.html). Releases should track releases of Hub schema versions in [`schemas` repository](https://github.com/Infectious-Disease-Modeling-Hubs/schemas). While changes to documentation text can be commited without creating a new release and will appear in th `latest` version of the documentation, **changes to documentation related to a new schema release must be accompanied by a new release in this repository**. New releases on `hubDocs` should use the same version number as the `schemas` release but without the `v` (e.g. a `v0.0.1` `schemas` version number would be released as `0.0.1` on `hubDocs`).
+
+Before making a new release, **ensure that URLs to schema files which power the interactive docson widget visualisation of schemas in the [`docs/source/format/hub-metadata.md` page](https://github.com/Infectious-Disease-Modeling-Hubs/hubDocs/blob/main/docs/source/format/hub-metadata.md?plain=1) are updated** to display the new versions of `admin.json` and `tasks.json` schema files.
## Contribution guidelines
In general, contributions should be made via pull requests to the `main` branch.
diff --git a/docs/source/conf.py b/docs/source/conf.py
index e0dda9c0..abad9d8b 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -37,6 +37,7 @@
"deflist",
"dollarmath",
"fieldlist",
+ "substitution"
]
# -- Options for HTML output
@@ -59,3 +60,8 @@
# -- Options for EPUB output
epub_show_urls = 'footnote'
+
+
+myst_substitutions = {
+ 'schema_version': "v0.0.1"
+}
diff --git a/docs/source/format/hub-metadata.md b/docs/source/format/hub-metadata.md
index 07a91fb2..fd65b78e 100644
--- a/docs/source/format/hub-metadata.md
+++ b/docs/source/format/hub-metadata.md
@@ -36,8 +36,9 @@ These are described separately in the following subsections.
The administrative hub metadata file contains settings that are expected to remain fixed throughout a hub’s existence, or for which it is not required to retain past values in order to work with hub data.
+### Hub administrative metadata (`admin.json`) Interactive Schema
-
+
Other things we may want to consider adding here:
* Something about truth data?
@@ -46,141 +47,8 @@ The administrative hub metadata file contains settings that are expected to rema
(tasks_metadata)=
## Hub model task metadata (`tasks.json` file)
-The hub model task metadata file specifies the model tasks and model output formats for the hub. To reduce redundancy, hubs may optionally specify a 'defaults' entry with values that apply unless they are overridden by round-specific entries; this may be particularly useful for forecast hubs, which typically accept the same formats for all rounds.
-
-
-The hub model task metadata should follow this format:
-
-
-* Top level object
- * property named `“model_tasks”`, which is an object
- * Each element of the model_tasks object corresponds to one submission round; its name specifies the round id. Hubs may optionally specify one entry named `“default”`, with settings that apply to all rounds; as noted above, this will primarily be of use in forecast hubs. The element for a single submission round is an array.
- * Each element of the array for a single submission round is an object with two properties: `“task_ids”` and `“output_types”`.
- * “Task_ids”
- * Optionally, the top level object may contain other objects that define model task or output type definitions that are referenced multiple times.
-
-```json
-{
- "model_tasks": [
- "default": [
- {
- "task_ids": {
- "location": {
- "required": {
- "$ref": "#/$defs/task_ids/location/us_states"
- },
- "optional": {
- "$ref": "#/$defs/task_ids/location/us_counties"
- },
- },
- "age_group": {
- "required": {
- "$ref": "#/$defs/task_ids/age_group/all_ages"
- },
- "optional": {
- "$ref": "#/$defs/task_ids/age_group/age_subdivisions"
- },
- },
- "horizon": {
- "required": null,
- "optional": {
- "$ref": "#/$defs/task_ids/horizon/valid_horizons"
- },
- },
- "outcome_variable": {
- "required": null,
- "optional": {
- "$ref": "#/$defs/task_ids/outcome_variable/cases"
- },
- }
- },
- "output_types": {
- "mean": {
- "required": false
- },
- "bin_prob": {
- "required": {
- "$ref": "#/$defs/output_type_ids/short_term_inc_bins"
- },
- "optional": null
- }
- }
- },
- {
- "task_ids": {
- "location": {
- "required": {
- "$ref": "#/$defs/task_ids/location/us_states"
- },
- "optional": null,
- },
- "age_group": {
- "required": {
- "$ref": "#/$defs/task_ids/age_group/all_ages"
- },
- "optional": {
- "$ref": "#/$defs/task_ids/age_group/age_subdivisions"
- },
- },
- "horizon": {
- "required": null,
- "optional": {
- "$ref": "#/$defs/task_ids/horizon/valid_horizons"
- },
- },
- "outcome_variable": {
- "required": null,
- "optional": {
- "$ref": "#/$defs/task_ids/outcome_variable/hosps_and_deaths"
- },
- }
- },
- "output_types": {
- "mean": {
- "required": false
- },
- "cdf": {
- "required": [10.0, 20.0],
- "optional": null
- }
- }
- },
- {
- "task_groups":
- "output_types":
- },
- ],
- "round-1": [
- // if needed, a complete specification of settings for round 1 here
- ],
- "round-2": [
- // if needed, a complete specification of settings for round 2 here
- ]
- ],
-
-
- "$defs": {
- "task_ids": {
- "location": {
- "us_nat_states": ["US", "01", "02", ..., "56"],
- "us_counties": ["01001", ..., "56045"]
- },
- "age_group": {
- "all_ages": ["all_ages"]
- "age_subdivisions": ["0-5 yr", ..., "65+ yr"]
- },
- "horizon": {
- "weekly_horizons": [1, 2, 3, 4],
- "daily_horizons": [1, .., 28]
- },
- "outcome_variable": …
- }
- }
-}
-```
-
-With options for `task_ids` and forecast representations broken down into those that are required and those that are optional, with valid values/combinations of values specified using something like a `$ref` to a top-level list of options.
+The hub model task metadata file specifies the model tasks and model output formats for the hub.
### Model Tasks (`tasks.json`) Interactive Schema
-
+