RaceResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/datasportsapi/json-schema/datasportsapi-race-result-schema.json",
  "title": "RaceResult",
  "description": "A single competitor’s entry in the classification of a session or race.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/datasportsapi-openapi.json#/components/schemas/RaceResult",
  "type": "object",
  "properties": {
    "position": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Finishing position; null for a competitor who is not classified (check `state`)."
    },
    "competitor": {
      "anyOf": [
        {
          "$ref": "#/$defs/TeamRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "Who raced: a driver or rider, represented as a TeamRef with kind individual."
    },
    "team": {
      "anyOf": [
        {
          "$ref": "#/$defs/TeamRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "Constructor or cycling team the competitor belongs to."
    },
    "state": {
      "$ref": "#/$defs/RaceResultState",
      "description": "Whether the competitor is classified, and if not, the reason."
    },
    "outReason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Reason for being out, in our data source’s wording (\"Retired\"); null for classified competitors."
    },
    "carNumber": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Race number on the car or bike (motorsport)."
    },
    "gridPosition": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Grid slot at the start (races); null for a pit-lane start or when unknown."
    },
    "startedFromPitLane": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Set to `true` for a pit-lane start."
    },
    "laps": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Lap count according to our data source."
    },
    "lapsBehind": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "How many laps down on the winner (for lapped cars); null if on the lead lap."
    },
    "lapsLed": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Number of laps spent in the lead."
    },
    "pitStops": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Number of pit stops made."
    },
    "timeMs": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Overall time in ms for a race or stage, or the best lap in practice and qualifying. Null for lapped and non-classified competitors, and for a classified rider without a time in our data source. Unit: milliseconds."
    },
    "gapMs": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Gap to the winner. Null for the winner itself, for lapped or non-classified competitors, and for a classified rider with no time logged by our data source. Unit: milliseconds."
    },
    "intervalMs": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Gap to the competitor immediately in front; null for the winner, for lapped and non-classified competitors, and for a classified rider without a time in our data source. Unit: milliseconds."
    },
    "bestLapMs": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Quickest lap this competitor set, in ms (races). Unit: milliseconds."
    },
    "bestLapNumber": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Number of the lap on which that best time came."
    },
    "fastestLap": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "`true` if this was the quickest lap of the whole session."
    },
    "points": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Championship points earned from this result."
    },
    "tyreStints": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/TyreStint"
      },
      "description": "Sequence of tyre stints (Formula 1 races only; empty elsewhere)."
    },
    "currentTyre": {
      "anyOf": [
        {
          "$ref": "#/$defs/CurrentTyre"
        },
        {
          "type": "null"
        }
      ],
      "description": "The set of tyres currently fitted (Formula 1 sessions while running, then the final set once over); null if our data source does not report it. Available since 2026-11-09."
    },
    "inPit": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Whether the car is currently in the pit lane during a live session (`true`); null if our data source does not report it. Available since 2026-11-09."
    },
    "cycling": {
      "anyOf": [
        {
          "$ref": "#/$defs/CyclingStanding"
        },
        {
          "type": "null"
        }
      ],
      "description": "Secondary classifications, present on the overall result of a cycling stage race; null elsewhere."
    },
    "part": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the classification is stitched together from qualifying segments (MotoGP qualifying, for which our data source has no combined table), the segment this entry was taken from (\"Q2\", \"Q1\"); timeMs / gapMs / intervalMs then refer to that segment. Null otherwise."
    }
  },
  "required": [
    "position",
    "competitor",
    "team",
    "state",
    "outReason",
    "carNumber",
    "gridPosition",
    "startedFromPitLane",
    "laps",
    "lapsBehind",
    "lapsLed",
    "pitStops",
    "timeMs",
    "gapMs",
    "intervalMs",
    "bestLapMs",
    "bestLapNumber",
    "fastestLap",
    "points",
    "tyreStints",
    "currentTyre",
    "inPit",
    "cycling",
    "part"
  ],
  "$defs": {
    "CurrentTyre": {
      "type": "object",
      "description": "Tyres currently fitted to a car (available since 2026-11-09).",
      "properties": {
        "compound": {
          "$ref": "#/$defs/TyreCompound",
          "description": "Tyre compound."
        },
        "isNew": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "description": "True for a fresh set, false for a used one; null if the source does not specify."
        }
      },
      "required": [
        "compound",
        "isNew"
      ]
    },
    "CyclingJersey": {
      "type": "string",
      "enum": [
        "general",
        "points",
        "mountains",
        "young",
        "other"
      ],
      "description": "A jersey worn by a classification leader in a cycling stage race.",
      "x-enumDescriptions": {
        "general": "General classification leader; the yellow jersey at the Tour.",
        "points": "Points classification leader; green at the Tour.",
        "mountains": "Mountains classification leader; polka dot at the Tour.",
        "young": "Top young rider; white at the Tour.",
        "other": "Any jersey missing from this list."
      }
    },
    "CyclingStanding": {
      "type": "object",
      "description": "Secondary-classification standings for one rider within a stage race’s overall result.",
      "properties": {
        "jersey": {
          "anyOf": [
            {
              "$ref": "#/$defs/CyclingJersey"
            },
            {
              "type": "null"
            }
          ],
          "description": "Leader’s jersey worn by this rider, if there is one."
        },
        "pointsPosition": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Where the rider sits in the points classification."
        },
        "points": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Points tallied in the points classification."
        },
        "mountainsPosition": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Where the rider sits in the mountains classification."
        },
        "mountainsPoints": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "Points tallied in the mountains classification."
        },
        "youngRiderPosition": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Where the rider sits in the young-rider classification."
        },
        "youngRiderTimeMs": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Time on which the young-rider classification is based (total, in ms). Unit: milliseconds."
        }
      },
      "required": [
        "jersey",
        "pointsPosition",
        "points",
        "mountainsPosition",
        "mountainsPoints",
        "youngRiderPosition",
        "youngRiderTimeMs"
      ]
    },
    "RaceResultState": {
      "type": "string",
      "enum": [
        "classified",
        "didNotFinish",
        "didNotStart",
        "disqualified",
        "notClassified"
      ],
      "description": "A competitor’s status within a classification.",
      "x-enumDescriptions": {
        "classified": "Included in the classification, whether lapped or not; `position` is filled unless the source left a gap there.",
        "didNotFinish": "Took the start but failed to finish (retired, crashed out); has no position.",
        "didNotStart": "Was entered but never started; has no position.",
        "disqualified": "Excluded by disqualification; has no position.",
        "notClassified": "Left out of the classification for some other reason (the source flags the row as out without explanation); has no position."
      }
    },
    "TeamRef": {
      "type": "object",
      "description": "Compact team reference embedded in other objects (fixtures, standings, players, leaders).",
      "properties": {
        "id": {
          "type": "integer",
          "description": "The team’s DataSportsAPI id."
        },
        "name": {
          "type": "string",
          "description": "Name of the team. Individual sports (tennis, table tennis, darts, MMA, …) also model each competitor as a team — a single player, or a doubles pair."
        },
        "slug": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Slug for use in URLs."
        },
        "shortName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Abbreviated display name, if the source provides one."
        },
        "code": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Abbreviation of 1–4 characters as used on scoreboards (e.g. \"ARS\", \"LA\"); generated artificially for individual sports."
        },
        "image": {
          "anyOf": [
            {
              "type": "string",
              "format": "uri"
            },
            {
              "type": "null"
            }
          ],
          "description": "Team logo hosted on our CDN; null if the team has no image."
        }
      },
      "required": [
        "id",
        "name",
        "slug",
        "shortName",
        "code",
        "image"
      ]
    },
    "TyreCompound": {
      "type": "string",
      "enum": [
        "soft",
        "medium",
        "hard",
        "intermediate",
        "wet",
        "other"
      ],
      "description": "Formula 1 tyre compound.",
      "x-enumDescriptions": {
        "soft": "The soft slick, \"S\" in the source.",
        "medium": "The medium slick, \"M\".",
        "hard": "The hard slick, \"H\".",
        "intermediate": "The intermediate, used on a damp track, \"I\".",
        "wet": "The full wet tyre, \"W\".",
        "other": "Any compound letter missing from this list."
      }
    },
    "TyreStint": {
      "type": "object",
      "description": "A run on a single set of tyres.",
      "properties": {
        "compound": {
          "$ref": "#/$defs/TyreCompound",
          "description": "Tyre compound used."
        },
        "laps": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Number of laps completed on this set."
        }
      },
      "required": [
        "compound",
        "laps"
      ]
    }
  }
}