{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/livetennisapi-com/json-schema/livetennisapi-com-ranking-list-meta-schema.json",
  "title": "RankingListMeta",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/livetennisapi-com-rankings-api-openapi.yml#/components/schemas/RankingListMeta",
  "allOf": [
    {
      "$ref": "#/$defs/ListMeta"
    },
    {
      "type": "object",
      "properties": {
        "coverage": {
          "type": "object",
          "description": "What resolved against what was asked. Read it before trusting an empty result — ITF and UTR observations reach back to 2026-06-01 (append-only per-player history accumulates from 2026-07-29); nothing earlier can be reconstructed, so a request before `oldest_available` correctly returns nothing for those systems.",
          "properties": {
            "as_of": {
              "type": [
                "string",
                "null"
              ],
              "format": "date"
            },
            "effective_date": {
              "type": [
                "string",
                "null"
              ],
              "format": "date",
              "description": "Listing mode. For the official systems, the published week the table is from. For `elo`, the as-of instant the leaderboard was resolved at (each row carries its own `effective_date`, since a sparse tape moves per player)."
            },
            "players_requested": {
              "type": "integer",
              "description": "Per-player mode only."
            },
            "players_resolved": {
              "type": "integer",
              "description": "Per-player mode only."
            },
            "systems_requested": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "systems_resolved": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "oldest_available": {
              "type": "object",
              "additionalProperties": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date"
              },
              "description": "Earliest effective date held, per requested system."
            },
            "newest_available": {
              "type": "object",
              "additionalProperties": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date"
              },
              "description": "Present only when `elo` was requested. The NEWEST effective date the Elo tape holds. The corpus behind it is fixed and no longer receives new results, so this date does not advance and will keep receding from today — that is a property of a historical tape, not a fault. Read it before treating an Elo leaderboard as a current one."
            },
            "tour": {
              "type": [
                "string",
                "null"
              ],
              "description": "Present only when `elo` was requested — which walk answered."
            },
            "surface": {
              "description": "Present only when `elo` was requested. The ladder (listing) or the list of ladders (per-player) the response covers."
            },
            "players_rated": {
              "type": "integer",
              "description": "Present only when `elo` was requested. People with at least one rating in the tape."
            },
            "players_linked": {
              "type": "integer",
              "description": "Present only when `elo` was requested. How many of those have a row in our player roster, and therefore can be reached with `player`. The rest are reachable with `archive_player` and appear on the leaderboard with a null `player_id` and their name. The gap between these two numbers is large and is reported rather than buried."
            },
            "qualified": {
              "type": "object",
              "description": "Present only on an `elo` listing. The two filters that DEFINE the field this table ranks. A top-N is not quotable without them — change either and it is a different top-N, and neither is more correct than the other.",
              "properties": {
                "activity_weeks": {
                  "type": "integer"
                },
                "min_matches": {
                  "type": "integer"
                }
              }
            },
            "model": {
              "type": "object",
              "description": "Present only when `elo` was requested. What the numbers ARE.",
              "properties": {
                "name": {
                  "type": "string"
                },
                "start_rating": {
                  "type": "number"
                },
                "k_base": {
                  "type": "number"
                },
                "publication_lag_days": {
                  "type": "integer",
                  "description": "A result becomes effective this many days after its tournament WEEK begins. The corpus dates a match by its tournament start, so without the lag a Slam final would be visible under the Monday the Slam began. The lag clears the longest event in tennis, so the failure direction is staleness and never look-ahead."
                },
                "built_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  ],
  "$defs": {
    "ListMeta": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer"
        },
        "offset": {
          "type": "integer"
        },
        "count": {
          "type": "integer"
        },
        "total": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Size of the whole filtered set. Null when it cannot be counted cheaply."
        },
        "has_more": {
          "type": "boolean",
          "description": "More results exist beyond this page. Read this rather than comparing count to limit. For a complete enumeration of a filtered set, page `offset` forward by `limit` until this is false; on `completed`/`cancelled` listings `total` is null and this is the only end-of-data signal."
        },
        "next_cursor": {
          "type": [
            "string",
            "null"
          ],
          "description": "Change-feed only (`?updated_since=` / `?cursor=`). Opaque token to pass back as `?cursor=`. Null means you are caught up — stop paging and switch to polling from `watermark`."
        },
        "watermark": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Change-feed only. The floor to use on your NEXT poll. Deliberately trails the server clock by 5s so a row committed during this request cannot fall through the gap."
        }
      }
    }
  }
}