{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "/schemas/football-match.schema.json",
  "title": "Todayspredict Football Match (canonical)",
  "description": "Canonical JSON shape for a football fixture used on the front. Aligns with Schema.org SportsEvent where noted. See FootballMatchSchema::schemaCompletenessNotes() in app for gaps.",
  "type": "object",
  "required": ["match_id", "sport", "home_team", "away_team", "scheduled_at"],
  "properties": {
    "match_id": {
      "type": "string",
      "description": "External fixture id (e.g. API-Football fixture id)."
    },
    "sport": {
      "type": "string",
      "const": "Soccer",
      "description": "schema.org sport for SportsEvent."
    },
    "scheduled_at": {
      "type": "string",
      "format": "date-time",
      "description": "Kickoff in ISO 8601 (prefer UTC or include offset)."
    },
    "scheduled_timezone": {
      "type": ["string", "null"],
      "description": "IANA tz used when local display differs, e.g. Africa/Lagos."
    },
    "status_code": {
      "type": "string",
      "description": "Raw provider status: NS, 1H, HT, 2H, FT, PST, CANC, etc."
    },
    "event_status_schema_org": {
      "type": "string",
      "description": "https://schema.org/EventStatusType IRI when mappable."
    },
    "competition": {
      "$ref": "#/$defs/Competition"
    },
    "venue": {
      "$ref": "#/$defs/Venue"
    },
    "home_team": {
      "$ref": "#/$defs/TeamSide"
    },
    "away_team": {
      "$ref": "#/$defs/TeamSide"
    },
    "goals": {
      "$ref": "#/$defs/Score"
    },
    "odds": {
      "type": "object",
      "description": "1X2 or other markets; structure varies by book source.",
      "additionalProperties": true
    },
    "prediction": {
      "type": "object",
      "properties": {
        "primary_pick": { "type": ["string", "null"] },
        "raw_code": { "type": ["string", "null"] },
        "category_picks": {
          "type": "object",
          "additionalProperties": { "type": ["string", "null"] }
        },
        "h2h_model": {
          "type": ["object", "array", "null"],
          "description": "Model / API h2h payload when present."
        }
      },
      "additionalProperties": true
    },
    "form": {
      "type": "object",
      "properties": {
        "home_last5": { "type": ["string", "null"] },
        "away_last5": { "type": ["string", "null"] }
      }
    },
    "lineups": {
      "type": ["object", "null"],
      "description": "Starting XI, bench, formation — needs fixture lineups endpoint."
    },
    "statistics": {
      "type": ["object", "null"],
      "description": "Shots, corners, cards — needs fixture statistics endpoint."
    },
    "head_to_head": {
      "type": ["array", "null"],
      "description": "Past meetings; needs teams/fixtures h2h API."
    },
    "referee": {
      "type": ["string", "null"],
      "description": "Needs fixture officials from provider."
    },
    "attendance": {
      "type": ["integer", "null"]
    },
    "round": {
      "type": ["string", "null"],
      "description": "League round / matchday label."
    },
    "weather": {
      "type": ["object", "null"],
      "description": "Optional; rarely available from core fixture APIs."
    },
    "data_sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "retrieved_at": { "type": "string", "format": "date-time" },
          "endpoint": { "type": ["string", "null"] }
        }
      }
    }
  },
  "$defs": {
    "Competition": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "league_id": { "type": ["string", "integer", "null"] },
        "name": { "type": "string" },
        "country": { "type": ["string", "null"] },
        "logo_url": { "type": ["string", "null"], "format": "uri" },
        "season": { "type": ["string", "integer", "null"] }
      }
    },
    "Venue": {
      "type": "object",
      "properties": {
        "name": { "type": ["string", "null"] },
        "city": { "type": ["string", "null"] },
        "country": { "type": ["string", "null"] },
        "latitude": { "type": ["number", "null"] },
        "longitude": { "type": ["number", "null"] }
      }
    },
    "TeamSide": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": { "type": "string" },
        "short_name": { "type": ["string", "null"] },
        "logo_url": { "type": ["string", "null"], "format": "uri" },
        "provider_team_id": { "type": ["string", "integer", "null"] }
      }
    },
    "Score": {
      "type": "object",
      "properties": {
        "home": { "type": ["integer", "null"] },
        "away": { "type": ["integer", "null"] },
        "halftime_home": { "type": ["integer", "null"] },
        "halftime_away": { "type": ["integer", "null"] }
      }
    }
  }
}