NAV

Introduction to the YAML format

This document details the YAML data provided by Cricsheet. It describes the organisation of the file and attempts to give some idea of the possible contents for each field.

The current version number for the YAML format is 0.92, but you can also see the changes that have happened over time in the changelog.

The meta section

meta:
  data_version: 0.92
  created: 2009-08-15
  revision: 1

The meta section contains details related to the data file itself, specifically the version of the data format, the date the file was created, and the revision of the file.

Field Description
data_version string (required) The version of the data format the file contains, in this case 0.91.
created string (required) The date on which the data file was first created. This will be in the format YYYY-MM-DD.
revision integer (required) The revision number for this data version of the file. When first created this will be 1, and it will increment on subsequent revisions.

The info section

info:
  balls_per_over: 6
  city: Chennai
  competition: IPL
  dates:
    - 2008-04-26
  gender: male
  match_type: T20
  outcome:
    by:
      wickets: 9
    winner: Chennai Super Kings
  overs: 20
  player_of_match:
    - JDP Oram
  teams:
    - Chennai Super Kings
    - Kolkata Knight Riders
  toss:
    decision: bat
    winner: Kolkata Knight Riders
  umpires:
    - BF Bowden
    - AV Jayaprakash
  venue: 'MA Chidambaram Stadium, Chepauk'

The info section contains the information on the actual match, such as when and where it was played, any competition it was part of, the type of match etc. Some of the fields are required, whereas some are optional.

Field Description
balls_per_over integer (required) The number of balls expected per over, generally 6.
bowl_out array The balls of any bowl-out used to decide the outcome of the match. If provided this will be an array. More details on the bowl_out field.
city string The city in which the game took place, such as Chennai.
competition string The competition the match was part of. At the moment this value, if provided, will always be Caribbean Premier League, IPL, NatWest T20 Blast, New Zealand Cricket Women's Twenty20, Pakistan Super League, Super Smash, The Hundred Men's Competition, The Hundred Women's Competition, Vitality Blast, Women's Big Bash League, or Women's T20 Challenge, however these should not be regarded as the only possible options.
dates array (required) An array of dates on which the match took place. Matches on a single day will still be an array. More details on the dates field.
gender string (required) The gender of the players who took part on the match. At the moment this value will be either female or male, however these should not be regarded as the only possible options.
match_type string (required) The type of match this data file refers to. Currently the possible values are Test, ODI, T20, IT20 (International T20), ODM (One-day match) or MDM (multi-day match).
match_type_number integer If provided, the number of this particular match type, for example the 2404th Test match.
neutral_venue integer If provided this indicates that the game was played at a venue neither team would regard as a home ground. The value will be 1.
outcome associative array (required) The outcome of the match. It contains information such as which team won the match, whether the game was a draw, tie, or no result, and any margin of victory. More details on the outcome field.
overs integer The number of overs for this type of match, if appropriate. For T20s, this will be 20, and for ODIs/ODMs this will be 50.
player_of_match array If this field appears then it will be an array of the names of any players who were adjudged to be the player of the match.
players associative array (required) A list of players officially involved in the match for each team. More details on the players field.
registry associative array (required) Mappings of names to ids, currently used for mapping the names of people involved in the match to unique identifiers for those people. More details on the registry field.
supersubs associative array (required) Any supersubs used by each team in the match. More details on the supersubs field
teams array (required) The names of the teams who played in the match.
toss associative array (required) The winner, and decision, from the toss. More details on the toss field
umpires array If this field appears then it will be an array of the names of any umpires, and there will be at least 2 entries.
venue string The venue in which the game took place, such as Old Trafford.

bowl_out

bowl_out:
  - bowler: JE Taylor
    outcome: miss
  - bowler: JE Taylor
    outcome: miss
  - bowler: SE Bond
    outcome: hit
  - bowler: SE Bond
    outcome: hit

An array containing an entry for each delivery attempted in the bowl-out.

Field Description
bowler string (required) The name of the bowler who bowled the ball.
outcome string (required) The outcome of the bowl-out ball, either hit, or miss.

dates

A match played on a single day, such as an ODI.

dates:
  - 2008-04-26

A match played on multiple days, such as a Test match.

dates:
  - 2011-01-02
  - 2011-01-03
  - 2011-01-04
  - 2011-01-05
  - 2011-01-06

dates is always an array, regardless of the number of days on which the match took place. Each date will be in the format YYYY-MM-DD.

outcome

A match where India won by a number of wickets.

outcome:
  by:
    wickets: 9
  winner: Chennai Super Kings

A match where Ireland won by a number of runs.

outcome:
  by:
    runs: 73
  winner: Ireland

A match where Australia won by an innings and a number of runs.

outcome:
  winner: Australia
  by:
    innings: 1
    runs: 48

A match that ended in a tie, with England winning the super over.

outcome:
  result: tie
  eliminator: England

A match that ended in with no result.

outcome:
  result: no result

A match won by Hong Kong, by a number of runs, under the Duckworth Lewis method.

outcome:
  by:
    runs: 39
  method: D/L
  winner: Hong Kong

A match that ended in a tie, with New Zealand winning the bowl out.

outcome:
  bowl_out: New Zealand
  result: tie

The outcome is an associative array which contains information such as which team won the match, whether the game was a draw, tie, or no result, and any margin of victory.

Field Description
by associative array Information on how much the winning team, if there was one, won by. More details on the by field.
bowl_out string The team name of the winner of any bowl-out used to decide a tie in a T20 match.
eliminator string The team name of the winner of any elimination super-over used to decide a tie in a T20 match.
method string Any method used to determine the winner where a match has been curtailed for some reason, or decided in an "unusual" manner. Currently the only values this will contain are D/L (when a match uses the Duckworth Lewis, and possibly Stern, method), VJD (when a match uses the Jayadevan system), Awarded (when a match is awarded to a team), 1st innings score (when the team with the highest 1st inning score is determined to have won the match), or Lost fewer wickets (when losing fewer wickets than the opponent determined the winner).
result string The result of the match if the match was not won by one of the teams. Currently the possible values are draw, no result, or tie.
winner string If a team won the match then this will be the name of the winning team.

by

Information on how much the winning team, if there was one, won by.

Field Description
innings integer If the match was won by an innings and something then this entry will appear with a value of 1.
runs integer If the match was won by a number of runs, or an innings and a number of runs, then this will contain the runs.
wickets integer If the match was won by a number of wickets, then this will contain the number of wickets.

players

The players involved in a match between Australia and Sri Lanka.

players:
  Australia:
  - M Klinger
  - AJ Finch
  - BR Dunk
  - MC Henriques
  - TM Head
  - AJ Turner
  - JP Faulkner
  - TD Paine
  - PJ Cummins
  - AJ Tye
  - JA Richardson
  Sri Lanka:
  - N Dickwella
  - WU Tharanga
  - EMDY Munaweera
  - BKG Mendis
  - DAS Gunaratne
  - TAM Siriwardana
  - CK Kapugedera
  - S Prasanna
  - KMDN Kulasekara
  - SL Malinga
  - JRMVB Sanjaya

The players section lists, for each team, the players officially involved in the match, including the starting eleven, and any supersubs, concussion substitutes, covid replacements, or other replacements. The section itself is an associative array containing the names of the teams as the key, and each value being an array of the names of the players for that team.

registry

The players and officials involved in a match.

registry:
  people:
    AJ Finch: b8d490fd
    AJ Turner: ff1e12a0
    AJ Tye: 7c7d63a2
    BKG Mendis: 5d1e7582
    BR Dunk: 272d796e
    CK Kapugedera: cfad138c
    DAS Gunaratne: 770494eb
    EMDY Munaweera: 5a22d91c
    JA Richardson: 1ee08e9a
    JJ Crowe: 2e760301
    JP Faulkner: 808f425a
    JRMVB Sanjaya: 530b20e3
    KMDN Kulasekara: 469ea22b
    M Klinger: b970a03f
    MC Henriques: 32198ae0
    MW Graham-Smith: 18aca3ce
    N Dickwella: 45963d9e
    P Wilson: 68304a36
    PJ Cummins: ded9240e
    S Prasanna: f78e7113
    SD Fry: 6b725ed1
    SJ Nogajski: 9b3f9323
    SL Malinga: a12e1d51
    TAM Siriwardana: bf7842c9
    TD Paine: 5748e866
    TM Head: 12b610c2
    WU Tharanga: 7ed9fd56

The registry entry contains a single entry (people) which provides a mapping between the names used for people mentioned in the data file and the stable unique identifier used for those people (regardless of the name the person appeared in the match under). The same person will always have the same identifier across all matches. The identifier is always an 8 character string consisting of digits or the lowercase letters a to f.

A name in this section will always be used to refer to the person in the data file, whether as a batter, non-striker, bowler, fielder, official, or in some other capacity.

supersubs

A match where only a single team (Australia) used a supersub.

supersubs:
  Australia: JR Hopes

A match where both teams used a supersub.

supersubs:
  Adelaide Strikers: MW Short
  Hobart Hurricanes: M Wright

The data for this field is an associative array which details any supersubs used by each team in the match. The keys for the entry will be the names of any teams that used a super-sub, while the values will be the names of the super-subs for those teams.

toss

Namibia won the toss and decided to bat.

toss:
  decision: bat
  winner: Namibia

Netherlands won the toss and decided to field.

toss:
  decision: field
  winner: Netherlands

Somerset decided to field as the away team in a County Championship match, and thus the toss was uncontested.

toss:
  decision: field
  uncontested: yes
  winner: Somerset
}

The result of the toss before the match.

Field Description
uncontested string If this is provided the value will be yes. This indicates that the toss was not contested, and that instead it was automatically awarded to the winning team with the specified decision. Generally this is for County Championship matches from 2016 to 2019.
decision string (required) The decision made by the team winning the toss. This will be either bat or field.
winner string (required) The name of the team which won the toss.

The innings section

The simple example here shows a small part of both innings of a one-day match. The first innings shows Ireland facing 2 balls, with William Porterfield batting, while the second innings shows 1 ball of the Indian reply.

innings:
  - 1st innings:
      team: Ireland
      deliveries:
        - 0.1:
            batsman: WTS Porterfield
            bowler: IK Pathan
            extras:
              wides: 1
            non_striker: JP Bray
            runs:
              batsman: 0
              extras: 1
              total: 1
        - 0.2:
            batsman: WTS Porterfield
            bowler: IK Pathan
            non_striker: JP Bray
            runs:
              batsman: 0
              extras: 0
              total: 0
  - 2nd innings:
      team: India
      deliveries:
        - 0.1:
            batsman: G Gambhir
            bowler: WB Rankin
            non_striker: RG Sharma
            runs:
              batsman: 4
              extras: 0
              total: 4

The innings section contains an array of associative arrays, with each entry representing an innings within the game, in the order in which they took place. Each associative array has a single key (such as 1st innings) which specifies the “name” of the innings and then the value is a further associative array with the details of that innings, such as the team batting, and the deliveries faced within the innings.

Field Description
team string (required) The team which is batting must be specified in the data for the innings. This will be one of the two teams mentioned in the teams section in info for the match.
deliveries array An array containing an entry for each delivery in the innings. Each entry is an associative array (containing a single entry). There is a separate section covering the details on the delivery data. This will always be provided, unless the inning is forfeited.
absent_hurt array If this is provided it will contain an array of the names of players who did not take part in the innings due to being absent hurt.
penalty_runs associative array If this field is provided it will be a associative array which details any penalty runs added either before or after the innings. More details on the penalty_runs field.
declared string If this is provided the value will be yes. This indicates that the innings was declared.
forfeited string If this is provided the value will be yes. This indicates that the innings was forfeited by the batting team.

penalty_runs

Penalty runs added before the start of the innings. In this case the batting team start with 5 runs.

penalty_runs:
  pre: 5

Penalty runs added after the end of the innings. In this case the batting team has 6 runs added to their total.

penalty_runs:
  post: 6

Details on any penalty runs applied to an innings either before it begins or after it finishes. Penalty runs applied on particular deliveries will be indicated on the deliveries themselves rather than here.

Field Description
pre integer The number of penalty runs applied to the innings before it begins.
post integer The number of penalty runs applied to the innings after it finishes.

Delivery data

An example delivery (the 2nd in the 8th over of the innings) in which Nadine de Klerk bowled to Nahida Khan, with Umaima Sohail at the non-striker's end. Khan scored a single run but was then run-out going for the 2nd run. The fielders involved in the run-out are not known.

- 7.2:
    batsman: Nahida Khan
    bowler: N de Klerk
    non_striker: Umaima Sohail
    runs:
      batsman: 1
      extras: 0
      total: 1
    wicket:
      player_out: Nahida Khan
      kind: run out

An example delivery (the 1st in the 3rd over of the innings) in which Ross ter Braak bowled to Tim Seifert, with Katene Clarke at the non-striker's end. Ter Braak bowled a wide.

- 2.1:
    batsman: TL Seifert
    bowler: RM ter Braak
    non_striker: KD Clarke
    extras:
      wides: 1
    runs:
      batsman: 0
      extras: 1
      total: 1

Each individual delivery is a key/value pair, where the single key (such as 23.5) specifies the particular ball (in that case the 5th ball of the 24th over), and the value is a further associative array with the details of that delivery.

Field Description
batsman string (required) The name of the batter who faced the delivery.
bowler string (required) The name of the bowler of the delivery.
non_striker string (required) The name of the non-striker during the delivery.
runs associative array (required) The runs scored on the delivery, whether by the batter or as extras. Also covers the possibility that a 4 or 6 was not an actual boundary should, for example if the batsmen ran a 4. More details on the runs field.
wicket associative array, or array The details of any wickets that took place during the delivery, including the method of dismissal, the name of the dismissed player, and any fielders involved in the dismissal. More details on the wicket field.
extras associative array The types and number of extras conceded on the delivery. More details on the extras field.
replacements associative array Any player replacements that happened before this delivery took place, for example when a bowler is replaced during an over due to injury. More details on the replacements field.

runs

A delivery where the batter scored 4 runs, and no extras were scored. As non_boundary is not specified this was a boundary.

runs:
  batsman: 4
  extras: 0
  total: 4

A delivery where the batter didn't score, but some extras occurred.

runs:
  batsman: 0
  extras: 1
  total: 1

A delivery where the batter scored 2 runs, and an extra occurred.

runs:
  batsman: 2
  extras: 1
  total: 3

A delivery where the batter scored 4 runs, but it wasn't a boundary.

runs:
  batsman: 4
  extras: 0
  non_boundary: 1
  total: 4

Details on how the runs scored on the delivery should be assigned. Runs scored by the batter, and the total extras conceded, are shown individually along with the total of both. It may also contain a non_boundary entry to indicate that any 4 or 6 should not be regarded as a boundary.

Field Description
batsman integer (required) The total number of runs scored by the batter off the ball. If the batter failed to score this will show 0.
extras integer (required) The total number of runs conceded via extras off the ball. If no extras were conceded this will show 0.
non_boundary integer If this is listed against the delivery then the value will be 1. This indicates that the 4 or 6 scored was not via an actual boundary, for example it was all run, or overthrows.
total integer (required) The total number of runs scored off this delivery. If no runs were scored from the delivery then this will display 0.

wicket

Ahmed Shehzad is out bowled.

wicket:
  kind: bowled
  player_out: Ahmed Shehzad

Azhar Ali is out caught.

wicket:
  fielders:
    - AJ Doolan
  kind: caught
  player_out: Azhar Ali

Stuart Broad is out caught and bowled.

wicket:
  kind: caught and bowled
  player_out: SCJ Broad

Mohammad Hafeez is out leg before wicket (lbw).

wicket:
  kind: lbw
  player_out: Mohammad Hafeez

David Warner is out stumped, by Sarfraz Ahmed.

wicket:
  fielders:
    - Sarfraz Ahmed
  kind: stumped
  player_out: DA Warner

Alex Doolan is run out, by Rahat Ali.

wicket:
  fielders:
    - Rahat Ali
  kind: run out
  player_out: AJ Doolan

Salman Butt is out retired hurt.

wicket:
  kind: retired hurt
  player_out: Salman Butt

Swapnil Asnodkar is out hit wicket.

wicket:
  kind: hit wicket
  player_out: SA Asnodkar

Diego Lord is out obstructing the field.

wicket:
  kind: obstructing the field
  player_out: DM Lord

Zhang Yu Fei is out handled the ball.

wicket:
  player_out: Zhang Yu Fei
  kind: handled the ball

Two wickets listed on the same delivery, one played stumped, and the other played retired hurt.

wicket:
  - fielders:
      - BJ Haddin
    kind: stumped
    player_out: Sarfraz Ahmed
  - kind: retired hurt
    player_out: Zulfiqar Babar

If a wicket occurs on the delivery then this entry will provide details on the wicket, such as which player is out, what type of dismissal it was, and any fielders who were involved.

In the very unlikely case that a wicket falls and another player retires hurt on the same ball, this will be an array containing an entry for each wicket. At the moment we only have a single match that meets this criteria, the 1st Test between Pakistan and Australia in 2014 where Sarfaraz Ahmed was stumped, the tea interval was taken, and Zulfiqar Babar retired hurt during it (effectively meaning he had retired on the same delivery).

Field Description
fielders array If we know them this will contain the names of any fielders who were involved in the dismissal. Generally this will be the player (or players) who took a catch, or were involved in a run-out.
kind string (required) The kind of dismissal that took place. This will be one of bowled, caught, caught and bowled, lbw, stumped, run out, retired hurt, hit wicket, obstructing the field, hit the ball twice, handled the ball, or timed out.
player_out string (required) The name of the player who was dismissed.

extras

Byes

extras:
  byes: 1

Leg-byes

extras:
  legbyes: 2

No-balls

extras:
  noballs: 1

Penalty runs

extras:
  penalty: 5

Wides

extras:
  wides: 1

If extras were conceded on a delivery then this field will indicate how the extras came about. The value of the field will be an associative array with byes, legbyes, noballs, penalty, and wides as the possible keys, and the associated value for each will be the number of runs from each.

Field Description
byes integer The number of byes conceded on the delivery.
legbyes integer The number of legbyes conceded on the delivery.
noballs integer The number of no-balls conceded on the delivery.
penalty integer The number of penalty runs conceded on the delivery.
wides integer The number of wides conceded on the delivery.

replacements

Kyle Abbott takes over as the bowler due to an injury to the existing bowler.

replacements:
  role:
    - in: KJ Abbott
      reason: injury
      role: bowler

Sam Whiteman (of Perth Scorchers) leaves the match due to a concussion and is replaced permanently by Cameron Bancroft,

replacements:
  match:
    - in: CT Bancroft
      out: SM Whiteman
      reason: concussion_substitute
      team: Perth Scorchers

This field is an associative array providing the details of any replacements that happened before this delivery took place. It shows who was substituted in and out, why, and which team it was for, as well as what type of replacement it is, match or role. These different types are grouped together within the replacements section, and it’s possible that a delivery could have both types.

Field Description
match array Match replacements detail players who replace others and take their place in the match. More details on the match field.
role array Role replacements are occasions where a player replaces another as a bowler or batter (but does not take their place in the match). More details on the role field.

match

James Marshall replaces Jeetan Patel for New Zealand as a supersub.

replacements:
  match:
    - in: JAH Marshall
      out: JS Patel
      reason: supersub
      team: New Zealand

Chris Tremain replaces Daniel Sams for Sydney Thunder as a concussion substitute.

replacements:
  match:
    - in: CP Tremain
      out: DR Sams
      team: Sydney Thunder
      reason: concussion_substitute

Jack Brooks replaces Lewis Gregory for Somerset as a covid replacement.

replacements:
  match:
    - in: JA Brooks
      out: L Gregory
      team: Somerset
      reason: covid_replacement

Graham Clarke replaces Ben Stokes due to Stokes receiving a callup to the national team.

replacements:
  match:
  - in: G Clark
    out: BA Stokes
    team: Durham
    reason: national_callup

Tim Murtagh replaces Ethan Bamber after Murtagh was released from his national commitments with Ireland.

replacements:
  match:
  - in: TJ Murtagh
    out: ER Bamber
    team: Middlesex
    reason: national_release

match replacements involve one player completely replacing another in a match, such as a occurs when a concussion substitution takes places.

Field Description
in string (required) The name of the player who came in as part of the replacement. If the replacement is a supersub replacement then this value will match the player listed as a supersub for the team.
out string (required) The name of the player who went out as part of the replacement.
reason string (required) The reason for the replacement. This must be one of concussion_substitute, covid_replacement, national_callup, national_release, supersub, or unknown.
team string (required) The name of the team the substitution was for.

role

Alex Thomson replaces George Scrimshaw as the bowler, after Scrimshaw is excluded for bowling excessive short-pitched deliveries.

replacements:
  role:
    - in: AT Thomson
      out: GLS Scrimshaw
      reason: excluded - excessive short-pitched deliveries
      role: bowler

Rob Taylor replaces Nathan Buck as the bowler, after Buck is excluded for bowling multiple high-pitched deliveries.

replacements:
  role:
    - in: RML Taylor
      out: NL Buck
      reason: excluded - high full pitched balls
      role: bowler

Steve Finn replaces the existing (un-named) bowler who is excluded for having run on the pitch.

replacements:
  role:
    - in: ST Finn
      reason: 'excluded - running on the pitch'
      role: bowler

George Dockrell comes in as bowler, replacing the injured David Delany.

replacements:
  role:
    - in: GH Dockrell
      out: DC Delany
      reason: injury
      role: bowler

Ravindra Jadeja replaces the (un-named) bowler after it is determined that the existing bowler has bowled too many overs. This actually happened in an ODI between Australia and India in 2012.

replacements:
  role:
    - in: RA Jadeja
      reason: too many overs
      role: bowler

Charles Perchard replaces Anthony Hawkins-Kay as bowler for an unknown reason.

replacements:
  role:
    - in: CW Perchard
      out: AW Hawkins-Kay
      reason: unknown
      role: bowler

role replacements involve one player replacing another in a role, such as a bowler being replaced due to being injured.

Field Description
in string (required) The name of the player who came in as part of the replacement.
out string The name of the player who went out as part of the replacement. This may not be provided for a bowler replacement.
reason string (required) The reason for the replacement. This must be one of excluded - excessive short-pitched deliveries, excluded - high full pitched balls, excluded - running on the pitch, injury, too many overs, or unknown.
role string (required) The role of the player being replaced, currently either batter, or bowler.

Changelog

Version 0.92

Version 0.91

Version 0.9

Version 0.8

Version 0.7

Version 0.6

Version 0.5

Version 0.4

Version 0.3