{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/hubverse-org/schemas/blob/main/v0.0.0.9/tasks-schema.json",
  "title": "Hub model task definitions",
  "type": "object",
  "properties": {
    "schema_version": {
        "type": "string",
        "format": "uri"
    },
    "rounds": {
      "description": "Array of modeling round properties",
      "type": "array",
      "items": {
        "type": "object",
        "description": "Individual modeling round properties",
        "properties": {
          "round_id_from_variable": {
            "description": "Whether the round identifier is encoded by a task id variable in the data.",
            "type": "boolean"
          },
          "round_id": {
            "description": "Round identifier. If round_id_from_variable = true, round_id should be the name of a task id variable present in all sets of modeling task specifications",
            "examples": ["round-1", "2022-11-05", "origin_date"],
            "type": "string"
          },
          "round_name": {
            "description": "An optional round name. This can be useful for internal referencing of rounds, for examples, when a date is used as round_id but hub maintainers and teams also refer to rounds as round-1, round-2 etc.",
            "examples": ["round-1"],
            "type": "string"
          },
          "model_tasks": {
            "type": "array",
            "description": "Array defining round-specific modeling tasks. Can contain one or more groups of modeling tasks per round where each group is defined by a distinct combination of values of task id variables.",
            "items": {
              "type": "object",
              "properties": {
                "task_ids": {
                  "description": "Group of valid values of task id variables. A set of valid tasks corresponding to this group is formed by taking all combinations of these values.",
                  "type": "object",
                  "properties": {
                    "origin_date": {
                      "description": "An object containing arrays of required and optional unique origin dates. Origin date defines the starting point that can be used for calculating a target_date via the formula target_date = origin_date + horizon * time_units_per_horizon (e.g., with weekly data, target_date is calculated as origin_date + horizon * 7 days)",
                      "examples": [{
                        "required": null,
                        "optional": ["2022-11-05", "2022-11-12", "2022-11-19"]
                      }],
                      "type": "object",
                      "properties": {
                        "required": {
                          "description": "Array of origin date unique identifiers that must be present for submission to be valid. Can be null if no origin dates are required and all valid origin dates are specified in the optional property.",
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string",
                            "format": "date"
                          }
                        },
                        "optional": {
                          "description": "Array of valid but not required unique origin date identifiers. Can be null if all origin dates are required and are specified in the required property.",
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string",
                            "format": "date"
                          }
                        }
                      },
                      "required": [
                        "required",
                        "optional"
                      ]
                    },
                    "scenario_id": {
                      "description": "An object containing arrays of required and optional unique identifiers of each valid scenario.",
                      "examples": [{
                          "required": null,
                          "optional": [1, 2, 3, 4]
                        },
                        {
                          "required": null,
                          "optional": ["A-2021-03-28", "B-2021-03-28", "A-2021-04-05", "B-2021-04-05"]
                        }
                      ],
                      "type": "object",
                      "properties": {
                        "required": {
                          "description": "Array of identifiers of scenarios that must be present in a valid submission. Can be null if no scenario ids are required and all valid ids are specified in the optional property.",
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": ["integer", "string"]
                          }
                        },
                        "optional": {
                          "description": "Array of identifiers of valid but not required scenarios. Can be null if all scenarios are required and are specified in the required property.",
                          "type": [
                            "null",
                            "array"
                          ],
                          "items": {
                            "type": ["integer", "string"]
                          }
                        }
                      },
                      "required": [
                        "required",
                        "optional"
                      ]
                    },
                    "location": {
                      "description": "An object containing arrays of required and optional unique identifiers for each valid location, e.g. country codes, FIPS state or county level code etc.",
                      "examples": [{
                        "required": "US",
                        "optional": ["01", "02", "04", "05", "06", "08", "09", "10", "11", "12", "13", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "41", "42", "44", "45", "46", "47", "48", "49", "50", "51", "53", "54", "55", "56"]
                      }],
                      "type": "object",
                      "properties": {
                        "required": {
                          "description": "Array of location unique identifiers that must be present for submission to be valid. Can be null if no locations are required and all valid locations are specified in the optional property.",
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          }
                        },
                        "optional": {
                          "description": "Array of valid but not required unique location identifiers. Can be null if all locations are required and are specified in the required property.",
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "required",
                        "optional"
                      ]
                    },
                    "target": {
                      "description": "An object containing arrays of required and optional unique identifiers for each valid target.",
                      "type": "object",
                      "examples": [{
                        "required": null,
                        "optional": ["weekly rate"]
                      }],
                      "properties": {
                        "required": {
                          "description": "Array of target unique identifiers that must be present for submission to be valid. Can be null if no targets are required and all valid targets are specified in the optional property.",
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          }
                        },
                        "optional": {
                          "description": "Array of valid but not required unique target identifiers. Can be null if all targets are required and are specified in the required property.",
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "required",
                        "optional"
                      ]
                    },
                    "target_date": {
                      "description": "An object containing arrays of required and optional unique target dates. For short-term forecasts, the target_date specifies the date of occurrence of the outcome of interest. For instance, if models are requested to forecast the number of hospitalizations that will occur on 2022-07-15, the target_date is 2022-07-15",
                      "examples": [{
                        "required": null,
                        "optional": ["2022-11-12", "2022-11-19", "2022-11-26"]
                      }],
                      "type": "object",
                      "properties": {
                        "required": {
                          "description": "Array of target date unique identifiers that must be present for submission to be valid. Can be null if no target dates are required and all valid target dates are specified in the optional property.",
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string",
                            "format": "date"
                          }
                        },
                        "optional": {
                          "description": "Array of valid but not required unique target date identifiers. Can be null if all target dates are required and are specified in the required property.",
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string",
                            "format": "date"
                          }
                        }
                      },
                      "required": [
                        "required",
                        "optional"
                      ]
                    },
                    "horizon": {
                      "description": "An object containing arrays of required and optional unique horizons. Horizons define the difference between the target_date and the origin_date in time units specified by the hub (e.g., may be days, weeks, or months)",
                      "examples": [{
                        "required": null,
                        "optional": [1, 2, 3, 4]
                      }],
                      "type": "object",
                      "properties": {
                        "required": {
                          "description": "Array of horizon unique identifiers that must be present for submission to be valid. Can be null if no horizons are required and all valid horizons are specified in the optional property.",
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": ["integer", "string"]
                          }
                        },
                        "optional": {
                          "description": "Array of valid but not required unique horizon identifiers. Can be null if all horizons are required and are specified in the required property.",
                          "type": [
                            "null",
                            "array"
                          ],
                          "items": {
                            "type": ["integer", "string"]
                          }
                        }
                      },
                      "required": [
                        "required",
                        "optional"
                      ]
                    },
                    "age_group": {
                      "type": "object",
                      "description": "An object containing arrays of required and optional unique identifiers for age groups",
                      "examples": [{
                        "required": ["0-5", "6-18", "19-24", "25-64", "65+"],
                        "optional": null
                      }],
                      "properties": {
                        "required": {
                          "description": "Array of age group unique identifiers that must be present for submission to be valid. Can be null if no age groups are required and all valid age groups are specified in the optional property.",
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          }
                        },
                        "optional": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "required",
                        "optional"
                      ]
                    }
                  },
                  "additionalProperties": true
                },
                "output_type": {
                  "type": "object",
                  "description": "Object defining valid model output types for a given modeling task. The name of each property corresponds to valid values in column 'type' while the 'type_id' property of each output type defines the valid values of the 'type_id' column and the 'value' property defines the valid values of the 'value' column for a given output type.",
                  "properties": {
                    "mean": {
                      "type": "object",
                      "description": "Object defining the mean of the predictive distribution output type.",
                      "properties": {
                        "type_id": {
                          "description": "type_id is not meaningful for a mean output_type. The property is primarily used to determine whether mean is a required or optional output type through properties required and optional. If mean is a required output type, the required property must be an array containing the single string element 'NA' and the optional property must be set to null. If mean is an optional output type, the optional property must be an array containing the single string element 'NA' and the required property must be set to null",
                          "examples": [{
                            "required": ["NA"],
                            "optional": null
                          }, {
                            "required": null,
                            "optional": ["NA"]
                          }],
                          "type": "object",
                          "oneOf": [{
                            "properties": {
                              "required": {
                                "description": "When mean is required, property set to single element 'NA' array",
                                "type": "array",
                                "items": {
                                  "const": "NA",
                                  "maxItems": 1
                                }
                              },
                              "optional": {
                                "description": "When mean is required, property set to null",
                                "type": "null"
                              }
                            }
                          }, {
                            "properties": {
                              "required": {
                                "description": "When mean is optional, property set to null",
                                "type": "null"
                              },
                              "optional": {
                                "description": "When mean is optional, property set to single element 'NA' array",
                                "type": "array",
                                "items": {
                                  "const": "NA",
                                  "maxItems": 1
                                }
                              }
                            }
                          }],
                          "required": [
                            "required",
                            "optional"
                          ]
                        },
                        "value": {
                          "type": "object",
                          "description": "Object defining the characteristics of valid mean values.",
                          "examples": [{
                            "type": "numeric",
                            "minimum": 0
                          }],
                          "properties": {
                            "type": {
                              "description": "Data type of mean values.",
                              "type": "string",
                              "enum": ["numeric", "double", "integer"]
                            },
                            "minimum": {
                              "description": "The minimum inclusive valid mean value",
                              "type": "integer"
                            },
                            "maximum": {
                              "description": "the maximum inclusive valid mean value",
                              "type": "integer"
                            }
                          },
                          "required": [
                            "type"
                          ]
                        }
                      },
                      "required": [
                        "type_id",
                        "value"
                      ]
                    },
                    "median": {
                      "type": "object",
                      "description": "Object defining the median of the predictive distribution output type",
                      "properties": {
                        "type_id": {
                          "description": "type_id is not meaningful for a median output_type. The property is primarily used to determine whether median is a required or optional output type through properties required and optional. If median is a required output type, the required property must be an array containing the single string element 'NA' and the optional property must be set to null. If median is an optional output type, the optional property must be an array containing the single string element 'NA' and the required property must be set to null",
                          "examples": [{
                            "required": ["NA"],
                            "optional": null
                          }, {
                            "required": null,
                            "optional": ["NA"]
                          }],
                          "type": "object",
                          "oneOf": [{
                            "properties": {
                              "required": {
                                "description": "When median is required, property set to single element 'NA' array",
                                "type": "array",
                                "items": {
                                  "const": "NA",
                                  "maxItems": 1
                                }
                              },
                              "optional": {
                                "description": "When median is required, property set to null",
                                "type": "null"
                              }
                            }
                          }, {
                            "properties": {
                              "required": {
                                "description": "When median is optional, property set to null",
                                "type": "null"
                              },
                              "optional": {
                                "description": "When median is optional, property set to single element 'NA' array",
                                "type": "array",
                                "items": {
                                  "const": "NA",
                                  "maxItems": 1
                                }
                              }
                            }
                          }],
                          "required": [
                            "required",
                            "optional"
                          ]
                        },
                        "value": {
                          "type": "object",
                          "description": "Object defining the characteristics of valid median values",
                          "examples": [{
                            "type": "numeric",
                            "minimum": 0
                          }],
                          "properties": {
                            "type": {
                              "description": "Data type of median values",
                              "type": "string",
                              "enum": ["numeric", "double", "integer"]
                            },
                            "minimum": {
                              "description": "The minimum inclusive valid median value",
                              "type": "integer"
                            },
                            "maximum": {
                              "description": "the maximum inclusive valid median value",
                              "type": "integer"
                            }
                          },
                          "required": [
                            "type"
                          ]
                        }
                      },
                      "required": [
                        "type_id",
                        "value"
                      ]
                    },
                    "quantile": {
                      "description": "Object defining the quantiles of the predictive distribution output type.",
                      "type": "object",
                      "properties": {
                        "type_id": {
                          "description": "Object containing required and optional arrays defining the probability levels at which quantiles of the predictive distribution will be recorded.",
                          "examples": [{
                            "required": [0.25, 0.5, 0.75],
                            "optional": [0.1, 0.2, 0.3, 0.4, 0.6, 0.7, 0.8, 0.9]
                          }],
                          "type": "object",
                          "properties": {
                            "required": {
                              "description": "Array of unique probability levels between 0 and 1 that must be present for submission to be valid. Can be null if no probability levels are required and all valid probability levels are specified in the optional property.",
                              "type": ["array", "null"],
                              "items": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1
                              }
                            },
                            "optional": {
                              "description": "Array of valid but not required unique probability levels. Can be null if all probability levels are required and are specified in the required property.",
                              "type": ["array", "null"],
                              "items": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1
                              }
                            }
                          },
                          "required": [
                            "required",
                            "optional"
                          ]
                        },
                        "value": {
                          "type": "object",
                          "description": "Object defining the characteristics of valid quantiles of the predictive distribution at a given probability level.",
                          "properties": {
                            "type": {
                              "description": "Data type of quantile values.",
                              "examples": ["numeric"],
                              "type": "string",
                              "enum": ["numeric", "double", "integer"]
                            },
                            "minimum": {
                              "description": "The minimum inclusive valid quantile value (optional).",
                              "examples": [0],
                              "type": "number"
                            },
                            "maximum": {
                              "description": "The maximum inclusive valid quantile value (optional).",
                              "type": "number"
                            }
                          },
                          "required": [
                            "type"
                          ]
                        }
                      },
                      "required": [
                        "type_id",
                        "value"
                      ]
                    },
                    "cdf": {
                      "description": "Object defining the cumulative distribution function of the predictive distribution output type.",
                      "type": "object",
                      "properties": {
                        "type_id": {
                          "description": "Object containing required and optional arrays defining possible values of the target variable at which values of the cumulative distribution function of the predictive distribution will be recorded.",
                          "examples": [{
                              "required": [10.0, 20.0],
                              "optional": null
                            },
                            {
                              "required": ["EW202240", "EW202241", "EW202242", "EW202243", "EW202244", "EW202245", "EW202246", "EW202247"],
                              "optional": null
                            }
                          ],
                          "type": "object",
                          "properties": {
                            "required": {
                              "description": "Array of unique target values that must be present for submission to be valid. Can be null if no target values are required and all valid target values are specified in the optional property.",
                              "type": ["array", "null"],
                              "items": {
                                "oneOf": [{
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  {
                                    "type": "string",
                                    "pattern": "^EW[0-9]{6}",
                                    "minLength": 8,
                                    "maxLength": 8
                                  }
                                ]
                              }
                            },
                            "optional": {
                              "description": "Array of valid but not required unique target values. Can be null if all target values are required and are specified in the required property.",
                              "type": ["array", "null"],
                              "items": {
                                "oneOf": [{
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  {
                                    "type": "string",
                                    "pattern": "^EW[0-9]{6}",
                                    "minLength": 8,
                                    "maxLength": 8
                                  }
                                ]
                              }
                            }
                          },
                          "required": [
                            "required",
                            "optional"
                          ]
                        },
                        "value": {
                          "type": "object",
                          "description": "Object defining the characteristics of valid values of the cumulative distribution function at a given target value.",
                          "properties": {
                            "type": {
                              "description": "Data type of cumulative distribution function values.",
                              "examples": ["double"],
                              "enum": [
                                "numeric", "double"
                              ]
                            },
                            "minimum": {
                              "description": "The minimum inclusive valid cumulative distribution function value. Must be 0.",
                              "const": 0
                            },
                            "maximum": {
                              "description": "The maximum inclusive valid cumulative distribution function value. Must be 1.",
                              "const": 1
                            }
                          },
                          "required": [
                            "type",
                            "minimum",
                            "maximum"
                          ]
                        }
                      },
                      "required": [
                        "type_id",
                        "value"
                      ]
                    },
                    "categorical": {
                      "description": "Object defining a categorical output type.",
                      "type": "object",
                      "properties": {
                        "type_id": {
                          "description": "Object containing required and optional arrays specifying valid category values.",
                          "examples": [{
                            "required": null,
                            "optional": ["low", "moderate", "high", "extreme"]
                          }],
                          "type": "object",
                          "properties": {
                            "required": {
                              "description": "Array of unique categories that must be present for submission to be valid. Can be null if no categories are required and all valid categories are specified in the optional property.",
                              "type": ["array", "null"],
                              "items": {
                                "type": "string"
                              }
                            },
                            "optional": {
                              "description": "Array of valid but not required unique categories. Can be null if all categories are required and are specified in the required property.",
                              "type": ["array", "null"],
                              "items": {
                                "type": "string"
                              }
                            }
                          },
                          "required": [
                            "required",
                            "optional"
                          ]
                        },
                        "value": {
                          "type": "object",
                          "description": "Object defining valid values of the probability mass function of the predictive distribution for a given level of a categorical outcome variable.",
                          "examples": [{
                            "type": "double",
                            "minimum": 0,
                            "maximum": 1
                          }],
                          "properties": {
                            "type": {
                              "description": "Data type of the probability mass function values.",
                              "enum": [
                                "numeric", "double"
                              ]
                            },
                            "minimum": {
                              "description": "The minimum inclusive valid probability mass function value. Must be 0.",
                              "const": 0
                            },
                            "maximum": {
                              "description": "The maximum inclusive valid probability mass function value. Must be 1.",
                              "const": 1
                            }
                          },
                          "required": [
                            "type",
                            "minimum",
                            "maximum"
                          ]
                        }
                      },
                      "required": [
                        "type_id",
                        "value"
                      ]
                    },
                    "sample": {
                      "description": "Object defining a sample output type.",
                      "type": "object",
                      "properties": {
                        "type_id": {
                          "description": "Object containing required and optional arrays specifying valid sample values.",
                          "examples": [{
                            "required": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
                            "optional": [11, 12, 13, 14, 15]
                          }],
                          "type": "object",
                          "properties": {
                            "required": {
                              "description": "Array of unique sample indexes that must be present for submission to be valid. Can be null if no sample indexes are required and all valid sample indexes are specified in the optional property.",
                              "type": ["array", "null"],
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              }
                            },
                            "optional": {
                              "description": "Array of valid but not required unique sample indexes. Can be null if all sample indexes are required and are specified in the required property.",
                              "type": ["array", "null"],
                              "items": {
                                "type": "integer",
                                "minimum": 1
                              }
                            }
                          },
                          "required": [
                            "required",
                            "optional"
                          ]
                        },
                        "value": {
                          "type": "object",
                          "description": "Object defining valid values of samples from the predictive distribution for a given sample index.  Depending on the Hub specification, samples with the same sample index (specified by the type_id) may be assumed to correspond to a joint distribution across multiple levels of the task id variables. See Hub documentation for details.",
                          "properties": {
                            "type": {
                              "description": "Data type of sample value from the predictive distribution.",
                              "examples": [{
                                "type": "double"
                              }],
                              "enum": [
                                "numeric", "double", "integer"
                              ]
                            },
                            "minimum": {
                              "description": "The minimum inclusive valid sample value from the predictive distribution"
                            },
                            "maximum": {
                              "description": "The maximum inclusive valid sample value from the predictive distribution"
                            }
                          },
                          "required": [
                            "type"
                          ]
                        }
                      },
                      "required": [
                        "type_id",
                        "value"
                      ]
                    }
                  }
                }
              },
              "required": [
                "task_ids",
                "output_type"
              ]
            }
          },
          "submissions_due": {
            "description": "Object defining the dates by which model forecasts must be submitted to the hub.",
            "examples": [{
                "start": "2022-06-07",
                "end": "2022-07-20"
              },
              {
                "relative_to": "origin_date",
                "start": -4,
                "end": 2
              }
            ],
            "type": "object",
            "oneOf": [{
                "properties": {
                  "relative_to": {
                    "description": "Name of task id variable in relation to which submission start and end dates are calculated.",
                    "type": "string"
                  },
                  "start": {
                    "description": "Difference in days between start and origin date.",
                    "type": "integer"
                  },
                  "end": {
                    "description": "Difference in days between end and origin date.",
                    "type": "integer"
                  }
                },
                "required": [
                  "relative_to",
                  "start",
                  "end"
                ]
              },
              {
                "properties": {
                  "start": {
                    "description": "Submission start date.",
                    "type": "string",
                    "format": "date"
                  },
                  "end": {
                    "description": "Submission end date.",
                    "type": "string",
                    "format": "date"
                  }
                },
                "required": [
                  "start",
                  "end"
                ]
              }
            ],
            "required": [
              "start",
              "end"
            ]
          },
          "last_data_date": {
            "description": "The last date with recorded data in the data set used as input to a model.",
            "examples": ["2022-07-18"],
            "type": "string",
            "format": "date"
          }
        },
        "required": [
          "round_id_from_variable",
          "round_id",
          "model_tasks",
          "submissions_due"
        ]
      }
    },
    "$defs": {}
  },
  "required": [
    "rounds",
    "schema_version"
  ]
}
