{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.mosticare.org/threat-map/feed.schema.json",
  "title": "Mosticare disease-incidence feed",
  "description": "Machine-readable JSON Schema for /threat-map/feed.json — Mosticare's per-country disease-incidence surveillance feed for the European Union and EEA. The feed is published by Mosticare (NGO) under CC BY 4.0 as the third civil-society source alongside ECDC's Surveillance Atlas and EFSA's One-Health zoonoses reporting. Each record covers one country × one disease × one period.",
  "type": "object",
  "required": [
    "feed",
    "version",
    "publisher",
    "description",
    "license",
    "license_url",
    "temporal_coverage",
    "variables_measured",
    "measurement_technique",
    "is_based_on",
    "refresh_cadence",
    "last_updated",
    "record_count",
    "records",
    "key_fact_count",
    "key_facts"
  ],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri",
      "description": "Self-reference to this JSON Schema document. Required by strict-validator AI ingestion paths."
    },
    "feed": {
      "type": "string",
      "const": "mosticare-disease-incidence",
      "description": "Canonical feed identifier. Always 'mosticare-disease-incidence' for this feed."
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "Semantic version of the feed schema (semver). Breaking changes to record shape bump the major."
    },
    "publisher": {
      "type": "object",
      "required": ["name", "url", "type"],
      "additionalProperties": false,
      "properties": {
        "name": { "type": "string", "minLength": 1 },
        "url": { "type": "string", "format": "uri" },
        "type": { "type": "string", "enum": ["NGO", "Government", "Academic", "Commercial"] }
      },
      "description": "Authority publishing the feed."
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "description": "Human-readable feed description."
    },
    "license": {
      "type": "string",
      "minLength": 1,
      "description": "SPDX-compatible license identifier (e.g. 'CC BY 4.0')."
    },
    "license_url": {
      "type": "string",
      "format": "uri",
      "description": "Canonical license URL."
    },
    "temporal_coverage": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}/\\d{4}-\\d{2}-\\d{2}$",
      "description": "ISO-8601 time interval (start/end) spanned by the records."
    },
    "variables_measured": {
      "type": "array",
      "description": "The measurement dimensions the feed reports.",
      "items": {
        "type": "object",
        "required": ["name", "description", "unit"],
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string", "minLength": 1 },
          "description": { "type": "string", "minLength": 1 },
          "unit": { "type": "string", "minLength": 1 }
        }
      }
    },
    "measurement_technique": {
      "type": "string",
      "minLength": 1,
      "description": "Method by which the data is produced (aggregation/re-publication of upstream surveillance)."
    },
    "is_based_on": {
      "type": "array",
      "description": "Upstream source datasets this feed is aggregated from (honest attribution).",
      "items": {
        "type": "object",
        "required": ["name", "authority", "url"],
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string", "minLength": 1 },
          "authority": { "type": "string", "minLength": 1 },
          "url": { "type": "string", "format": "uri" }
        }
      }
    },
    "refresh_cadence": {
      "type": "object",
      "required": ["minimum", "target", "next_review"],
      "additionalProperties": false,
      "properties": {
        "minimum": {
          "type": "string",
          "enum": ["hourly", "daily", "weekly", "monthly", "quarterly", "annually"],
          "description": "Worst-case refresh frequency. Consumers can budget polling against this."
        },
        "target": {
          "type": "string",
          "enum": ["hourly", "daily", "weekly", "monthly", "quarterly", "annually"],
          "description": "Aspirational refresh frequency."
        },
        "next_review": {
          "type": "string",
          "format": "date",
          "description": "ISO-8601 date on which the publisher commits to re-review the feed."
        }
      }
    },
    "last_updated": {
      "type": "string",
      "format": "date",
      "description": "ISO-8601 date the feed envelope was last verified or refreshed."
    },
    "record_count": {
      "type": "integer",
      "minimum": 0,
      "description": "Total number of records in the records array. MUST equal records.length."
    },
    "records": {
      "type": "array",
      "items": { "$ref": "#/$defs/incidenceRecord" },
      "description": "Array of country × disease × period incidence records."
    },
    "key_fact_count": {
      "type": "integer",
      "minimum": 0,
      "description": "Total number of key_facts entries. MUST equal key_facts.length."
    },
    "key_facts": {
      "type": "array",
      "items": { "$ref": "#/$defs/keyFact" },
      "description": "Superlative answer-bearing facts (first/most/largest/highest/deadliest) derived from records, each independently sourced."
    }
  },
  "$defs": {
    "keyFact": {
      "type": "object",
      "required": [
        "id",
        "superlative",
        "question",
        "answer",
        "metric",
        "value",
        "value_label",
        "disease",
        "disease_code",
        "country",
        "country_name",
        "year",
        "period",
        "source_url",
        "source_authority",
        "last_updated"
      ],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string", "minLength": 1, "description": "Stable slug / page fragment id." },
        "superlative": {
          "type": "string",
          "enum": ["first", "largest", "most", "highest", "deadliest", "earliest"],
          "description": "The superlative dimension the fact answers on."
        },
        "question": { "type": "string", "minLength": 1, "description": "The natural-language query this fact answers." },
        "answer": { "type": "string", "minLength": 1, "description": "Answer-first, self-contained, quotable statement." },
        "metric": {
          "type": "string",
          "enum": ["human cases", "autochthonous cases", "deaths", "case fatality rate"],
          "description": "The answer-bearing measurement dimension."
        },
        "value": { "type": "number", "description": "Numeric answer value for the metric." },
        "value_label": { "type": "string", "minLength": 1, "description": "Human-formatted value (e.g. '779 cases')." },
        "disease": { "type": "string", "minLength": 1 },
        "disease_code": { "type": "string", "minLength": 1 },
        "country": { "type": "string", "pattern": "^[A-Z]{2}$" },
        "country_name": { "type": "string", "minLength": 1 },
        "region": { "type": "string", "minLength": 1 },
        "year": { "type": "integer", "minimum": 2000, "description": "Calendar year the fact pertains to." },
        "period": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}/\\d{4}-\\d{2}-\\d{2}$",
          "description": "ISO-8601 interval matching the underlying record's period."
        },
        "source_url": { "type": "string", "format": "uri" },
        "source_authority": { "type": "string", "minLength": 1 },
        "last_updated": { "type": "string", "format": "date" }
      }
    },
    "incidenceRecord": {
      "type": "object",
      "required": [
        "country",
        "country_name",
        "disease",
        "disease_code",
        "vector",
        "vector_common",
        "cases",
        "deaths",
        "period",
        "period_label",
        "source_url",
        "source_authority",
        "last_updated"
      ],
      "additionalProperties": false,
      "properties": {
        "country": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "description": "ISO-3166-1 alpha-2 country code (e.g. 'FR', 'IT')."
        },
        "country_name": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable country name."
        },
        "region": {
          "type": "string",
          "minLength": 1,
          "description": "Optional sub-national region name (e.g. 'Andalusia', 'Madeira')."
        },
        "disease": {
          "type": "string",
          "minLength": 1,
          "description": "Disease name (e.g. 'West Nile virus', 'Chikungunya', 'Dengue (DENV-2)')."
        },
        "disease_code": {
          "type": "string",
          "minLength": 1,
          "description": "Short canonical disease code (e.g. 'WNV', 'CHIKV', 'DENV2', 'VECTOR-AALBO')."
        },
        "vector": {
          "type": "string",
          "minLength": 1,
          "description": "Latin name of the primary vector species (e.g. 'Culex pipiens')."
        },
        "vector_common": {
          "type": "string",
          "minLength": 1,
          "description": "Common name of the vector (e.g. 'common house mosquito')."
        },
        "cases": {
          "type": "integer",
          "minimum": 0,
          "description": "Confirmed human cases in the period."
        },
        "deaths": {
          "type": "integer",
          "minimum": 0,
          "description": "Locally fatal cases in the period."
        },
        "hospitalisations": {
          "type": "integer",
          "minimum": 0,
          "description": "Optional, when reported by the source authority."
        },
        "affected_areas": {
          "type": "integer",
          "minimum": 0,
          "description": "Optional surveillance metric (e.g. count of high-risk municipalities or vector-established areas)."
        },
        "affected_areas_unit": {
          "type": "string",
          "minLength": 1,
          "description": "Unit / qualifier for affected_areas (e.g. 'high-risk municipalities')."
        },
        "period": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}/\\d{4}-\\d{2}-\\d{2}$",
          "description": "ISO-8601 time interval (start/end) for the period the record covers."
        },
        "period_label": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable period label (e.g. '2025 transmission season')."
        },
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "Authoritative source URL for the record."
        },
        "source_authority": {
          "type": "string",
          "minLength": 1,
          "description": "Source authority name (e.g. 'Santé publique France', 'Istituto Superiore di Sanità (ISS)')."
        },
        "last_updated": {
          "type": "string",
          "format": "date",
          "description": "ISO-8601 date the record was last verified."
        },
        "notes": {
          "type": "string",
          "description": "Optional freeform notes on case definition, caveats, or context."
        }
      }
    }
  }
}