Event

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bigballsdata-com/json-schema/bigballsdata-com-event-schema.json",
  "title": "Event",
  "description": "One play/incident row from `/v1/matches/{id}/events`. The ordering key is `sequence_number`, and there is no per-event `id` or `match_id`: the match is the one in the path. Until 2026-09-18 this schema required `id`, `match_id` and `sequence`, none of which is returned.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/bigballsdata-com-api-openapi.json#/components/schemas/Event",
  "type": "object",
  "properties": {
    "sequence_number": {
      "type": "integer",
      "minimum": 1,
      "description": "Ordering key within the match."
    },
    "elapsed": {
      "type": "integer",
      "minimum": 0,
      "description": "Soccer minute from the live adapter."
    },
    "elapsed_extra": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "team": {
      "type": [
        "string",
        "null"
      ]
    },
    "player_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "player_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "headshot_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri"
    },
    "assist_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "assist_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "assist_headshot_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri"
    },
    "event_type": {
      "type": [
        "string",
        "null"
      ]
    },
    "event_detail": {
      "type": [
        "string",
        "null"
      ]
    },
    "card_class": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "second_yellow",
        "straight_red",
        "yellow",
        null
      ],
      "description": "Football only. Whether a dismissal was a SECOND YELLOW or a DIRECT (straight) RED, derived from the player's card sequence in this match, because the upstream feed labels every card either `Yellow Card` or `Red Card` and states nothing more. `event_detail` is unchanged and still carries the upstream label verbatim. Definitions, applied consistently: `second_yellow` means the player has exactly two yellows and exactly one red in this match; `straight_red` means exactly one red and no yellow; `yellow` is any booking. `null` means WE WILL NOT SAY, and for a red card that is a deliberate verdict rather than missing data: it covers a red following exactly one booking (which cannot be told apart from a second yellow with a missing first booking), any player-match where VAR reviewed, upgraded or cancelled a card, more than one dismissal for one player, and events whose player cannot be identified. An unlabelled red is still returned in full."
    },
    "period": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "period_display": {
      "type": [
        "string",
        "null"
      ]
    },
    "clock": {
      "oneOf": [
        {
          "$ref": "#/$defs/Clock"
        },
        {
          "type": "null"
        }
      ],
      "description": "Null on feeds that carry no clock; 8 of 8 sampled baseball events were null."
    },
    "type": {
      "type": "string"
    },
    "team_id": {
      "$ref": "#/$defs/StoredId"
    },
    "related_player_id": {
      "$ref": "#/$defs/StoredId"
    },
    "description": {
      "type": "string"
    },
    "scoring_play": {
      "type": "boolean"
    },
    "score_value": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Points/runs this event added."
    },
    "home_score": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Running home score AFTER this event."
    },
    "away_score": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Running away score AFTER this event."
    },
    "coordinate_x": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Soccer shot location: the SHOOTER's position on a 0-100 normalised pitch. `null` on non-shot events and on any event from a feed that carries no positions."
    },
    "coordinate_y": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "xg": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Expected goals for a shot, 0-1. `null` means the source does not model xG for this event, never \"zero chance\"."
    },
    "xgot": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "Expected goals on target. Present only for shots that were on target; `null` for misses and blocks by design."
    },
    "down": {
      "oneOf": [
        {
          "type": "integer",
          "minimum": 1,
          "maximum": 4
        },
        {
          "type": "null"
        }
      ],
      "description": "NFL down; null for plays without a down and for non-NFL events."
    },
    "distance": {
      "oneOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "NFL yards to gain; null for non-NFL events."
    },
    "yards_to_endzone": {
      "oneOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "NFL field position measured in yards from the opponent end zone."
    },
    "yards_gained": {
      "oneOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "NFL yards gained on the play; null for non-NFL events."
    },
    "epa": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "NFL expected points added; null when unavailable or on non-NFL events."
    },
    "win_probability": {
      "oneOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "NFL possession-team win probability after the play."
    },
    "defending_team_id": {
      "oneOf": [
        {
          "$ref": "#/$defs/StoredId"
        },
        {
          "type": "null"
        }
      ],
      "description": "Canonical defending-team UUID on NFL rows; null otherwise."
    }
  },
  "$defs": {
    "Clock": {
      "type": "object",
      "required": [
        "elapsed_seconds",
        "period"
      ],
      "properties": {
        "elapsed_seconds": {
          "type": "integer",
          "minimum": 0
        },
        "period": {
          "type": "integer",
          "minimum": 0,
          "maximum": 20
        },
        "added_seconds": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "StoredId": {
      "type": "string",
      "format": "uuid",
      "description": "A stored BigBalls id. This is the identifier every match, team, player and league endpoint returns, and the one every `{id}` path segment accepts. Take it from the `id` field of the corresponding list endpoint and use it as-is."
    }
  }
}