There are nine primary entities that you will often come across in the Toornament API and 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. Some competitors are eliminated along the way and, at the end, a single competitor is declared winner.
In Toornament, competitors are defined as participants. The predefined path of matches is defined as the tournament’s structure and is composed of stages, groups, rounds, brackets, rankings and matches. A match can be further detailed with subsets of a match usually called games or match games.
The participant refers to the attendance of a competitor in a single tournament. A participant is tied to its tournament. In the case of one competitor taking part in several tournaments, he will 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 rank of a competitor in a ranking.
A stage is a major step in a tournament. Its purpose is to arrange and organize the competition for some of the participants following a specific and standardized method. The method is defined by the type of stage.
There are currently ten different types of stage supported on Toornament: single elimination, double elimination, gauntlet, round-robin groups, bracket groups, league and swiss system. And also three Free-for-all ones: simple, single elimination and bracket groups.
Each has its own method to arrange matches between participants. Depending on its type, a stage may involve sub-elements of the structure: groups, rounds, matches, brackets and rankings.
A group represents a portion of a stage that usually involves only a subset of the participants. Most of the time groups can be played simultaneously because they involve different participants. However, in some cases, a group may have to wait the outcome of another group in order to receive additional participants and continue.
Some stage types do not require groups. In such case, a single group is still created as a placeholder to comply with the structure of the other stages.
A round represents a small step inside a group in which all participants play no more than one match. The purpose of a round is to provide a step in which all participants can, if necessary, play simultaneously.
A bracket represents a type of competition in which the outcome of a match (a win or a loss) determines where the participants go next. Matches in a bracket are therefore connected between them and are often represented as a tree.
A ranking represents a type of competition in which the outcome of a match rewards the participants with points. These points are then used to calculate a ranking. Once the stage or the group is completed, the ranking is then used to determine the final standing of the participants in the stage.
A match is a small structured form of play involving one or more participants. These participants play against each others following a match format and possibly smaller steps of play (such as games or match games). At the end, an outcome is defined by the match format.
Depending on the number of participants involved in the match, the outcome is calculated differently. When a match only involves two participants, it is typed as duel and the result is described by a win, a draw or a loss. When a match involves more than two participants, it is typed as ffa and the result is described by a ranking.
A match contains match opponents. These opponents act like slots that expect to receive a participant at some point in the tournament. A match opponent contains a number and the match-related data of a participant such as his score, his result and other game information.
A match game is a subset of a match that describes part of a match. It is usually where you find discipline-specific information such as maps or modes.
A match game contains match game opponents. They share the same opponent number as in the match so they do not need to contain a participant. They also contain match-game-related data such as score and result and discipline-specific information such as characters.