schema reference

Football Data

FootballData

Merged English football season dataset. Season records contain a seasonInfo summary and zero or more tierN league-table records.

Schema Links

Contents

Root

Root
anchor
type object 1 requiredclosed object

Merged English football season dataset. Season records contain a seasonInfo summary and zero or more tierN league-table records.

Property key Type Use Notes
metadata DatasetMetadata optional No description.
clubs ClubsMap optional Optional embedded club metadata. Release assets normally publish club metadata as a sidecar file instead.
seasons SeasonsMap required No description.

Clubs Map

ClubsMap
anchor
type object closed objectpattern keys
Property key Type Use Notes
^[a-z0-9][a-z0-9 -]*$ ClubMetadata optional Pattern property.

Dataset Metadata

DatasetMetadata
anchor
type object closed object

Build provenance for a generated FootballData export.

Property key Type Use Notes
schemaVersion integer optional Version of the generated dataset contract.
generator string | null optional Generator or merge command that produced this export.
generatedAt string | null optional ISO timestamp for the data generation run.
gitSha string | null optional Git commit SHA used for the data generation run.
sourceFiles array optional Input files used to build the export.
buildOptions object optional Selected build options captured as primitive values.

League Structure Special Case

LeagueStructureSpecialCase
anchor
type object 3 requiredclosed object

A documented league-structure exception attached to a season summary.

Property key Type Use Notes
type string required No description.
levels array required No description.
tierKeys array required No description.
notes string | null optional No description.

League Table Entry

LeagueTableEntry
anchor
type object 18 requiredclosed object

One final league-table row.

Property key Type Use Notes
pos integer required No description.
team string required No description.
played integer required No description.
won integer required No description.
drawn integer required No description.
lost integer required No description.
goalsFor integer required No description.
goalsAgainst integer required No description.
goalDifference integer | null required No description.
goalAverage number | null required No description.
points integer required No description.
notes string | null required No description.
wasRelegated boolean required No description.
wasPromoted boolean required No description.
isExpansionTeam boolean required No description.
wasReElected boolean required No description.
wasReprieved boolean required No description.
outcomeStatus string | null required Administrative or exceptional row outcome, such as expelled, folded, resigned, failed-re-election-and-demoted, reprieved, or relegated-after-points-deduction. Null for ordinary rows.

Season Data

SeasonData
anchor
type object 1 requiredclosed objectpattern keys

A single season. Wartime or abandoned placeholder seasons may contain only seasonInfo.

Property key Type Use Notes
seasonInfo SeasonInfo required No description.
^tier\d+$ TierData optional Pattern property.

Season Info

SeasonInfo
anchor
type object 4 requiredclosed object

Season-level summary. promoted and relegated describe movement into and out of the next season's top flight.

Property key Type Use Notes
season integer required Starting year for the season.
table array required Always empty. seasonInfo is a summary object, not a league table.
relegated StringList required No description.
promoted StringList required No description.
seasonSlug string | null optional No description.
sourceUrl string | null optional No description.
tableCount integer | null optional No description.
competitionStatus string | null optional No description.
warSuspensionLabel string | null optional No description.
officialLeagueTables boolean | null optional No description.
officialCompetitionsSuspended boolean | null optional No description.
officialCompetitionsAbandoned boolean | null optional No description.
regionalBridgeSeason boolean | null optional No description.
promotionRelegationApplies boolean | null optional No description.
specialCompetitions StringList optional No description.
leagueStructureSpecialCases array optional Known structural exceptions for a season, such as parallel regional leagues or restructure placement rules.
notes string | null optional No description.

Seasons Map

SeasonsMap
anchor
type object closed objectpattern keys

Map of starting season year to season data. For example, 2025 means the 2025-26 season.

Property key Type Use Notes
^\d{4}$ SeasonData optional Pattern property.

String List

StringList
anchor
type array

No named properties.

Tier Data

TierData
anchor
type object 4 requiredclosed object

League-table data for one tier in a season.

Property key Type Use Notes
season integer required No description.
table array required No description.
relegated StringList required No description.
promoted StringList required No description.
metadata TierMetadata optional No description.
divisions array optional Parallel league tables that share this pyramid level.

Tier Division Data

TierDivisionData
anchor
type object 4 requiredclosed object

One league table inside a parallel tier.

Property key Type Use Notes
season integer required No description.
table array required No description.
relegated StringList required No description.
promoted StringList required No description.
metadata TierMetadata optional No description.

Tier Metadata

TierMetadata
anchor
type object closed object

Source and table-selection metadata for a tier record.

Property key Type Use Notes
source string optional No description.
sourceUrl string | null optional No description.
seasonSlug string | null optional No description.
leagueId string | null optional No description.
title string | null optional No description.
leagueLevel integer | null optional No description.
structure string | null optional No description.
parallelGroup string | null optional No description.
divisionKey string | null optional No description.
divisionCount integer | null optional No description.
tableIndex integer | null optional No description.
tableCount integer | null optional No description.
tierKey string | null optional No description.