🆕 Schemas v5 release on 2025-01-17

2025-01-17-schema-v5.md

On 2025-01-17, the hubverse development team released the v5 schemas.

This release contains the following changes:

• Added explicit checks of round_id format through a regex pattern check to the round.round_id property when round.round_id_from_variable is false. This provides upfront validation of the expected format of manually-supplied round IDs (i.e. those not sourced from a task ID) (hubverse-org/schemas#112).
• BREAKING CHANGE: Restricted the target_metadata.target_keys object to contain only a single key value pair (if not null). This means that target keys can now only consist of a single value from a single task ID (hubverse-org/schemas#117).
• BREAKING CHANGE The target_variable and target_outcome properties are removed from the standard Task IDs that can be validated against the schema (hubverse-org/schemas#117).

The decision for the breaking change is based on the one recorded in LDR 2024-12-11 and the announcements to the discussion board (https://github.com/orgs/hubverse-org/discussions/34) and the mailing list (https://groups.io/g/hubverse/message/24). We have investigated all publicly available hubs and determined that the breaking change will not adversely affect any existing hubs.

Updating to v5

Note

If you have not updated to v4, then be sure to follow the instructions in the Schema v4 release announcement.

Check the following:

• round IDs are either an ISO 8601-formatted date (YYYY-MM-DD) or an alphanumeric sequence with underscores (_).
• each target_metadata.target_keys object contains only a single key value pair.

If both of the above are correct, then you should be able to transition smoothly from v4 to v5 by changing the version number in the schema_version property of your config files.

Discussion

The updates to the round ID requirements are a formalization of validation measures we were already assuming in the hubValidations code.

With respect to restricting target_metadata.target_keys to a single key-value pair: the ability to use multiple key-value pairs with target_keys was a concept that would allow hub administrators to specify multiple targets and partition them in conceptual categories of variable and measures (e.g. 3 outcome variables ("hospitalizations", "cases", "deaths") combined with 2 outcome measures ("incident count", "cumulative count") would give you a total of six targets ("incident count hospitalizations", "incident count cases", "incident count deaths", "cumulative count hospitalizations", "cumulative count cases", "cumulative count deaths")).

As described in LDR 2024-12-11, our downstream tools (e.g. dashboards and evaluations) do not support multiple keys and their implementation represents additional complexity. Because it is trivially possible to manually curate these targets into one variable, we determined that the cost to implement and maintain functionality for multiple target keys was greater than the benefit.

If you use multiple target keys in your hub and would like migration support, please feel free to reach out.