Common Data Format - Official Match Data

Type: object

Version 0.3.2

This schema defines the Official Match Data as described in the Common Data Format paper.

root match

root match allOf item 0
Type: object

If the conditions in the "If" tab are respected, then the conditions in the "Then" tab should be respected. Otherwise, the conditions in the "Else" tab should be respected.

root match allOf item 0 if
Type: object

root match allOf item 0 if status
Type: object

root match allOf item 0 if status has_extratime
Type: const
Specific value: true
root match allOf item 0 then
Type: object

root match allOf item 0 then result
Type: object

The following properties are required:

  • first_half_extratime
  • second_half_extratime
root match allOf item 1
Type: object

If the conditions in the "If" tab are respected, then the conditions in the "Then" tab should be respected. Otherwise, the conditions in the "Else" tab should be respected.

root match allOf item 1 if
Type: object

root match allOf item 1 if status
Type: object

root match allOf item 1 if status has_shootout
Type: const
Specific value: true
root match allOf item 1 then
Type: object

root match allOf item 1 then result
Type: object

The following properties are required:

  • shootout

root match id
Type: string

Unique match identifier

root match status
Type: object

root match status is_neutral
Type: boolean

Denotes whether the game was hosted in a neutral venue (true) or not (false)

root match status has_extratime
Type: boolean

Denotes whether the game went to extra time (true) or not (false)

root match status has_shootout
Type: boolean

Denotes whether the game had a penalty shootout (true) or not (false)

root match result
Type: object

root match result final
Type: object

root match result final home
Type: integer

Result after the final whistle excluding penalty shootout goals (i.e. home goals, away goals)

root match result final away
Type: integer

Result after the final whistle excluding penalty shootout goals (i.e. home goals, away goals)

root match result final winning_team_id
Type: string or null

Unique identifier of the winning team, null when the match was drawn and no shootout was played

root match result first_half
Type: object

root match result first_half home
Type: integer

Result after the first half (i.e. home goals, away goals)

root match result first_half away
Type: integer

Result after the first half (i.e. home goals, away goals)

root match result second_half
Type: object

root match result second_half home
Type: integer

Result after the second half (i.e. home goals, away goals)

root match result second_half away
Type: integer

Result after the second half (i.e. home goals, away goals)

root match result first_half_extratime
Type: object

Required if has_extratime is true

root match result first_half_extratime home
Type: integer

Result after the first half of extra time (i.e. home goals, away goals). Only required if a game goes to extra time.

root match result first_half_extratime away
Type: integer

Result after the first half of extra time (i.e. home goals, away goals). Only required if a game goes to extra time.

root match result second_half_extratime
Type: object

Required if has_extratime is true

root match result second_half_extratime home
Type: integer

Result after the second half of extra time (i.e. home goals, away goals). Only required if a game goes to extra time.

root match result second_half_extratime away
Type: integer

Result after the second half of extra time (i.e. home goals, away goals). Only required if a game goes to extra time.

root match result shootout
Type: object

Required if has_shootout is true

root match result shootout home
Type: integer

Score for the penalty shootout (i.e. home goals, away goals, shootout goals only). Only required if a game goes to shootout.

root match result shootout away
Type: integer

Score for the penalty shootout (i.e. home goals, away goals, shootout goals only). Only required if a game goes to shootout.

root teams
Type: object

root teams home
Type: object

root teams home id
Type: string

Unique identifier for the home or away team

root teams home short_name
Type: string

Short name of the home or away team

root teams home formation
Type: string

Formation label of the team (e.g. '4-4-2')

root teams home players
Type: array of object
No Additional Items

Each item of this array must be:

root teams home players players items
Type: object

root teams home players players items id
Type: string

Unique player identifier

root teams home players players items first_name
Type: string

First name

root teams home players players items last_name
Type: string

Last name

root teams home players players items short_name
Type: string

Short name. For example "Mohamed Salah Hamed Mahrous Ghaly" as "Mo Salah" (or "Mohamed Salah") or "Givanildo Vieira de Sousa" as "Hulk".

root teams home players players items team_id
Type: string

Unique team identifier denoting the team the player plays for

root teams home players players items jersey_number
Type: integer

Jersey number for a player

root teams home players players items is_starter
Type: boolean

Denotes whether a player started the game (true) or not (false)

root teams home players players items has_played
Type: boolean

Denotes whether a player played in game (true) or not (false)

root teams home players players items maiden_name
Type: string

Maiden name. For example, "Smith" for Sophia Wilson.

root teams home players players items position_group
Type: enum (of string)

Position group acronym given according to the CDF-compatible groups

Must be one of:

  • "GK"
  • "DF"
  • "MF"
  • "FW"
  • "SUB"

root teams home players players items position
Type: enum (of string)

Position label acronym per player given according to the CDF-compatible labels

Must be one of:

  • "GK"
  • "LB"
  • "LCB"
  • "CB"
  • "RCB"
  • "RB"
  • "LDM"
  • "CDM"
  • "RDM"
  • "LM"
  • "LCM"
  • "CM"
  • "RCM"
  • "RM"
  • "LAM"
  • "CAM"
  • "RAM"
  • "LW"
  • "LCF"
  • "CF"
  • "RCF"
  • "RW"
  • "SUB"

root teams home players players items is_captain
Type: boolean

Whether the player is a captain (true) or not (false)

root teams home players players items date_of_birth
Type: stringFormat: date

A player's date of birth in YYYY-MM-DD format

Must match regular expression: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

root teams home players players items height
Type: integer

Height of a player in cm

root teams home players players items foot
Type: enum (of string)

A player's dominant foot, which can take the values left, right or both

Must be one of:

  • "left"
  • "right"
  • "both"

root teams home players players items alternative_id
Type: string

Additional identifier(s) of the player

root teams home coaches
Type: array of object
No Additional Items

Each item of this array must be:

root teams home coaches coaches items
Type: object

root teams home coaches coaches items id
Type: string

Unique identifier for a coach

root teams home coaches coaches items first_name
Type: string

First name

root teams home coaches coaches items last_name
Type: string

Last name

root teams home coaches coaches items short_name
Type: string

Short name, a combination of First name and Last name

root officials
Type: array of object
No Additional Items

Each item of this array must be:

root officials officials items
Type: object

root officials officials items id
Type: string

Unique identifier for the official

root officials officials items first_name
Type: string

First name of the official, null if not available

root officials officials items last_name
Type: string

Last name of the official, null if not available

root officials officials items short_name
Type: string

Short name of the official, null if not available

root officials officials items type
Type: enum (of string)

Role of the official (e.g., 'mainreferee', 'assistantreferee', 'fourth_official')

Must be one of:

  • "main_referee"
  • "fourth_official"
  • "assistant_referee"
  • "video_assistant_referee"
  • "assistant_video_assistant_referee"
  • "reserve_assistant_referee"
  • "support_video_assistant_referee"

root events
Type: object

root events goals
Type: array of object or null
No Additional Items

Each item of this array must be:

root events goals goals items
Type: object

root events goals goals items time
Type: stringFormat: date-time

Time a player scored

root events goals goals items period
Type: enum (of string)

Period of the game when the goal was scored

Must be one of:

  • "first_half"
  • "second_half"
  • "first_half_extratime"
  • "second_half_extratime"
  • "shootout"

root events goals goals items team_id
Type: string

Identifier of the team that scored (for own goals this should be identifier of the team that gained a goal)

root events goals goals items player_id
Type: string

Identifier of the player who scored

root events goals goals items assist_id
Type: string or null

Identifier of the player who assisted, if the goal was assisted else leave as null.

root events goals goals items is_own_goal
Type: boolean

Denotes whether it was an own goal (true) or not (false)

root events goals goals items is_penalty
Type: boolean

Denotes whether it was a penalty (true) or not (false)

root events goals goals items score
Type: object

root events goals goals items score home
Type: integer

Team score after the goal

root events goals goals items score away
Type: integer

Team score after the goal

root events substitutions
Type: array of object or null
No Additional Items

Each item of this array must be:

root events substitutions substitutions items
Type: object

root events substitutions substitutions items team_id
Type: string

Identifier of the team that made the substitution

root events substitutions substitutions items in_time
Type: stringFormat: date-time

Time in UTC a player is substituted in

root events substitutions substitutions items period
Type: enum (of string)

Period of the game when the substitution occurred

Must be one of:

  • "first_half"
  • "second_half"
  • "first_half_extratime"
  • "second_half_extratime"

root events substitutions substitutions items in_player_id
Type: string

Unique identifier of the player substituted in

root events substitutions substitutions items out_time
Type: stringFormat: date-time

Time the player was substituted out

root events substitutions substitutions items out_player_id
Type: string

Identifier of the player that is substituted out

root events cards
Type: array of object or null
No Additional Items

Each item of this array must be:

root events cards cards items
Type: object

root events cards cards items team_id
Type: string

Identifier of the team that made the received a card

root events cards cards items time
Type: stringFormat: date-time

Time in UTC a player received a card

root events cards cards items period
Type: enum (of string)

Period of the game when the card was shown

Must be one of:

  • "first_half"
  • "second_half"
  • "first_half_extratime"
  • "second_half_extratime"
  • "shootout"

root events cards cards items player_id
Type: string

Identifier of the player who received a card

root events cards cards items type
Type: enum (of string)

Type of card which can be yellowcard, redcard or secondyellowcard

Must be one of:

  • "yellow_card"
  • "red_card"
  • "second_yellow_card"

root meta
Type: object

root meta vendor
Type: string

Match sheet data vendor name (e.g. "company_a")