{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/livetennisapi-com/json-schema/livetennisapi-com-tournament-schema.json",
  "title": "Tournament",
  "description": "One tournament of the catalogue — the stable id space `Match.tournament_id` joins, one row per tournament × event type, stable across seasons.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/livetennisapi-com-tournaments-api-openapi.yml#/components/schemas/Tournament",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The stable id `Match.tournament_id` joins."
    },
    "name": {
      "type": [
        "string",
        "null"
      ]
    },
    "tour": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "atp",
        "wta",
        "challenger",
        "itf",
        "juniors",
        null
      ]
    },
    "surface": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "hard",
        "clay",
        "grass",
        null
      ],
      "description": "Court surface, null where the catalogue holds none — 61 of 10,287 tournaments on 2026-09-20. 35 of those are team competitions (Davis Cup, Billie Jean King Cup, Laver Cup), which have no tournament-level surface to hold: each tie is played on the host nation's choice, and that surface is published on each MATCH of the tie instead. A surface value that is not one of hard/clay/grass is rejected rather than published. 3 are the exhibition catch-all and 23 are ordinary events with no stated surface."
    },
    "indoor": {
      "type": "boolean"
    },
    "city": {
      "type": [
        "string",
        "null"
      ],
      "description": "Host city, from a curated table — null where not curated."
    },
    "country": {
      "type": [
        "string",
        "null"
      ],
      "description": "Host country, ISO-3166 alpha-2 — null where not curated. (NOTE this differs from `player.country` and the `?country=` filter, which use IOC-style lowercase 3-letter codes.)"
    },
    "category": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "grand_slam",
        "masters_1000",
        "tour_finals",
        "atp_500",
        "atp_250",
        "wta_1000",
        "wta_500",
        "wta_250",
        "wta_125",
        "challenger",
        "itf",
        "juniors",
        null
      ],
      "description": "Tournament category where our catalogues agree unambiguously on an exact-name join — null otherwise, never derived from the name. Unchanged by `tier` (2026-09-22) and remains the coarse class; read `tier` for the level."
    },
    "tier": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "grand_slam",
        "atp_finals",
        "atp_1000",
        "atp_500",
        "atp_250",
        "next_gen_finals",
        "united_cup",
        "davis_cup",
        "olympics",
        "laver_cup",
        "wta_finals",
        "wta_elite_trophy",
        "wta_1000",
        "wta_500",
        "wta_250",
        "wta_125",
        "bjk_cup",
        "challenger_175",
        "challenger_125",
        "challenger_100",
        "challenger_75",
        "challenger_50",
        "itf_m15",
        "itf_m25",
        "itf_w15",
        "itf_w25",
        "itf_w35",
        "itf_w40",
        "itf_w50",
        "itf_w60",
        "itf_w75",
        "itf_w80",
        "itf_w100",
        "juniors",
        "utr",
        "exhibition",
        null
      ],
      "description": "The level this tournament is played at in the CURRENT season (added 2026-09-22) — the same closed vocabulary as `tier` on a match (`grand_slam`, `atp_1000` … `atp_250`, `wta_1000` … `wta_125`, `challenger_175` … `challenger_50`, `itf_m15` / `itf_m25`, `itf_w15` … `itf_w100`, the team events, `juniors`, `utr`, `exhibition`). A catalogue row has no season of its own; a match does: the tier is PER SEASON and it moves under one id — Dallas was `atp_250` in 2023 and 2024 and `atp_500` from 2025; Estoril `atp_250`, then `challenger_175` in 2025, then `atp_250` again in 2026; Eastbourne `wta_500` through 2024 and `wta_250` from 2025 — so read the tier off each MATCH for its season, never copy this value onto a match. Null when this season's calendar does not list the event — never guessed."
    },
    "tier_source": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "calendar",
        "name",
        "wikipedia",
        "resolver",
        null
      ],
      "description": "How `tier` was established (added 2026-09-22): `calendar` = the official per-season tour calendar named the level (ATP tour and Challenger calendars, the WTA tournament list); `name` = an unambiguous name rule (the ITF category is in the event's official name — `M25 …`, `W35 …` — team and UTR events are named as such, and the Slam junior draws and exhibitions are their own event type); `wikipedia` = a published season schedule, used only where the official calendar could not state the level for that season (Eastbourne 2023–2025); `resolver` = resolved after the seed dataset, by the same rules, from the event's name, tour and dates in that season. Null exactly when `tier` is null."
    }
  }
}