{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/good-grants/json-schema/good-grants-leaderboard-list-schema.json",
  "title": "Leaderboard list",
  "description": "Paginated leaderboard for a single score set, with ranked applications in `data` alongside the score set and season.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/good-grants-leaderboard-api-openapi.yml#/components/schemas/LeaderboardList",
  "allOf": [
    {
      "$ref": "#/$defs/Pagination"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "description": "Leaderboard rows for the current page.",
          "items": {
            "$ref": "#/$defs/Leaderboard"
          }
        },
        "score_set": {
          "type": "object",
          "description": "Score set the leaderboard is calculated for.",
          "properties": {
            "slug": {
              "type": "string",
              "description": "Short URL-safe identifier for the score set."
            },
            "name": {
              "type": "object",
              "description": "Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.",
              "additionalProperties": {
                "type": "string"
              }
            },
            "mode": {
              "type": "string",
              "enum": [
                "voting",
                "qualifying",
                "scoring",
                "top_pick"
              ],
              "description": "Scoring mode of the score set, determines the shape of each row's `scores` object."
            },
            "form": {
              "type": "object",
              "description": "Form the score set scores applications from.",
              "properties": {
                "slug": {
                  "type": "string",
                  "description": "Short URL-safe identifier for the form."
                },
                "link": {
                  "type": "string",
                  "format": "uri",
                  "description": "Canonical URL for the form resource."
                },
                "name": {
                  "type": "object",
                  "description": "Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.",
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "season": {
          "type": "object",
          "description": "Season the leaderboard belongs to.",
          "properties": {
            "slug": {
              "type": "string",
              "description": "Short URL-safe identifier for the season."
            },
            "link": {
              "type": "string",
              "format": "uri",
              "description": "Canonical URL for the season resource."
            },
            "name": {
              "type": "object",
              "description": "Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  ],
  "$defs": {
    "Leaderboard": {
      "title": "Leaderboard",
      "description": "Single row in a score-set leaderboard, representing one application and its scores.",
      "type": "object",
      "properties": {
        "slug": {
          "type": "string",
          "description": "Short URL-safe identifier for the application."
        },
        "title": {
          "type": "string",
          "description": "Title of the application as submitted by the applicant."
        },
        "tags": {
          "type": "string",
          "description": "Comma-separated tags applied to the application, empty string if none."
        },
        "category": {
          "type": [
            "object",
            "null"
          ],
          "description": "Category the application was submitted to, `null` if not assigned.",
          "properties": {
            "slug": {
              "type": "string",
              "description": "Short URL-safe identifier for the category."
            },
            "link": {
              "type": "string",
              "format": "uri",
              "description": "Canonical URL for the category resource."
            },
            "name": {
              "type": "object",
              "description": "Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        },
        "chapter": {
          "type": [
            "object",
            "null"
          ],
          "description": "Chapter the application belongs to, `null` if not assigned.",
          "properties": {
            "slug": {
              "type": "string",
              "description": "Short URL-safe identifier for the chapter."
            },
            "link": {
              "type": "string",
              "format": "uri",
              "description": "Canonical URL for the chapter resource."
            },
            "name": {
              "type": "object",
              "description": "Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        },
        "division": {
          "type": [
            "string",
            "null"
          ],
          "description": "Division the application is assigned to, `null` if not assigned."
        },
        "submitted": {
          "type": "string",
          "format": "date-time",
          "description": "Date and time when the application was submitted, in ISO 8601 format."
        },
        "auto_score": {
          "type": [
            "number",
            "null"
          ],
          "description": "Automated score calculated from the application's auto-scored fields, `null` if none."
        },
        "status": {
          "type": "string",
          "description": "Submission status of the application."
        },
        "grant_status": {
          "type": [
            "string",
            "null"
          ],
          "description": "Grant status of the application, `null` unless grants are enabled."
        },
        "link": {
          "type": "string",
          "format": "uri",
          "description": "Canonical URL for the application resource."
        },
        "scores": {
          "description": "Scores for the application, shaped by the score set mode (`voting`, `qualifying`, `scoring`, or `top_pick`).",
          "anyOf": [
            {
              "title": "Voting",
              "type": "object",
              "description": "Scores returned for a `voting` score set.",
              "properties": {
                "total_votes": {
                  "type": "integer",
                  "description": "Total number of votes the application received."
                }
              }
            },
            {
              "title": "Qualifying",
              "type": "object",
              "description": "Scores returned for a `qualifying` score set.",
              "properties": {
                "final_decision": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "enum": [
                    "pass",
                    "fail",
                    "unsure"
                  ],
                  "description": "Qualifying decision recorded for the application, `null` if none recorded."
                }
              }
            },
            {
              "title": "Scoring",
              "type": "object",
              "description": "Scores returned for a `scoring` score set.",
              "properties": {
                "total_score": {
                  "type": "object",
                  "description": "Aggregated score across all criteria.",
                  "properties": {
                    "value": {
                      "type": "number",
                      "description": "Total score awarded across all criteria."
                    },
                    "max_score": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ],
                      "description": "Maximum achievable total score, empty string if none configured."
                    },
                    "final_score": {
                      "type": "string",
                      "description": "Formatted total score, such as `8/10`, or `-` if no maximum is configured."
                    }
                  }
                },
                "criteria": {
                  "type": "array",
                  "description": "Per-criterion scores making up the total.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "object",
                        "description": "Map keyed by locale code (for example, `en_GB` or `fr_FR`), with the translated string as the value.",
                        "additionalProperties": {
                          "type": "string"
                        }
                      },
                      "value": {
                        "type": "number",
                        "description": "Score awarded for the criterion."
                      },
                      "max_score": {
                        "type": "integer",
                        "description": "Maximum achievable score for the criterion."
                      },
                      "final_score": {
                        "type": "string",
                        "description": "Formatted criterion score, such as `4/5`."
                      },
                      "weight": {
                        "type": "number",
                        "description": "Relative weight of the criterion in the total."
                      }
                    }
                  }
                }
              }
            },
            {
              "title": "Top Pick",
              "type": "object",
              "description": "Scores returned for a `top_pick` score set, keyed by preference position (for example, `preference_1`), with the number of reviewers at that position.",
              "additionalProperties": {
                "type": "integer"
              }
            }
          ]
        }
      }
    },
    "Pagination": {
      "type": "object",
      "title": "Pagination",
      "properties": {
        "current_page": {
          "type": "integer",
          "description": "Number of the page returned by this response, starting at `1`."
        },
        "first_page_url": {
          "type": "string",
          "description": "URL of the first page in the result set, relative when the requested page is beyond the last page."
        },
        "from": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Position of the first record on this page within the full result set, starting at `1`, or `null` when the requested page is beyond the last page."
        },
        "last_page": {
          "type": "integer",
          "description": "Total number of pages."
        },
        "last_page_url": {
          "type": "string",
          "description": "URL of the last page in the result set, relative when the requested page is beyond the last page."
        },
        "next_page_url": {
          "type": "string",
          "description": "URL of the next page in the result set, empty when the current page is the last page."
        },
        "path": {
          "type": "string",
          "description": "Canonical URL of the endpoint, without query parameters."
        },
        "per_page": {
          "type": "integer",
          "default": 10,
          "description": "Maximum number of records returned per page."
        },
        "prev_page_url": {
          "type": "string",
          "description": "URL of the previous page in the result set, empty when the current page is the first page."
        },
        "to": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Position of the last record on this page within the full result set, or `null` when the requested page is beyond the last page."
        },
        "total": {
          "type": "integer",
          "description": "Total number of records across all pages."
        }
      }
    }
  }
}