# statsbomb/open-data architecture

> Architecture diagram of the GitHub repository statsbomb/open-data, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/statsbomb/open-data
- Repository: https://github.com/statsbomb/open-data

## Overview

1. This repository is a static data distribution repo, not an application. Its purpose is to publish StatsBomb football data as versioned JSON files for research and analysis.

2. The top-level `data/` directory is the core product. It contains the canonical datasets exported from the StatsBomb Data API and organized by entity type rather than by software subsystem.

3. `data/competitions.json` is the entry index. It defines the available competitions and seasons and acts as the first lookup layer for navigating the rest of the dataset.

4. `data/matches/` is the competition/season hierarchy. Each subfolder is a competition ID, and each file inside is a season ID. This is the bridge between the competition catalog and match-level records.

5. `data/events/` is match-centric event data. Each JSON file is named by match ID and stores the event timeline for that match. This is typically the richest behavioral dataset in the repo.

6. `data/lineups/` mirrors `data/events/` at the same match-ID granularity. For each match, it provides squad and player lineup information that complements the event stream.

7. `data/three-sixty/` contains StatsBomb 360 frame data for selected matches only. It is also keyed by match ID, but it is a sparse augmentation layer rather than a complete parallel dataset.

8. The main data flow is hierarchical: competition/season metadata in `competitions.json` points to match lists, and match IDs then join together events, lineups, and sometimes 360-frame data. The match ID is the primary foreign key across the repository.

9. The `doc/` directory contains PDF specifications and format documentation for each dataset type. These documents define the schema and semantics needed to interpret the JSON correctly.

10. `README.md` is the public entry point and explains the dataset layout and usage conventions. `LICENSE.pdf` and the usage terms in the README define distribution and attribution boundaries.

11. `img/` appears to be a supporting asset folder, likely for branding or documentation, but it is not part of the data model itself.

12. Because there is no executable code, build pipeline, or service layer in the repository, the architecture diagram should emphasize storage, dataset relationships, and documentation rather than runtime components.

Main entry points: [`README.md`](https://github.com/statsbomb/open-data/blob/master/README.md) (README), [`data/matches`](https://github.com/statsbomb/open-data/tree/master/data/matches) (Matches), [`data/events`](https://github.com/statsbomb/open-data/tree/master/data/events) (Events), [`doc/StatsBomb Open Data Specification v1.1.pdf`](https://github.com/statsbomb/open-data/blob/HEAD/doc/StatsBomb%20Open%20Data%20Specification%20v1.1.pdf) (Spec Guide)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_root["Repository"]
  node_n_readme["README<br/>entry doc<br/>[README.md]"]
  node_n_license["License<br/>distribution terms<br/>[LICENSE.pdf]"]
  node_n_img["Assets<br/>support files"]
end

subgraph group_g_data["Data"]
  node_n_competitions["Competitions<br/>catalog json<br/>[competitions.json]"]
  node_n_matches[("Matches<br/>competition-season index")]
  node_n_events[("Events<br/>match event json")]
  node_n_lineups[("Lineups<br/>match lineup json")]
  node_n_360[("360 Frames<br/>sparse match json")]
end

subgraph group_g_docs["Docs"]
  node_n_doc_spec["Spec Guide<br/>format spec"]
  node_n_doc_comp["Competitions PDF<br/>dataset spec"]
  node_n_doc_matches["Matches PDF<br/>dataset spec"]
  node_n_doc_events["Events PDF<br/>dataset spec"]
  node_n_doc_lineups["Lineups PDF<br/>dataset spec"]
  node_n_doc_360["360 PDF<br/>dataset spec"]
end

node_n_readme -->|"describes"| node_n_competitions
node_n_readme -->|"documents"| node_n_matches
node_n_readme -->|"documents"| node_n_events
node_n_readme -->|"documents"| node_n_lineups
node_n_readme -->|"documents"| node_n_360
node_n_license -->|"governs"| node_n_readme
node_n_competitions -->|"indexes"| node_n_matches
node_n_matches -->|"joins to"| node_n_events
node_n_matches -->|"joins to"| node_n_lineups
node_n_matches -->|"joins to"| node_n_360
node_n_events -.->|"complements"| node_n_lineups
node_n_events -.->|"augmented by"| node_n_360
node_n_doc_spec -->|"specifies"| node_n_competitions
node_n_doc_spec -->|"specifies"| node_n_matches
node_n_doc_spec -->|"specifies"| node_n_events
node_n_doc_spec -->|"specifies"| node_n_lineups
node_n_doc_spec -->|"specifies"| node_n_360
node_n_doc_comp -->|"documents"| node_n_competitions
node_n_doc_matches -->|"documents"| node_n_matches
node_n_doc_events -->|"documents"| node_n_events
node_n_doc_lineups -->|"documents"| node_n_lineups
node_n_doc_360 -->|"documents"| node_n_360
node_n_img -.->|"supports"| node_n_readme

click node_n_readme "https://github.com/statsbomb/open-data/blob/master/README.md"
click node_n_license "https://github.com/statsbomb/open-data/blob/master/LICENSE.pdf"
click node_n_img "https://github.com/statsbomb/open-data/tree/master/img"
click node_n_competitions "https://github.com/statsbomb/open-data/blob/master/data/competitions.json"
click node_n_matches "https://github.com/statsbomb/open-data/tree/master/data/matches"
click node_n_events "https://github.com/statsbomb/open-data/tree/master/data/events"
click node_n_lineups "https://github.com/statsbomb/open-data/tree/master/data/lineups"
click node_n_360 "https://github.com/statsbomb/open-data/tree/master/data/three-sixty"
click node_n_doc_spec "https://github.com/statsbomb/open-data/blob/master/doc/StatsBomb Open Data Specification v1.1.pdf"
click node_n_doc_comp "https://github.com/statsbomb/open-data/blob/master/doc/Open Data Competitions v2.0.0.pdf"
click node_n_doc_matches "https://github.com/statsbomb/open-data/blob/master/doc/Open Data Matches v3.0.0.pdf"
click node_n_doc_events "https://github.com/statsbomb/open-data/blob/master/doc/Open Data Events v4.0.0.pdf"
click node_n_doc_lineups "https://github.com/statsbomb/open-data/blob/master/doc/Open Data Lineups v2.0.0.pdf"
click node_n_doc_360 "https://github.com/statsbomb/open-data/blob/master/doc/Open Data 360 Frames v1.0.0 (1).pdf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_readme,node_n_license,node_n_img toneBlue
class node_n_competitions,node_n_matches,node_n_events,node_n_lineups,node_n_360 toneAmber
class node_n_doc_spec,node_n_doc_comp,node_n_doc_matches,node_n_doc_events,node_n_doc_lineups,node_n_doc_360 toneMint
```

## Components

### Repository

Static StatsBomb open data distribution

- [README](https://github.com/statsbomb/open-data/blob/master/README.md): entry doc · Public overview and usage conventions · `README.md`
- [License](https://github.com/statsbomb/open-data/blob/master/LICENSE.pdf): distribution terms · Repository usage and attribution boundary · `LICENSE.pdf`
- [Assets](https://github.com/statsbomb/open-data/tree/master/img): support files · Supplementary imagery and branding assets · `img`

### Data

Canonical versioned JSON datasets

- [Competitions](https://github.com/statsbomb/open-data/blob/master/data/competitions.json): catalog json · Entry index of competitions and seasons · `data/competitions.json`
- [Matches](https://github.com/statsbomb/open-data/tree/master/data/matches): competition-season index · Competition and season hierarchy keyed by IDs · `data/matches`
- [Events](https://github.com/statsbomb/open-data/tree/master/data/events): match event json · Match-level event timelines · `data/events`
- [Lineups](https://github.com/statsbomb/open-data/tree/master/data/lineups): match lineup json · Match-level squad and player lineups · `data/lineups`
- [360 Frames](https://github.com/statsbomb/open-data/tree/master/data/three-sixty): sparse match json · Selected-match 360 frame augmentations · `data/three-sixty`

### Docs

PDF specifications and usage guidance

- [Spec Guide](https://github.com/statsbomb/open-data/blob/HEAD/doc/StatsBomb%20Open%20Data%20Specification%20v1.1.pdf): format spec · Repository-wide specification reference · `doc/StatsBomb Open Data Specification v1.1.pdf`
- [Competitions PDF](https://github.com/statsbomb/open-data/blob/HEAD/doc/Open%20Data%20Competitions%20v2.0.0.pdf): dataset spec · Competition and season schema documentation · `doc/Open Data Competitions v2.0.0.pdf`
- [Matches PDF](https://github.com/statsbomb/open-data/blob/HEAD/doc/Open%20Data%20Matches%20v3.0.0.pdf): dataset spec · Matches dataset schema documentation · `doc/Open Data Matches v3.0.0.pdf`
- [Events PDF](https://github.com/statsbomb/open-data/blob/HEAD/doc/Open%20Data%20Events%20v4.0.0.pdf): dataset spec · Events dataset schema documentation · `doc/Open Data Events v4.0.0.pdf`
- [Lineups PDF](https://github.com/statsbomb/open-data/blob/HEAD/doc/Open%20Data%20Lineups%20v2.0.0.pdf): dataset spec · Lineups dataset schema documentation · `doc/Open Data Lineups v2.0.0.pdf`
- [360 PDF](https://github.com/statsbomb/open-data/blob/HEAD/doc/Open%20Data%20360%20Frames%20v1.0.0%20(1).pdf): dataset spec · 360 frames dataset schema documentation · `doc/Open Data 360 Frames v1.0.0 (1).pdf`

## Connections

- README → Competitions: describes · Explains the main data entry point
- README → Matches: documents · Explains dataset layout and navigation
- README → Events: documents · Explains match event data
- README → Lineups: documents · Explains match lineup data
- README → 360 Frames: documents · Explains 360 frame data
- License → README: governs · Defines distribution and attribution terms
- Competitions → Matches: indexes · Competition and season metadata points to match lists
- Matches → Events: joins to · Match IDs bridge into match event records
- Matches → Lineups: joins to · Match IDs bridge into lineups
- Matches → 360 Frames: joins to · Match IDs bridge into sparse 360 frames
- Events → Lineups: complements · Lineups augment the event stream at match level
- Events → 360 Frames: augmented by · Some matches have 360 frame data alongside events
- Spec Guide → Competitions: specifies · General schema and semantics reference
- Spec Guide → Matches: specifies · General schema and semantics reference
- Spec Guide → Events: specifies · General schema and semantics reference
- Spec Guide → Lineups: specifies · General schema and semantics reference
- Spec Guide → 360 Frames: specifies · General schema and semantics reference
- Competitions PDF → Competitions: documents · Competition dataset format
- Matches PDF → Matches: documents · Matches dataset format
- Events PDF → Events: documents · Events dataset format
- Lineups PDF → Lineups: documents · Lineups dataset format
- 360 PDF → 360 Frames: documents · 360 frames dataset format
- Assets → README: supports · Supporting assets for presentation or docs
