Incident

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/datasportsapi/json-schema/datasportsapi-incident-schema.json",
  "title": "Incident",
  "description": "Something that happened during a match. As with all timeline lists, entries run oldest first (chronological order).",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/datasportsapi-openapi.json#/components/schemas/Incident",
  "type": "object",
  "properties": {
    "type": {
      "$ref": "#/$defs/IncidentType",
      "description": "Category of the event."
    },
    "detail": {
      "anyOf": [
        {
          "$ref": "#/$defs/IncidentDetail"
        },
        {
          "type": "null"
        }
      ],
      "description": "Sub-category within the type; null on period and injuryTime rows."
    },
    "side": {
      "anyOf": [
        {
          "$ref": "#/$defs/Side"
        },
        {
          "type": "null"
        }
      ],
      "description": "Side the event is credited to (an own goal belongs to the side that benefits from it); null on period / injuryTime rows."
    },
    "minute": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Match minute. Null whenever the clock is stopped — before kick-off, at half-time and after full time, for bench events, and during a shoot-out. Unit: minutes."
    },
    "addedMinute": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "How far into stoppage time the event happened (90+3 gives minute 90, addedMinute 3). On injuryTime rows it holds the announced minutes. Unit: minutes."
    },
    "second": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Game clock in seconds, if the source supplies it — present on all rows in ice hockey, basketball, handball and rugby, but only on period rows in football. Unit: seconds."
    },
    "period": {
      "anyOf": [
        {
          "$ref": "#/$defs/PeriodKey"
        },
        {
          "type": "null"
        }
      ],
      "description": "Period in which the event took place. On period rows it is the period that just ended (ET → extra2, PEN → penalties, FT → period2 in football and period4 in basketball). On other rows it is the period bounded by the surrounding period rows, or the source’s own value when supplied; shoot-out kicks use penalties. Null only if it cannot be determined (no period row yet and the period length for the sport is unknown)."
    },
    "player": {
      "anyOf": [
        {
          "$ref": "#/$defs/PlayerRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "Main player involved: the scorer, the booked or penalised player, the subject of a VAR check, or the shoot-out taker."
    },
    "playerName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Name of the player; filled even when the source provides a name without a player record (as with some own goals)."
    },
    "assists": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/PlayerRef"
      },
      "description": "Players credited with assists on the goal, in order (up to two in ice hockey)."
    },
    "playerIn": {
      "anyOf": [
        {
          "$ref": "#/$defs/PlayerRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "For a substitution: the player entering the field."
    },
    "playerOut": {
      "anyOf": [
        {
          "$ref": "#/$defs/PlayerRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "For a substitution: the player leaving the field."
    },
    "drawnBy": {
      "anyOf": [
        {
          "$ref": "#/$defs/PlayerRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "For an ice hockey suspension: the player who drew the penalty."
    },
    "homeScore": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Home score immediately after the event (on goals, period rows and shoot-out kicks). For period rows in set sports (volleyball, table tennis, badminton) it is the number of sets won so far; the points inside each set are given by /points and by the fixture’s `periods`."
    },
    "awayScore": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Away score immediately after the event (sets won, on period rows in set sports)."
    },
    "text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "On period rows: the label a scoreboard would show (\"HT\", \"FT\", \"Q4\", \"3rd period\", \"Overtime\", \"PEN\"). For display only."
    },
    "reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "For a card, why it was shown (\"Foul\", \"Violent conduct\"); for a suspension, the offence (\"Holding\"); for a missed penalty, how it was missed (\"Goalkeeper save\", \"Off target\")."
    },
    "rescinded": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "For a card: true if it was later withdrawn."
    },
    "confirmed": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "For a varDecision: true when the original decision was upheld."
    },
    "shootoutSequence": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "For a shootoutPenalty: position of the kick in the overall order across both teams (1 is the opening kick of the shoot-out)."
    },
    "shootoutRound": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "For a shootoutPenalty: the round, i.e. whether it was the taking side’s 1st, 2nd, … kick."
    },
    "durationSeconds": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "For a suspension: how long the player is excluded. Unit: seconds."
    },
    "buildUp": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/BuildUpStep"
      },
      "description": "For a football goal: the sequence of passes and shots leading up to it, ending with the goal itself (covered leagues only; empty elsewhere and for all other incidents)."
    }
  },
  "required": [
    "type",
    "detail",
    "side",
    "minute",
    "addedMinute",
    "second",
    "period",
    "player",
    "playerName",
    "assists",
    "playerIn",
    "playerOut",
    "drawnBy",
    "homeScore",
    "awayScore",
    "text",
    "reason",
    "rescinded",
    "confirmed",
    "shootoutSequence",
    "shootoutRound",
    "durationSeconds",
    "buildUp"
  ],
  "$defs": {
    "BodyPart": {
      "type": "string",
      "enum": [
        "rightFoot",
        "leftFoot",
        "head",
        "other"
      ],
      "description": "Football: the part of the body used for a shot.",
      "x-enumDescriptions": {
        "rightFoot": "Struck with the right foot.",
        "leftFoot": "Struck with the left foot.",
        "head": "Headed.",
        "other": "Some other part of the body."
      }
    },
    "BuildUpAction": {
      "type": "string",
      "enum": [
        "pass",
        "cross",
        "throwIn",
        "freeKick",
        "carry",
        "touch",
        "tackle",
        "interception",
        "clearance",
        "savedShot",
        "missedShot",
        "post",
        "penaltySaved",
        "penaltyMissed",
        "goal",
        "other"
      ],
      "description": "The type of a single step in the move leading to a goal.",
      "x-enumDescriptions": {
        "pass": "A pass; `endPosition` marks where it was received.",
        "cross": "A cross; `endPosition` marks where it arrived.",
        "throwIn": "A throw-in; `endPosition` marks where it landed. Available since 2026-10-25.",
        "freeKick": "A free kick that fed into the move; `endPosition` marks where it arrived. Available since 2026-11-09.",
        "carry": "The player ran with the ball (ball-movement in the source), without an `endPosition`. Available since 2026-10-25.",
        "touch": "A block, deflection, goalkeeper’s parry or similar touch that kept the move going (ball-touch in the source). Available since 2026-10-25.",
        "tackle": "A ball-winning tackle from which the move begins or continues. Available since 2026-11-09.",
        "interception": "An intercepted pass from which the move begins or continues. Available since 2026-11-09.",
        "clearance": "Either team cleared the ball and play went on. Available since 2026-11-09.",
        "savedShot": "A shot saved by the goalkeeper, with play continuing from the rebound.",
        "missedShot": "An off-target shot after which play continued. Available since 2026-10-25.",
        "post": "A shot off the woodwork after which play continued. Available since 2026-11-09.",
        "penaltySaved": "A saved penalty kick, with play continuing from the rebound. Available since 2026-11-09.",
        "penaltyMissed": "A missed penalty kick after which play continued. Available since 2026-11-09.",
        "goal": "The scoring shot, always the final step.",
        "other": "An action without a mapping yet; we log the source’s value."
      }
    },
    "BuildUpStep": {
      "type": "object",
      "description": "A single action in the move leading to a goal, as mapped by the source (football, covered leagues).",
      "properties": {
        "action": {
          "$ref": "#/$defs/BuildUpAction",
          "description": "Type of action performed in this step."
        },
        "side": {
          "anyOf": [
            {
              "$ref": "#/$defs/Side"
            },
            {
              "type": "null"
            }
          ],
          "description": "Team of the player performing the action (for an own goal, the final step belongs to the defending side)."
        },
        "player": {
          "anyOf": [
            {
              "$ref": "#/$defs/PlayerRef"
            },
            {
              "type": "null"
            }
          ],
          "description": "Player who performed the action."
        },
        "minute": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Minute of the match. Unit: minutes."
        },
        "position": {
          "anyOf": [
            {
              "$ref": "#/$defs/PitchSpot"
            },
            {
              "type": "null"
            }
          ],
          "description": "Pitch location where the action began."
        },
        "endPosition": {
          "anyOf": [
            {
              "$ref": "#/$defs/PitchSpot"
            },
            {
              "type": "null"
            }
          ],
          "description": "For a pass / cross: where the ball ended up. Null for other actions."
        },
        "assist": {
          "type": "boolean",
          "description": "True for the pass credited as the assist."
        },
        "bodyPart": {
          "anyOf": [
            {
              "$ref": "#/$defs/BodyPart"
            },
            {
              "type": "null"
            }
          ],
          "description": "For the goal: the body part used to strike it."
        },
        "expectedGoals": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "For a goal / savedShot: xG value of the chance on a 0–1 scale, if the source provides it."
        },
        "expectedGoalsOnTarget": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "description": "For a goal / savedShot: expected goals on target (xGOT), if available."
        },
        "goalMouthLocation": {
          "anyOf": [
            {
              "$ref": "#/$defs/GoalMouthLocation"
            },
            {
              "type": "null"
            }
          ],
          "description": "For the goal: the area of the goal mouth it went into."
        }
      },
      "required": [
        "action",
        "side",
        "player",
        "minute",
        "position",
        "endPosition",
        "assist",
        "bodyPart",
        "expectedGoals",
        "expectedGoalsOnTarget",
        "goalMouthLocation"
      ]
    },
    "GoalMouthLocation": {
      "type": "string",
      "enum": [
        "lowLeft",
        "lowCentre",
        "lowRight",
        "highLeft",
        "highCentre",
        "highRight",
        "left",
        "right",
        "high",
        "closeLeft",
        "closeRight",
        "closeHigh",
        "closeHighLeft",
        "closeHighRight",
        "other"
      ],
      "description": "Football: where a shot finished in relation to the goal.",
      "x-enumDescriptions": {
        "lowLeft": "On target, bottom left as seen by the shooter.",
        "lowCentre": "On target, bottom centre.",
        "lowRight": "On target, bottom right.",
        "highLeft": "On target, top left.",
        "highCentre": "On target, top centre.",
        "highRight": "On target, top right.",
        "left": "Missed to the left.",
        "right": "Missed to the right.",
        "high": "Went over the crossbar.",
        "closeLeft": "Narrowly wide to the left.",
        "closeRight": "Narrowly wide to the right.",
        "closeHigh": "Narrowly over the bar.",
        "closeHighLeft": "Narrowly over, to the left.",
        "closeHighRight": "Narrowly over, to the right.",
        "other": "A location we have not classified yet."
      }
    },
    "IncidentDetail": {
      "type": "string",
      "enum": [
        "regular",
        "ownGoal",
        "penalty",
        "powerPlay",
        "shortHanded",
        "emptyNet",
        "onePoint",
        "twoPoints",
        "threePoints",
        "try",
        "touchdown",
        "extraPoint",
        "fieldGoal",
        "twoPointConversion",
        "safety",
        "yellow",
        "secondYellow",
        "red",
        "injury",
        "goalAwarded",
        "goalNotAwarded",
        "penaltyAwarded",
        "penaltyNotAwarded",
        "cardUpgrade",
        "cardDowngrade",
        "scored",
        "missed",
        "twoMinutes",
        "fiveMinutes",
        "tenMinutes",
        "fourMinutes",
        "awarded",
        "redCardGiven",
        "other"
      ],
      "description": "Refines an incident’s type into a more specific kind.",
      "x-enumDescriptions": {
        "regular": "For a goal, a standard goal; for a substitution, a tactical change.",
        "ownGoal": "goal: put into their own net by the conceding side; `side` is the team credited with it.",
        "penalty": "goal: a converted penalty kick or 7-metre throw.",
        "powerPlay": "goal (ice hockey): scored while the side had a man advantage.",
        "shortHanded": "goal (ice hockey): scored while the side was a man short.",
        "emptyNet": "goal (ice hockey): scored with no goalie in the net.",
        "onePoint": "goal (basketball): a made free throw.",
        "twoPoints": "goal: a 2-point field goal in basketball, or a conversion in rugby.",
        "threePoints": "goal: a 3-pointer in basketball, or a penalty goal or drop goal in rugby.",
        "try": "goal (rugby): try scored.",
        "touchdown": "goal (American football): touchdown scored.",
        "extraPoint": "goal (American football): extra point converted.",
        "fieldGoal": "goal (American football): field goal made.",
        "twoPointConversion": "goal (American football): successful two-point conversion.",
        "safety": "goal (American football): points from a safety.",
        "yellow": "card: a caution (yellow).",
        "secondYellow": "card: a second yellow, which means a sending-off.",
        "red": "card: a direct red.",
        "injury": "substitution: made because of an injury.",
        "goalAwarded": "varDecision: the review awarded a goal.",
        "goalNotAwarded": "varDecision: the review ruled a goal out.",
        "penaltyAwarded": "varDecision: the review awarded a penalty.",
        "penaltyNotAwarded": "varDecision: the review cancelled a penalty.",
        "cardUpgrade": "varDecision: the review raised a card (e.g. yellow → red).",
        "cardDowngrade": "varDecision: the review lowered a card.",
        "scored": "shootoutPenalty: the kick went in.",
        "missed": "shootoutPenalty / inGamePenalty: the kick failed, either missed or saved; `reason` tells which.",
        "twoMinutes": "suspension: minor penalty of two minutes.",
        "fiveMinutes": "suspension: major penalty of five minutes.",
        "tenMinutes": "suspension: misconduct penalty of ten minutes.",
        "fourMinutes": "suspension (ice hockey): double minor lasting four minutes. Available since 2026-11-09.",
        "awarded": "inGamePenalty: the referee gave a penalty kick; the kick is then logged separately (as `missed`, or as the goal). Available since 2026-11-09.",
        "redCardGiven": "varDecision: the review produced a red card. Available since 2026-11-09.",
        "other": "A kind supplied by the source that DataSportsAPI does not classify yet."
      }
    },
    "IncidentType": {
      "type": "string",
      "enum": [
        "goal",
        "card",
        "substitution",
        "period",
        "injuryTime",
        "varDecision",
        "inGamePenalty",
        "shootoutPenalty",
        "suspension"
      ],
      "description": "The kind of match event.",
      "x-enumDescriptions": {
        "goal": "Any score, whether a goal, basket, try, touchdown, …; `detail` gives the kind. Points are not listed for set sports (volleyball, table tennis, badminton); the end of each set appears as a `period` row instead.",
        "card": "A card shown to a team official or a player.",
        "substitution": "A substitution in which playerIn comes on for playerOut.",
        "period": "The end of a period, and nothing else: since 2026-10-23 a period still in progress gets no row. `period` names the period just finished, and `text` holds its scoreboard label (FT, HT, Q2, 2. set, 3rd period, …). The scores show the match score at that moment — for volleyball, table tennis and badminton the sets won so far; the points inside each set are given by /points and by the fixture’s `periods`.",
        "injuryTime": "Announcement of added time: `addedMinute` extra minutes following `minute`.",
        "varDecision": "The outcome of a video review, described by `detail`; `confirmed` means the original call was upheld.",
        "inGamePenalty": "A penalty kick taken during play that did not result in a goal (`detail` missed). A converted penalty is recorded as a `goal` with detail `penalty`.",
        "shootoutPenalty": "A single kick in a penalty shoot-out. `shootoutSequence` is its position in the overall order (1, 2, 3, …, counting both sides) and `shootoutRound` is the round, i.e. the 1st, 2nd, … kick of the taker’s side.",
        "suspension": "A time-limited exclusion such as an ice hockey penalty or a handball two-minute suspension, with `durationSeconds` and `reason`."
      }
    },
    "PeriodKey": {
      "type": "string",
      "pattern": "^(?:period[1-9][0-9]*|inning[1-9][0-9]*|extra[12]|overtime|penalties)$",
      "description": "periodN: Regulation period number N. What a period is depends on the sport: a half in football, rugby, handball, futsal, minifootball and bandy; a quarter in basketball, American football and water polo; a period in ice hockey and floorball; a set in tennis, volleyball, table tennis, badminton and padel; an inning in baseball; a round in combat sports; a map / game in esports; a leg / frame block in darts and snooker. inningN: Cricket only: innings number N. extra1: Football and futsal: the opening half of extra time. extra2: Football and futsal: the closing half of extra time. overtime: Every overtime period summed into one value (American football, basketball, handball, ice hockey, water polo, …). In baseball it holds the runs scored in extra innings, and only when the source provides no inning-by-inning split (period10, …). penalties: The penalty shoot-out, which appears only as a `status.period` value; its score is kept in ScoreSide.penalties, not under a `periods` key."
    },
    "PitchSpot": {
      "type": "object",
      "description": "A location on a football pitch.",
      "properties": {
        "x": {
          "type": "number",
          "description": "Lengthwise position from 0 to 100, oriented in the attacking direction of the SCORING side (100 is the goal the ball ended up in, own goals included). For away goals we rotate the source’s coordinates, in which the home side always attacks towards 100 (corrected 2026-10-23). Unit: percent."
        },
        "y": {
          "type": "number",
          "description": "Widthwise position from 0 to 100, rotated together with x (seen from the scoring side). Unit: percent."
        }
      },
      "required": [
        "x",
        "y"
      ]
    },
    "PlayerRef": {
      "type": "object",
      "description": "Compact player reference embedded in other objects.",
      "properties": {
        "id": {
          "type": "integer",
          "description": "The player’s DataSportsAPI id."
        },
        "name": {
          "type": "string",
          "description": "Name of the player."
        },
        "slug": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Slug for use in URLs."
        },
        "shortName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Abbreviated display name such as \"B. Saka\", if the source provides one."
        },
        "image": {
          "anyOf": [
            {
              "type": "string",
              "format": "uri"
            },
            {
              "type": "null"
            }
          ],
          "description": "Player photo hosted on our CDN; null if the player has no image."
        }
      },
      "required": [
        "id",
        "name",
        "slug",
        "shortName",
        "image"
      ]
    },
    "Side": {
      "type": "string",
      "enum": [
        "home",
        "away"
      ],
      "description": "One of the two sides in a fixture.",
      "x-enumDescriptions": {
        "home": "The side listed as home in the fixture.",
        "away": "The side listed as away in the fixture."
      }
    }
  }
}