Core Concepts

Data model

There are nine major "entities" that you'll often come across in the Toornament API and when dealing with competition data in general. While there are also several other secondary entities, we encourage you to check these entities in detail to understand how they interact with each others.


A tournament is a competition involving a given set of competitors. These competitors play against each others following a predefined path of matches. Some competitors may be eliminated along the way, but at the end, a single competitor is declared the winner.

In Toornament, competitors are defined as the Participants and the predefined path of matches as the tournament's "structure". This structure is composed of major steps called Stages.


The participant refers to the attendance of one competitor in a tournament. A participant is tied to its tournament. In the case of one competitor taking part in several tournaments, he will then be represented by one distinctive participant for each tournament.

The participant is referenced each time there is a need to clearly identify a competitor in the tournament. For example, to identify who is playing a match or to identify the ranking of a competitor in a swiss ranking.


A stage is a major step in a tournament. Its purpose is to arrange and organize the competition for the participants following a specific and standardized method. This method is identified by the "type of the stage".

There are currently six different types of stage supported on Toornament: single elimination, double elimination, groups, bracket groups, league and swiss system.

Each has its own method to arrange and display matches. For example, a "groups" stage will provide a list of groups. Each group will contain a ranking, a certain number of rounds, and matches between all participants of a group.

Although each stage may have its own custom data such as a ranking or a bracket, there is a common structure among all stages.

  • Each Stage is composed of Groups,
  • each Group is composed of Rounds and
  • each Round is composed of Matches


A group represents a portion of a stage that involves only a sub-set of the participants, or sometimes involves different processes. A group does not represent a whole step in the tournament. For example, league stage divisions are treated as groups. Each division has its own participants, its own ranking and its own matches which do not involve participants from another division.

A group is composed of Rounds that represent smaller steps inside the group. Although multiple groups may have the same number of rounds, they do not share the same rounds. A single group may also contain specific settings. They override the settings provided in the stage and allows the customization on a group-level.

Note: In some cases, a stage may not need the use of groups. In such case, a single group is still created as a placeholder to comply with the structure of the other stages. Toornament will then display a placeholder status indicator.


A round represents a small step inside a group in which all participants play one match only. The purpose of a round is to provide a step in which all participants can, if necessary, play simultaneously. For example, in a single elimination bracket, the quarter finals are treated as a round because all four matches can be played simultaneously.

A round contains therefore a list of Matches. It also contain specific settings that only apply to a single round. They override the settings provided in the stage or in the group, and allows the customization on a round-level.


A match is a small structured form of play involving one or more competitors. These competitors play against each others following a match format and possibly smaller steps of play. At the end, an outcome is defined depending on the match format.

  • When only two competitors are involved, the match is typed as "duel". The outcome is a win, a draw or a loss.
  • When more than two competitors are involved, the match is typed as "ffa". The outcome is a ranking between all competitors.

In Toornament, participants are defined as the Match Opponents and the sub-steps of play are defined as Games. The match format sets up how the games and opponents interact during the match.

Match Opponent

A match opponent represents an expected competitor in a match. It should, at some point in the tournament, be associated to a Participant to clearly identify who is playing the match. But it does not have to. For example, in a single elimination bracket, when the semi-finals haven't yet been played, it isn't possible to know who is playing the finals, but we can already identify that the final will involve two defined opponents.

An opponent is tied to its match and is different for each match. It is identified by a "number" relative to the match, such as opponent 1 and opponent 2. This number is thereafter used as identifier in all Games.

When possible, the opponent will contain a reference to a participant of the tournament. It'll also contain additional information related to the match such as the result or the score.


A game is a sub-set of a match. It may represent multiple steps that function alike, or multiple steps with variations in the rules (such as a different map, a different mod, ...)

A game highly depends on the match format that describes how games must be chained but it should not depend on it. It should only care about the small step without knowing if additional games are required or not.

The game uses its own Game Opponents to describes its competitors.

Game Opponent

A game opponent represents the match opponent in a game. It shares the same opponent number as in the match but it contains information related to a single game (such as a score, a hero choice, ...).