Round Robin Tally Policy
The Round Robin Tally Policy controls how participants are ranked within round robin groups, including tiebreaking procedures, head-to-head calculations, and group order determination.
The ordering itself is the standings engine's, shared with season tables and the competition leaderboard: see Standings, including which sports' rules it can express.
This policy's shape is the RoundRobinTallyPolicy definition in tournament.schema.json (under PolicyDefinitions), open by decision, like its TypeScript type: it lists the members the tally reads, and validateTallyPolicy checks their values where a policy is saved. Policies are stored in each element's first-class appliedPolicies attribute (the appliedPolicies extension on older records).
Overview
Round robin groups require sophisticated tiebreaking rules to determine final standings when participants have equal records. The tally policy provides:
- Flexible tiebreaking through configurable
tallyDirectives - Head-to-head comparisons between tied participants
- Percentage calculations (matches, sets, games, points)
- Statistical tracking (wins, losses, defaults, retirements)
- Threshold-based rules via maxParticipants attribute
- Composite scoring through GEMscore
- Group totals for percentage calculations
Default Behavior
When no custom tally policy is specified, the system applies a comprehensive default tiebreaking procedure that follows widely-accepted tournament standards.
Standard Tiebreaking Sequence
The default tally policy implements the following hierarchy:
- Primary criterion: Participants grouped by
matchUpsWon - Head-to-head comparison: When participants are tied, their direct results against each other are evaluated
- Percentage-based tiebreakers: Match, set, game, and point percentages (in order)
- Scope escalation: First evaluate all group matches, then recalculate among tied participants only
Algorithm Overview
The tiebreaking algorithm works as follows:
- Group participants by the primary attribute (default:
matchUpsWon) - For each tied group:
- If only 1 participant: resolved (no tie)
- If exactly 2 participants: compare head-to-head record
- If 3+ participants: apply
tallyDirectivessequence
- Apply directives until ties are broken or all directives exhausted
- Recursive separation: As each directive separates participants, smaller groups are formed and process repeats
Head-to-Head Logic
When 2 participants are tied:
- Their win-loss record across every meeting
- More wins over the other places higher
- If the record is level, or they didn't play: move to next directive
When 3+ participants are tied:
- Calculate statistics among only the tied participants
- Look for clear separation
- If circular tie (A>B>C>A): move to next directive
Head-to-head is applied BEFORE tallyDirectives unless explicitly disabled via headToHead: { disabled: true }.
Head-to-head reads the record between the two participants across every meeting: the one with more wins over the
other is placed first. A level record (1-1 in a double round robin) or no meeting does not separate them, and the
tallyDirectives decide. The order in which meetings are listed never matters. (Before the standings engine, any one
victory decided, so a pair that split two meetings was decided by whichever meeting was found first.)
A directive's disableHeadToHead (skip head-to-head when sorting the sets that directive splits off) takes effect only
when the policy also declares a headToHead object.
Implementation Details
Calculated Attributes
For each participant, the following attributes are calculated from match results:
Match-level:
matchUpsWon- Total matches wonmatchUpsLost- Total matches lostmatchUpsCancelled- Matches that were cancelled/abandonedmatchUpsPct- Win percentage:matchUpsWon / (matchUpsWon + matchUpsLost)
Set-level:
setsWon- Total sets wonsetsLost- Total sets lostsetsPct- Win percentage:setsWon / (setsWon + setsLost)
Game-level:
gamesWon- Total games wongamesLost- Total games lostgamesPct- Win percentage:gamesWon / (gamesWon + gamesLost)
Point-level:
pointsWon- Total points wonpointsLost- Total points lostpointsPct- Win percentage:pointsWon / (pointsWon + pointsLost)
Incomplete matches:
defaults- Number of times participant defaultedwalkovers- Number of times participant walked overretirements- Number of times participant retiredallDefaults- Total of all exit statuses (defaults + walkovers + retirements)
TEAM events (tieMatchUps):
tieMatchUpsWon- Individual matches wontieMatchUpsLost- Individual matches losttieSinglesWon- Singles matches wontieSinglesLost- Singles matches losttieDoublesWon- Doubles matches wontieDoublesLost- Doubles matches lost
Final result:
groupOrder- Final placement (1-based, lower is better)GEMscore- Composite score (if configured)
Calculation Scoping
Global scope (idsFilter: false):
// Calculate from ALL group matches
matchUpsPct = matchUpsWon / (matchUpsWon + matchUpsLost);
Filtered scope (idsFilter: true):
// Calculate from ONLY matches among tied participants
// Example: If A, B, C are tied, only count A-B, A-C, B-C matches
matchUpsPct = matchUpsWon_amongTied / (matchUpsWon_amongTied + matchUpsLost_amongTied);
Group Totals
Participant-based (groupTotals: false - default):
gamesPct = gamesWon / (gamesWon + gamesLost);
// Each participant's denominator is their own games
// Sum of all gamesPct can exceed 1.0
Group-based (groupTotals: true):
totalGroupGames = sum of all gamesWon by all participants
gamesPct = gamesWon / totalGroupGames
// Sum of all gamesPct = 1.0
Directive Processing
Directives are applied sequentially:
for (const directive of tallyDirectives) {
// 1. Check maxParticipants threshold
if (directive.maxParticipants && tiedCount > directive.maxParticipants) {
continue; // Skip this directive
}
// 2. Calculate attribute (with idsFilter if specified)
const values = calculateAttribute(directive, tiedParticipants);
// 3. Sort (reversed if specified)
const sorted = directive.reversed
? sortAscending(values) // Least to greatest
: sortDescending(values); // Greatest to least
// 4. Separate into groups by value
const groups = groupByValue(sorted);
// 5. Recursively process each group
groups.forEach((group) => {
if (group.length > 1) {
// Still tied, continue with next directive
} else {
// Resolved! Assign groupOrder
}
});
}
Precision in Percentages
Percentages are calculated with configurable precision:
const precision = Math.pow(10, tallyPolicy?.precision || 3);
// precision: 3 → 1000 → 0.667
// precision: 5 → 100000 → 0.66667
matchUpsPct = Math.round((matchUpsWon / matchUpsTotal) * precision) / precision;
Policy Structure
type RoundRobinTallyPolicy = {
policyName?: string;
// Initial grouping attribute
groupOrderKey?:
| 'matchUpsWon'
| 'tieMatchUpsWon'
| 'tieSinglesWon'
| 'tieDoublesWon'
| 'pointsWon'
| 'gamesWon'
| 'setsWon'
| 'gamesPct'
| 'setsPct'
| 'pointsPct'
| 'matchUpsPct';
// Tiebreaking sequence
tallyDirectives?: Array<{
attribute: string; // Which statistic to compare
idsFilter?: boolean; // Compare only tied participants
reversed?: boolean; // Least-to-greatest instead of greatest-to-least
maxParticipants?: number; // Only apply if # tied <= threshold
groupTotals?: boolean; // Use group totals for percentages
disableHeadToHead?: boolean; // Skip head-to-head for this directive
}>;
// Head-to-head configuration
headToHead?: {
disabled?: boolean; // Skip head-to-head entirely
};
// Percentage calculation options
groupTotalGamesPlayed?: boolean; // Use all group games for gamesPct
groupTotalSetsPlayed?: boolean; // Use all group sets for setsPct
precision?: number; // Decimal precision (default: 3)
// Disqualification rules
disqualifyDefaults?: boolean; // Push defaulting participants to bottom
disqualifyWalkovers?: boolean; // Push walkover participants to bottom
// Exclude specific match statuses
excludeMatchUpStatuses?: string[]; // e.g., ['ABANDONED', 'INCOMPLETE']
// Credit for incomplete matches
setsCreditForDefaults?: boolean;
setsCreditForWalkovers?: boolean;
setsCreditForRetirements?: boolean;
gamesCreditForDefaults?: boolean;
gamesCreditForWalkovers?: boolean;
gamesCreditForRetirements?: boolean;
gamesCreditForTiebreakSets?: boolean; // Default: true
// Composite score attributes
GEMscore?: string[]; // Attributes to include in GEMscore calculation
};
Built-in Policies
Default Tally Policy
Standard tiebreaking procedure:
import { fixtures } from 'tods-competition-factory';
const { POLICY_ROUND_ROBIN_TALLY_DEFAULT } = fixtures.policies;
const policy = POLICY_ROUND_ROBIN_TALLY_DEFAULT[POLICY_TYPE_ROUND_ROBIN_TALLY];
// {
// policyName: 'Default Round Robin Tally',
// groupOrderKey: 'matchUpsWon',
// tallyDirectives: [
// { attribute: 'matchUpsPct', idsFilter: false },
// { attribute: 'allDefaults', reversed: true, idsFilter: false },
// { attribute: 'defaults', reversed: true, idsFilter: false },
// { attribute: 'walkovers', reversed: true, idsFilter: false },
// { attribute: 'retirements', reversed: true, idsFilter: false },
// { attribute: 'setsPct', idsFilter: false },
// { attribute: 'gamesPct', idsFilter: false },
// { attribute: 'pointsPct', idsFilter: false },
// { attribute: 'matchUpsPct', idsFilter: true },
// { attribute: 'setsPct', idsFilter: true },
// { attribute: 'gamesPct', idsFilter: true },
// { attribute: 'pointsPct', idsFilter: true },
// ],
// }
Tiebreaking sequence:
- Match win percentage (all group matches)
- Fewest all defaults (any exit status)
- Fewest defaults
- Fewest walkovers
- Fewest retirements
- Set win percentage (all group matches)
- Game win percentage (all group matches)
- Point win percentage (all group matches)
- Match win percentage (among tied teams only)
- Set win percentage (among tied teams only)
- Game win percentage (among tied teams only)
- Point win percentage (among tied teams only)
JTT Tally Policy
Junior Team Tennis format:
import { fixtures } from 'tods-competition-factory';
const { POLICY_ROUND_ROBIN_TALLY_JTT } = fixtures.policies;
// {
// policyName: 'JTT Round Robin Tally',
// groupOrderKey: 'gamesWon',
// tallyDirectives: [
// { attribute: 'matchUpsPct', idsFilter: true },
// { attribute: 'gamesWon', idsFilter: false },
// { attribute: 'matchUpsWon', idsFilter: false },
// { attribute: 'tieMatchUpsWon', idsFilter: false },
// { attribute: 'setsWon', idsFilter: false },
// ],
// }
Key features:
- Primary criterion: Most games won
- Head-to-head first: matchUpsPct with idsFilter: true
- Designed for team tennis where games won is primary metric
TOC Tally Policy
Tournament of Champions format:
import { fixtures } from 'tods-competition-factory';
const { POLICY_ROUND_ROBIN_TALLY_TOC } = fixtures.policies;
// {
// policyName: 'TOC Round Robin Tally',
// groupOrderKey: 'matchUpsPct',
// tallyDirectives: [
// { attribute: 'matchUpsPct', idsFilter: true, maxParticipants: 2 },
// { attribute: 'gamesPct', idsFilter: false },
// { attribute: 'gamesWon', idsFilter: false },
// { attribute: 'gamesLost', idsFilter: false, reversed: true },
// ],
// }
Key features:
- maxParticipants: 2 on head-to-head (only if 2 teams tied)
- Games percentage for 3+ team ties
- Fewest games lost as final tiebreaker
USTA League Championship Policy
POLICY_ROUND_ROBIN_TALLY_USTA_LEAGUE: the USTA League championship tie procedure as copied into section regulations
(USTA/Midwest Section 2026, Combo section M):
- the most individual matches (lines) won (
tieMatchUpsWon); - then the winner of the head-to-head match;
- then the fewest sets lost, then the fewest games lost;
- then the Midwest committee method: the fewest sets lost in the head-to-head match, then the fewest games lost in it,
then a coin toss (
terminal: 'LOT').
An individual default counts 6-0, 6-0 for the receiver, and a match tie-break counts as one set and one game. A section that varies the order needs its own policy.
FIBA Policy
POLICY_ROUND_ROBIN_TALLY_FIBA: FIBA Official Basketball Rules 2026, Appendix D:
resultPoints: 2 for a win, 1 for a loss including by default, 0 for a loss by forfeit (a forfeit mapped toWALKOVER, a default toDEFAULTED);- level teams are separated by the games between them, then points difference and points scored in those games, then the
same over all group games, then a draw (
terminal: 'LOT'); onSplit: 'RESTART'(D.1.4).
The FIBA ranking step (national-team competitions) is an external value and is not applied.
Premier League Policy
POLICY_ROUND_ROBIN_TALLY_PREMIER_LEAGUE: Premier League Handbook 2025/26, rules C.4 to C.7 and C.17:
resultPoints: 3 for a win, 1 for a draw; goals are each half's score (HAL2A-S:T45), so goal difference isgamesDiffand goals scoredgamesWon;- clubs level on points are separated by goal difference, then goals scored (C.5, C.6); clubs still level share the
place (C.7,
terminal: 'SHARE'); - C.17 applies only at the end of the season and only where the title, relegation or qualification depends on it: the
points in the matches between the tied clubs, as a directive
when: { purposes: ['ADVANCEMENT', 'MOVEMENT'], phase: 'FINAL' }. A season table asked for one of those purposes applies it; a caller deciding the title asks withADVANCEMENT.
Not applied: C.17's away goals between the tied clubs (the factory records no home or away side) and its play-off, which is a match the organiser arranges.
MLS Policy
POLICY_ROUND_ROBIN_TALLY_MLS: MLS 2026 Competition Guidelines, regular-season tiebreaking procedures:
resultPoints: 3 for a win, 1 for a tie;- level clubs are separated by total wins, goal differential, goals for, then head-to-head points and goal
differential, then the fewest disciplinary points (an
externalvalue,disciplinaryPoints, fewer is better), then a coin toss or drawing of lots (terminal: 'LOT'); - once a club is separated, the clubs still tied go through the procedure again (
onSplit: 'EXTRACT_ONE').
The head-to-head steps are for a conference table (MLS applies them intraconference only); a table across both conferences (the Supporters' Shield) drops them. Not applied: the away and home goal steps, since the factory records no home or away side.
FIVB Policy
POLICY_ROUND_ROBIN_TALLY_FIVB: FIVB Volleyball Nations League 2026 Competition Regulations, § 2.5:
- teams are ranked on victories (
matchUpsWon), then match points: 3 for a 3-0 or 3-1 win, 2 for a 3-2 win, 1 for a 2-3 loss, 0 for a 0-3 or 1-3 loss, and 0 for a forfeit (a forfeit mapped toWALKOVER, 3 to the winner); - then set ratio and points ratio (rally points are each set's tiebreak score,
SET5-S:TB25-F:TB15; nothing lost ranks first); - then the matches among the tied teams only, on the same criteria (
onSplit: 'CONTINUE'); - then the FIVB World Ranking, an
externalvalue,worldRanking(lower is better).
The regulations name no step after the World Ranking.
Key Attributes
groupOrderKey
Purpose: Initial attribute to group participants by before applying tiebreakers.
Valid values:
'matchUpsWon'(default)'tieMatchUpsWon'(for TEAM events)'tieSinglesWon'(for TEAM events)'tieDoublesWon'(for TEAM events)'pointsWon''gamesWon''setsWon''gamesPct''setsPct''pointsPct''matchUpsPct'
Example:
const policy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
groupOrderKey: 'gamesWon', // Group by total games won
tallyDirectives: [{ attribute: 'gamesPct', idsFilter: false }],
},
};
tallyDirectives
Purpose: Sequence of tiebreaking rules applied in order.
Structure:
{
attribute: string; // Statistic to compare
idsFilter?: boolean; // Scope to tied participants only
reversed?: boolean; // Reverse sort order (least-to-greatest)
maxParticipants?: number; // Threshold-based application
groupTotals?: boolean; // Use group totals for percentages
}
Directive attributes:
matchUpsPct- Match win percentagesetsPct- Set win percentagegamesPct- Game win percentagepointsPct- Point win percentagematchUpsWon- Total matches wonsetsWon- Total sets wongamesWon- Total games wonpointsWon- Total points wonmatchUpsLost- Total matches lostsetsLost- Total sets lostgamesLost- Total games lostpointsLost- Total points lostdefaults- Number of defaultswalkovers- Number of walkoversretirements- Number of retirementsallDefaults- All exit statuses combinedtieMatchUpsWon- Individual matches won (TEAM events)tieSinglesWon- Singles matches won (TEAM events)tieDoublesWon- Doubles matches won (TEAM events)
See also: maxParticipants documentation for threshold-based tiebreaking
idsFilter
Purpose: Scope calculations to only the tied participants.
When false (default):
- Statistics calculated from ALL group matches
- Example: gamesPct = gamesWon / (gamesWon + gamesLost) across entire group
When true:
- Statistics calculated ONLY from matches among tied participants
- Example: If A, B, C are tied, only count A-B, A-C, B-C matches
- Used for head-to-head comparisons
Example:
tallyDirectives: [
// Stage 1: Overall group performance
{ attribute: 'gamesPct', idsFilter: false },
// Stage 2: Performance among tied teams only
{ attribute: 'gamesPct', idsFilter: true },
];
reversed
Purpose: Reverse sort order from greatest-to-least to least-to-greatest.
Use cases:
- Fewest losses
- Fewest defaults/walkovers/retirements
- Fewest penalty minutes
- Any "lower is better" metric
Example:
tallyDirectives: [
{ attribute: 'gamesWon', reversed: false }, // Most games won
{ attribute: 'gamesLost', reversed: true }, // Fewest games lost
];
maxParticipants
Purpose: Only apply directive when number of tied participants does not exceed threshold.
Common usage:
{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2 // Only if exactly 2 teams tied
}
Why this exists:
- 2 teams: Direct head-to-head works (one beat the other)
- 3+ teams: Circular ties possible (A>B>C>A)
- Sports rules universally distinguish 2-team vs 3+-team ties
See: maxParticipants documentation for complete details and sports precedents
groupTotals
Purpose: Use total group games/sets for percentage calculations instead of participant totals.
When false (default):
gamesPct = gamesWon / (gamesWon + gamesLost)
// Sum of all gamesPct can be > 1.0
When true:
gamesPct = gamesWon / (total games played by all participants)
// Sum of all gamesPct = 1.0
Example:
tallyDirectives: [
{
attribute: 'gamesPct',
idsFilter: false,
groupTotals: true, // Use total group games as denominator
},
];
Or set at top level:
{
groupTotalGamesPlayed: true, // All gamesPct calculations
groupTotalSetsPlayed: true, // All setsPct calculations
}
headToHead
Purpose: Configure head-to-head tiebreaking behavior.
Default behavior:
- When 2 participants tied: Compare their head-to-head record
- When 3+ participants tied: Try to separate with head-to-head among all tied
Disable completely:
{
headToHead: { disabled: true },
tallyDirectives: [
// Head-to-head skipped, go straight to directives
{ attribute: 'gamesPct', idsFilter: false },
],
}
Note: Head-to-head happens BEFORE tallyDirectives. Disabling it forces all tiebreaking through directives.
Splits, gates and the final step
These fields are read by the standings engine, which orders round-robin groups and season tables alike.
onSplit
What happens when a directive splits a tied set.
'RESTART'(default): every part goes back to the first directive. A pair split off bysetsPctis settled by head-to-head next. FIBA, NBA, IIHF and FIDE work this way.'CONTINUE': every part continues with the next directive. A mini-league directive (idsFilter: true) is first re-applied to the residue it leaves, so a pair it splits off is settled by their own meeting before any overall measure is read.'EXTRACT_ONE': one participant is resolved per step, the leader of the top part, and everyone else (including the rest of the top part) goes back to the first directive. This is the NFL's procedure.
minParticipants
The directive is passed over when fewer than this many participants are tied, as maxParticipants passes it over
when more are. For example, aggregate measures for a three-way tie, head-to-head for two.
when
{ purposes?: string[]; phase?: 'PROVISIONAL' | 'FINAL' } on a directive. purposes limits it to tables computed
for those purposes: getSeasonStandings({ purpose }), with STANDINGS_PURPOSE_MOVEMENT passed by
getSeasonMovement and STANDINGS_PURPOSE_ADVANCEMENT by getSeasonAdvancement. phase: 'FINAL' skips the
directive while results are outstanding (a provisional order). A directive skipped by when is not reported.
headToHead directives (RECORD, SWEEP)
Head-to-head may also be written as a directive, { attribute: 'headToHead', mode }:
'RECORD'(the default reading): two tied participants, the one with more wins over the other.'SWEEP': any number tied. A participant who beat every other one is placed first, or else one who lost to every other one is placed last (the NFL's wild-card rule); everyone else goes back to the first directive. With no sweep, nothing splits.
external
{ attribute: 'external', externalKey } reads values from outside the results: a curling Draw Shot Challenge, a
ranking, fair-play points. They are passed by the caller as externalValues: { [externalKey]: { [participantId]: number } } to tallyParticipantResults, or keyed by subjectId to getSeasonStandings; the factory never fetches them. A
participant without a value reads 0. Use reversed: true where lower is better (a draw-shot distance).
terminal
What happens to a set no directive splits.
'ADJUDICATE'(default): the set shares a place, and an organiser's sub-order (setSubOrder) may order it.'SHARE': the place is shared and stays shared, whatever a sub-order says.'LOT': a draw seeded by the structure (a group) or the season and tier (a season table). The same seed always draws the same order, and the report records the seed.
{
onSplit: 'CONTINUE',
terminal: 'LOT',
tallyDirectives: [
{ attribute: 'matchUpsPct', idsFilter: true },
{ attribute: 'gamesPct', minParticipants: 3 },
{ attribute: 'gamesWon', when: { purposes: ['MOVEMENT'], phase: 'FINAL' } },
],
}
Percentage Calculations
precision
Purpose: Control decimal precision for percentage calculations.
Default: 3 (1000)
Example:
{
precision: 5, // Results: 0.66667 instead of 0.667
}
Formula: Math.pow(10, precision)
- precision: 3 → 1000 → 0.667
- precision: 5 → 100000 → 0.66667
- precision: 7 → 10000000 → 0.6666667
precision: 'EXACT'
precision: 'EXACT' compares and stores percentages unrounded, so two percentages tie only when their fractions are
equal. With a number (default 3), values equal after rounding to that many decimal places tie. Many rulebooks state
this explicitly ("win percentage to three decimal places"), so it is a ranking rule, not only a display setting.
Zero denominators
A percentage with nothing played is 0. For example, setsPct for a participant whose only result is a walkover. A
ratio with nothing lost is unbounded: it ranks first when anything was won, and is 0 when nothing was won either. A
directive can change that with zeroDivision (below).
Differences and ratios
setsDiff, gamesDiff and pointsDiff (won minus lost) are stored with the other measures. setsRatio,
gamesRatio and pointsRatio (won over lost) are computed only when ordering, never stored, because a ratio with
nothing lost is unbounded and a stored tally must stay serialisable. Any of them may be the groupOrderKey or a
directive attribute.
A ratio directive's zeroDivision decides what an unbeaten ratio means for that directive:
'MAX'(default): it ranks first (FIVB's convention).'ZERO': it reads as 0.'SKIP': the directive is passed over for any tied set where it happens.
Strength of schedule (graph measures)
buchholz, buchholzCut1, buchholzMedian and sonnebornBerger read the whole table, scoring each opponent by the
policy's primary measure (its groupOrderKey), once per meeting:
buchholz: the sum of the opponents' scores.buchholzCut1: the same without the lowest.buchholzMedian: the same without the highest and the lowest.sonnebornBerger: the scores of the opponents beaten, plusdrawCredit(default 0.5) of the scores of those drawn with.
They are computed only when ordering and never stored. They may be directive attributes, but not the
groupOrderKey (the primary measure scores the opponents), not scoped by idsFilter, and not a crossGroup
measure. FIDE's convention for unplayed rounds (a virtual opponent) is not applied: only meetings that were played
count.
Common opponents
commonOpponents is the NFL's "won-lost-tied percentage in common games". Its value depends on who is tied: for the set
being sorted, the common opponents are the participants every member of the set has met, and each member is scored by
its win percentage over every meeting with them, a draw counting drawCredit (default 0.5). No member of the set is a
common opponent of the others, so the meetings among the tied are not counted; head-to-head is a separate directive.
{ attribute: 'commonOpponents', minSample: 4 }
minSample (default 1) is the fewest meetings against common opponents each member needs. When any member of the set
has fewer, the directive does not split that set and the next directive is tried; the report records
{ attribute: 'commonOpponents', skipped: 'minSample', participantIds }. The NFL requires four for a wild-card tie.
It is most useful where not everyone meets everyone, as in a season table; in a complete round robin, every participant outside the set is a common opponent.
Groupings: divisions, conferences and sets
Divisions and conferences are supplied by the caller, like externalValues; the factory never fetches them. A
season derives them instead: getSeasonStandings({ combine: true }) orders a parent tier's table over its divisions'
matchUps with the grouping tier (see Seasons). Elsewhere they are passed to
tallyParticipantResults (and the ordering core) by name:
tallyParticipantResults({
matchUps,
policyDefinitions,
// named groupings: participantId → group key
groupings: { division: { A: 'EAST', B: 'EAST', C: 'WEST' } },
// each participant's place in its own group's table, decided by that group's own policy (1 leads it)
groupRanks: { division: { B: 1, A: 2, C: 1 } },
// sets that records are read against
participantSets: { eligible: ['A', 'C'] },
});
preReduce: { groupBy } (the NFL wild card's first step): in a tied set where two or more members share a group,
only each group's best-ranked member competes for the next place. The candidates are ordered by the directives, the
first one placed is taken, and everyone else, its group-mates included, goes back through the same procedure. A team
therefore cannot be placed ahead of a tied team that leads it in its own division, but it is not held back behind the
other divisions' leaders either. When the top candidates stay tied, they keep their shared place and the rest follow. A
participant with no group, or with no rank, is not reduced. The report records each step as
{ attribute: 'preReduce', groupBy, candidates, placed }.
{ preReduce: { groupBy: 'division' }, onSplit: 'EXTRACT_ONE', tallyDirectives: [ /* the wild-card steps */ ] }
Three more directive measures read the groupings:
groupLeader(groupBy): 1 for a participant ranked first in its group, else 0. The NBA's "division winner".recordVsGroup(groupBy): the record against the members of its own group, the division or conference win percentage. It splits only a set whose members all share a group; otherwise it is passed over for that set and the report recordsskipped: 'groupBy'(NBA: "only if in the same division").recordVsSet(setKey): the record against the members ofparticipantSets[setKey], such as the NBA's postseason-eligible teams. The caller defines the set; the NBA's definition depends on the standings themselves.
A record is a win percentage with a draw counting drawCredit, like commonOpponents. A member of the set with no
meeting to count passes the directive over for that set (skipped: 'noMeetings').
Tied-set measures
commonOpponents, groupLeader, recordVsGroup and recordVsSet are computed only when ordering and never stored.
They may be directive attributes, but not the groupOrderKey, not scoped by idsFilter (each reads the whole table),
and not a crossGroup measure.
resultPoints
Classification points by result, for sports whose tables award points per result rather than counting wins: FIBA's 2 for a win, 1 for a played or defaulted loss and 0 for a forfeit, or volleyball's 3 for a 3-0 or 3-1 win and 2 and 1 for a 3-2. The rules are matched in order, and the first that matches decides.
{
groupOrderKey: 'classificationPoints',
resultPoints: {
rules: [
{ id: 'forfeit', matchUpStatuses: ['WALKOVER'], winner: 3, loser: 0 },
{ id: 'five-sets', loserSetsWon: [2], winner: 2, loser: 1 },
{ id: 'win', winner: 3, loser: 0 },
{ id: 'draw', isDrawn: true, points: 1 },
],
},
}
- A decided rule may name
matchUpStatusesandloserSetsWon(the sets the loser won), and awardswinnerandloserpoints. A drawn rule awardspointsto both sides. - Statuses are mapped by the rules, never inferred: whether a sport's "forfeit" is a
WALKOVERis the policy author's decision. - A decided rule may also name
loserMarginAtMost: the loser lost by no more than that many, the sides' scores summed over every set and then subtracted (rugby's points, recorded as each half's score inHAL2A-S:T40). - A rule with
bonus: trueadds to the deciding rule's award instead of deciding. Every bonus rule that matches adds its points, wherever it is listed; a result that no deciding rule matches earns no bonus either, and the rules must include at least one rule that is not a bonus. A bonus that awards a side nothing is not listed among its contributions. Rugby's losing bonus (the PREM league table regulations, read 2026-11-04: 4 for a win, 2 for a draw, 1 to a team that loses a match by 7 points or less):
{
groupOrderKey: 'classificationPoints',
resultPoints: {
rules: [
{ id: 'win', winner: 4, loser: 0 },
{ id: 'draw', isDrawn: true, points: 2 },
{ id: 'losingBonus', bonus: true, loserMarginAtMost: 7, winner: 0, loser: 1 },
],
},
}
Rugby's four-try bonus needs the tries, which a score does not record; it is not yet expressible.
- A decided rule may name
decidedIn(the phase that completed the result:REGULATION,OVERTIME,DECIDER, orEXTERNALfor a winner decided outside the score) anddecidedBy(how that winner was decided:SHOOTOUT,COMPETITION_RULE,LOTS,OFFICIAL_DECISION). A result with no record was decided inREGULATION. IIHF's 3-2-1-0 over a format that declares its overtime and shootout (PER3XA-S:T20P-O:1SD/T5P-F:SO5), which recordsdecidedInon every result:
{
groupOrderKey: 'classificationPoints',
resultPoints: {
rules: [
{ id: 'regulation', decidedIn: ['REGULATION'], winner: 3, loser: 0 },
{ id: 'overtime', decidedIn: ['OVERTIME', 'DECIDER'], winner: 2, loser: 1 },
],
},
}
Where the format declares no shootout and one is entered as a decided result, the rule for it is
{ id: 'shootout', decidedBy: ['SHOOTOUT'], winner: 2, loser: 1 }.
- A drawn result is a COMPLETED matchUp with no winner whose score is a level finish its format permits: a level
combined total (
SET1-S:P32), a level aggregate over all of its segments (HAL2A-S:T45, a soccer 1-1), or a level count of sets (SET3-S:T10, a timed set closing level;SET2X-S:6/TB7, one set each). It stands only where no winner is needed: a round robin or an ad hoc draw. A format with a declared overtime (-O:) is drawn where the scoring engine completes it with no winner: a finite overtime with no decider that stays level. A level result with a winner decided outside the score (score.overtime.decidedIn: 'EXTERNAL') is that winner's win, not a draw. - An unfinished, excluded or BYE result earns nothing. A decided or drawn result that matches no rule is listed on both
participants in
classificationUnmatchedrather than counted as 0 in silence. - Each participant's tally carries
classificationPoints, andclassificationContributionsrecords each result's rule and points. Nothing is written withoutresultPoints.
denominator
denominator: 'EXPECTED' makes setsPct and gamesPct divide by the sets and games a participant was expected to
play. For example, a walkover win counts as sets the winner was due to play. The engine works the expected meetings
out from the group itself (any number of meetings per pair). 'PLAYED' (default) divides by what was actually played.
Completion
A group is complete when every meeting has a result, so a double round robin and a group with an excluded status
(excludeMatchUpStatuses) complete, and their order is written as groupOrder. Before the standings engine, they
only ever received provisionalOrder.
groupTotalGamesPlayed / groupTotalSetsPlayed
Purpose: Use total group games/sets as denominator for percentage calculations.
Example scenario:
4 participants in round robin (6 total matches):
- Participant A: 12 games won, 6 games lost
- Participant B: 10 games won, 8 games lost
- Participant C: 8 games won, 10 games lost
- Participant D: 6 games won, 12 games lost
Total: 36 games won, 36 games lost (72 games total)
Without groupTotalGamesPlayed:
A: 12/18 = 66.7%
B: 10/18 = 55.6%
C: 8/18 = 44.4%
D: 6/18 = 33.3%
Total: 200%
With groupTotalGamesPlayed:
A: 12/72 = 16.7%
B: 10/72 = 13.9%
C: 8/72 = 11.1%
D: 6/72 = 8.3%
Total: 50% (games won / total games)
Credit for Incomplete Matches
setsCreditForDefaults / setsCreditForWalkovers / setsCreditForRetirements
Purpose: Award winner full sets when opponent doesn't complete match.
Default: All false
Example:
// Best of 3 (2 sets to win)
// Match: A vs B, score 6-3, B retires
// Without setsCreditForRetirements:
A: 1 set won
// With setsCreditForRetirements:
A: 2 sets won (awarded setsToWin)
Policy:
{
setsCreditForRetirements: true,
setsCreditForDefaults: true,
setsCreditForWalkovers: true,
}
gamesCreditForDefaults / gamesCreditForWalkovers / gamesCreditForRetirements
Purpose: Award winner estimated games when opponent doesn't complete match.
Default: All false
Example:
// Best of 3, standard scoring (6 games per set)
// Match: A vs B, score 6-3, B retires
// Without gamesCreditForRetirements:
A: 6 games won
// With gamesCreditForRetirements:
A: 12 games won (estimated from setsToWin * 6)
gamesCreditForTiebreakSets
Purpose: Count tiebreak set as 1 game won.
Default: true
Example:
// Match: A vs B, score 6-3 3-6 [10-5]
// With gamesCreditForTiebreakSets: true
A: 6 + 3 + 1 = 10 games won
B: 3 + 6 = 9 games won
// With gamesCreditForTiebreakSets: false
A: 6 + 3 = 9 games won
B: 3 + 6 = 9 games won
Policy:
{
gamesCreditForTiebreakSets: false, // Don't count [10-x] as game
}
Disqualification
disqualifyDefaults / disqualifyWalkovers
Purpose: A participant who conceded a walkover (disqualifyWalkovers) or a default (disqualifyDefaults) is
ordered below every participant who conceded none, whatever their record. The disqualified participants are then
ordered among themselves by the same policy. A retirement does not disqualify.
Default: true in the built-in default, JTT and TOC policies.
Implemented by the standings engine. Before it, these flags were declared in the built-in policies but read by no code, so a participant who conceded a walkover was ordered by their record like anyone else.
Example:
// 4 participants:
// A: 2-1
// B: 2-1
// C: 1-2
// D: 1-2 (with 1 DEFAULT)
// With disqualifyDefaults: true
Order: A, B, C, D (4th - pushed to bottom)
// With disqualifyDefaults: false
Order: A, B, C/D tied (use tiebreakers)
Policy:
{
disqualifyDefaults: true,
disqualifyWalkovers: true,
}
Exclude Match Statuses
excludeMatchUpStatuses
Purpose: Exclude specific match statuses from tally calculations.
Use cases:
- Exclude ABANDONED matches
- Exclude INCOMPLETE matches
- Exclude matches that shouldn't count toward standings
Example:
{
excludeMatchUpStatuses: ['ABANDONED', 'INCOMPLETE'],
}
Effect:
- Excluded matches don't count toward wins/losses
- Not included in percentage calculations
- Treated as if they never happened
GEMscore
Purpose: Create composite score from multiple attributes.
Formula: Weighted combination of percentage attributes
Attributes:
matchUpsPcttieMatchUpsPctsetsPctgamesPctpointsPct
Result:
participantResults: {
participantId123: {
matchUpsWon: 2,
matchUpsLost: 1,
matchUpsPct: 0.667,
setsPct: 0.714,
gamesPct: 0.650,
GEMscore: 85234567, // Composite integer score
}
}
Usage:
- Alternative ranking metric
- Visual representation of overall performance
- Can be used as tiebreaker attribute
Best finishers across groups
crossGroup
When a playoff takes the best finishers of a position across several groups (the best third-placed participants),
the candidates are compared by crossGroup: an ordered list of stored measures, higher first, a reversed one lower
first. The first measure that differs decides. Head-to-head cannot apply across groups.
{
crossGroup: [{ attribute: 'matchUpsPct' }, { attribute: 'gamesDiff' }, { attribute: 'gamesLost', reversed: true }],
}
The values are written to each participant's tally as crossGroupValues when the group is tallied. Without a
crossGroup, candidates are compared by GEMscore, as before. A ratio cannot be a crossGroup measure, because ratios
are computed only when ordering and are never stored.
Usage Examples
Example 1: Standard Tournament
import { fixtures, policyConstants } from 'tods-competition-factory';
const { POLICY_TYPE_ROUND_ROBIN_TALLY } = policyConstants;
const { POLICY_ROUND_ROBIN_TALLY_DEFAULT } = fixtures.policies;
const tournament = {
policyDefinitions: POLICY_ROUND_ROBIN_TALLY_DEFAULT,
};
tournamentEngine.generateDrawDefinition({
drawType: ROUND_ROBIN,
policyDefinitions: tournament.policyDefinitions,
drawSize: 16,
// ... other options
});
Example 2: Custom Tiebreaking
const customPolicy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
policyName: 'Custom Tournament 2024',
groupOrderKey: 'matchUpsWon',
tallyDirectives: [
// 1. Head-to-head if exactly 2 tied
{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2,
},
// 2. Games percentage (all matches)
{
attribute: 'gamesPct',
idsFilter: false,
},
// 3. Sets percentage (all matches)
{
attribute: 'setsPct',
idsFilter: false,
},
// 4. Games won among tied teams
{
attribute: 'gamesWon',
idsFilter: true,
},
// 5. Fewest games lost
{
attribute: 'gamesLost',
idsFilter: false,
reversed: true,
},
],
disqualifyDefaults: true,
disqualifyWalkovers: true,
},
};
Example 3: Team Tennis (TEAM Events)
const teamPolicy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
policyName: 'Team Championship',
groupOrderKey: 'tieMatchUpsWon', // Individual matches won
tallyDirectives: [
// Team match record among tied teams
{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2,
},
// Individual matches won
{
attribute: 'tieMatchUpsWon',
idsFilter: false,
},
// Singles matches won
{
attribute: 'tieSinglesWon',
idsFilter: false,
},
// Doubles matches won
{
attribute: 'tieDoublesWon',
idsFilter: false,
},
// Sets won
{
attribute: 'setsWon',
idsFilter: false,
},
],
},
};
Example 4: Games-Based Ranking
const gamesPolicy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
policyName: 'Games Primary',
groupOrderKey: 'gamesWon',
tallyDirectives: [
// Most games won
{
attribute: 'gamesWon',
idsFilter: false,
},
// Fewest games lost
{
attribute: 'gamesLost',
idsFilter: false,
reversed: true,
},
// Game percentage
{
attribute: 'gamesPct',
idsFilter: false,
},
// Head-to-head if 2 teams
{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2,
},
],
// Award games for walkovers/defaults
gamesCreditForWalkovers: true,
gamesCreditForDefaults: true,
},
};
Example 5: Hockey-Style with Penalty Minutes
const hockeyPolicy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
policyName: 'Hockey Tournament',
groupOrderKey: 'matchUpsWon',
tallyDirectives: [
// Head-to-head (2 teams only)
{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2,
},
// Most wins
{
attribute: 'matchUpsWon',
idsFilter: false,
},
// Goal average (custom attribute - would need implementation)
// { attribute: 'goalAverage', idsFilter: false },
// Fewest penalty minutes (custom attribute)
// { attribute: 'penaltyMinutes', idsFilter: false, reversed: true },
// Fallback to games
{
attribute: 'gamesPct',
idsFilter: false,
},
],
},
};
Best Practices
1. Always Provide Fallback Directives
// ✓ GOOD: Multiple tiebreakers
tallyDirectives: [
{ attribute: 'matchUpsPct', idsFilter: true, maxParticipants: 2 },
{ attribute: 'gamesPct', idsFilter: false },
{ attribute: 'gamesWon', idsFilter: false },
{ attribute: 'gamesLost', idsFilter: false, reversed: true },
];
// ✗ BAD: Single tiebreaker might not resolve all ties
tallyDirectives: [{ attribute: 'matchUpsPct', idsFilter: true, maxParticipants: 2 }];
2. Use maxParticipants for Head-to-Head
// ✓ GOOD: Only apply head-to-head when it makes sense
{
attribute: 'matchUpsPct',
idsFilter: true,
maxParticipants: 2 // Skip if 3+ teams (circular ties possible)
}
// ✗ RISKY: Head-to-head with 3+ teams can be indeterminate
{
attribute: 'matchUpsPct',
idsFilter: true // May not separate circular ties
}
3. Order Directives Logically
// ✓ GOOD: Broad criteria first, narrow criteria later
tallyDirectives: [
{ attribute: 'matchUpsPct', idsFilter: false }, // Overall record
{ attribute: 'setsPct', idsFilter: false }, // Overall sets
{ attribute: 'matchUpsPct', idsFilter: true }, // Head-to-head
{ attribute: 'setsPct', idsFilter: true }, // H2H sets
];
// ✗ CONFUSING: Narrow then broad
tallyDirectives: [
{ attribute: 'matchUpsPct', idsFilter: true }, // H2H first
{ attribute: 'matchUpsPct', idsFilter: false }, // Then overall
];
4. Document Tournament-Specific Rules
const tournamentPolicy = {
[POLICY_TYPE_ROUND_ROBIN_TALLY]: {
policyName: 'Spring Championship 2024',
// Document: "Per tournament regulations section 5.3"
groupOrderKey: 'matchUpsWon',
tallyDirectives: [
// Rule 5.3.1: Head-to-head if 2 teams tied
{ attribute: 'matchUpsPct', idsFilter: true, maxParticipants: 2 },
// Rule 5.3.2: Games won percentage
{ attribute: 'gamesPct', idsFilter: false },
// Rule 5.3.3: Fewest games lost
{ attribute: 'gamesLost', idsFilter: false, reversed: true },
],
},
};
Related Documentation
- maxParticipants - Threshold-based tiebreaking rules
- Seeding Policy - How participants are seeded into draws
- Feed-In Policy - Consolation feed patterns
- Policies Overview - All policy types
Methods
tallyParticipantResults
Calculate participant results and group order based on the round robin tally policy.
import { competitionEngine } from 'tods-competition-factory';
const { tallyParticipantResults } = competitionEngine;
const { participantResults, order, report, readableReport } = tallyParticipantResults({
matchUps, // Array of matchUps
policyDefinitions, // Policy definitions object
matchUpFormat, // Optional default format
generateReport: true, // Optional: generate detailed tiebreaking report
});
// participantResults: {
// [participantId]: {
// matchUpsWon: number;
// matchUpsLost: number;
// setsWon: number;
// setsLost: number;
// gamesWon: number;
// gamesLost: number;
// pointsWon: number;
// pointsLost: number;
// matchUpsPct: number;
// setsPct: number;
// gamesPct: number;
// pointsPct: number;
// defaults: number;
// walkovers: number;
// retirements: number;
// allDefaults: number;
// groupOrder: number; // Final placement (when bracket complete)
// provisionalOrder: number; // Current placement (when incomplete)
// GEMscore?: number; // If configured
// }
// }
When generateReport: true, the function returns detailed information showing exactly how tiebreaks were resolved step-by-step. This is invaluable for:
- Explaining to participants why they finished in a specific position
- Verifying that tiebreaking followed the expected policy
- Debugging complex tiebreaking scenarios
- Creating transparent tournament reports
See Query Governor - tallyParticipantResults for complete documentation of the generateReport parameter and examples of using the tiebreaking report.
Notes
groupOrder vs provisionalOrder
- groupOrder: Assigned when bracket is complete
- provisionalOrder: Assigned when bracket is incomplete
- See
provisionalPositioningin Draws Governor
Bracket Completion
Group order is ONLY assigned when all required matchUps are complete:
const bracketComplete = relevantMatchUps.filter((matchUp) => isComplete(matchUp)).length === relevantMatchUps.length;
if (bracketComplete && groupOrder) {
// Assign groupOrder to participantResults
}
For incomplete brackets, use provisionalOrder instead.
Circular Ties
With 3+ participants, circular ties are possible:
- Team A beats Team B
- Team B beats Team C
- Team C beats Team A
- All teams 1-1 head-to-head
Solution: Use maxParticipants: 2 on head-to-head rules to skip circular tie scenarios.
See maxParticipants documentation for details.
Validation
A tally policy is checked where it is saved: attachPolicies (before anything is written) and validateSeason (for
a season's or a tier's tallyPolicy) refuse it with INVALID_VALUES. validateTallyPolicy({ tallyPolicy }) runs the
same checks on its own. A season standings calculation does not refuse for its policy; the season was checked when
saved. Previously an unknown groupOrderKey was accepted and silently ranked by matchUpsWon.
An absent policy (undefined) is valid. Every other value is checked against the rules below, in the order they are
listed, and every rule that fails is collected; the refusal is
{ error: INVALID_VALUES, info: '<the message of the first rule that fails>', context: { errors: ['<every message>'] }, stack: ['validateTallyPolicy'] }
attachPolicies returns that refusal as it is. validateSeason lists each message in its own context.errors,
prefixed by its owner and a space: season tallyPolicy: or tier <tierId> tallyPolicy:.
Accepted names
- Primary measures (
groupOrderKey):tieMatchUpsWon,tieSinglesWon,tieDoublesWon,matchUpsWon,matchUpsDrawn,standingsPoints,pointsWon,gamesWon,setsWon,gamesPct,setsPct,pointsPct,matchUpsPct,setsDiff,gamesDiff,pointsDiff,setsRatio,gamesRatio,pointsRatio,classificationPoints. - Measures (a directive
attribute):allDefaults,defaults,walkovers,retirements,matchUpsWon,matchUpsLost,matchUpsDrawn,matchUpsCancelled,matchUpsPct,setsWon,setsLost,setsPct,gamesWon,gamesLost,gamesPct,pointsWon,pointsLost,pointsPct,tieMatchUpsWon,tieMatchUpsLost,tieMatchUpsPct,tieSinglesWon,tieSinglesLost,tieDoublesWon,tieDoublesLost,standingsPoints,setsDiff,gamesDiff,pointsDiff,setsRatio,gamesRatio,pointsRatio,classificationPoints,buchholz,buchholzCut1,buchholzMedian,sonnebornBerger. - Directive-only attributes, which are not measures:
headToHead,external. - Tied-set measures (a directive
attributeonly):commonOpponents,groupLeader,recordVsGroup,recordVsSet. - Ratio measures:
setsRatio,gamesRatio,pointsRatio. - Graph measures:
buchholz,buchholzCut1,buchholzMedian,sonnebornBerger. - A season's extra measures: a season's or a tier's policy may also use
valueWonandvalueLost, both as the primary measure and as a measure.
Rules
"Whole number" means an integer value (2 and 2.0 alike). "Finite number" means a number that is neither infinite
nor NaN. In a message, [i] is the zero-based index and a value is written as text (an absent one as undefined).
Each rule's example is a policy that it refuses, with the message it gives.
| Rule | Refused | Message |
|---|---|---|
The policy is an object (null is not). | "text" | tallyPolicy must be an object |
groupOrderKey, when present, is a primary measure. | { "groupOrderKey": "gamesWonn" } | unknown groupOrderKey: gamesWonn |
groupOrderKey is not a graph measure (a graph measure scores opponents by the primary measure; it is also not a primary measure, so the rule above fails first). | { "groupOrderKey": "sonnebornBerger" } | unknown groupOrderKey: sonnebornBerger |
tallyDirectives, when present, is an array. | { "tallyDirectives": {} } | tallyDirectives must be an array |
Each directive is an object (null is not). | { "tallyDirectives": [3] } | tallyDirectives[0] must be an object |
A directive's attribute is a measure, a tied-set measure or a directive-only attribute. | { "tallyDirectives": [{ "attribute": "gamesWonn" }] } | tallyDirectives[0]: unknown attribute gamesWonn |
A headToHead directive's mode, when present, is RECORD or SWEEP. | { "tallyDirectives": [{ "attribute": "headToHead", "mode": "FIRST" }] } | tallyDirectives[0]: headToHead mode must be one of RECORD, SWEEP |
An external directive has an externalKey that is a non-empty string. | { "tallyDirectives": [{ "attribute": "external" }] } | tallyDirectives[0]: an external directive needs an externalKey |
A directive's minParticipants, when present, is a whole number of at least 1. | { "tallyDirectives": [{ "attribute": "gamesWon", "minParticipants": 0 }] } | tallyDirectives[0]: minParticipants must be a whole number of at least 1 |
A directive's maxParticipants, when present, is a whole number of at least 1. | { "tallyDirectives": [{ "attribute": "gamesWon", "maxParticipants": 1.5 }] } | tallyDirectives[0]: maxParticipants must be a whole number of at least 1 |
A directive's zeroDivision, when present, is MAX, ZERO or SKIP (any directive may carry it; only a ratio reads it). | { "tallyDirectives": [{ "attribute": "setsRatio", "zeroDivision": "INFINITY" }] } | tallyDirectives[0]: zeroDivision must be one of MAX, ZERO, SKIP |
A directive's when, when present, is an object (null is not). | { "tallyDirectives": [{ "attribute": "gamesWon", "when": "FINAL" }] } | tallyDirectives[0]: when must be an object |
when.purposes, when present, is an array of strings. | { "tallyDirectives": [{ "attribute": "gamesWon", "when": { "purposes": "MOVEMENT" } }] } | tallyDirectives[0]: when.purposes must be an array of strings |
when.phase, when present, is PROVISIONAL or FINAL. | { "tallyDirectives": [{ "attribute": "gamesWon", "when": { "phase": "LIVE" } }] } | tallyDirectives[0]: when.phase must be one of PROVISIONAL, FINAL |
A graph measure directive is not scoped by idsFilter (a truthy idsFilter); it reads the whole table. | { "tallyDirectives": [{ "attribute": "buchholz", "idsFilter": true }] } | tallyDirectives[0]: buchholz reads the whole table; idsFilter cannot scope it |
A tied-set measure directive is not scoped by idsFilter (a truthy idsFilter); it reads the whole table. | { "tallyDirectives": [{ "attribute": "commonOpponents", "idsFilter": true }] } | tallyDirectives[0]: commonOpponents reads the whole table; idsFilter cannot scope it |
A directive's minSample, when present, is on a commonOpponents directive (nothing else reads it). | { "tallyDirectives": [{ "attribute": "gamesPct", "minSample": 4 }] } | tallyDirectives[0]: minSample applies only to commonOpponents |
A directive's groupBy, when present, is on a groupLeader or recordVsGroup directive (nothing else reads it). | { "tallyDirectives": [{ "attribute": "gamesWon", "groupBy": "division" }] } | tallyDirectives[0]: groupBy applies only to groupLeader, recordVsGroup |
A groupLeader or recordVsGroup directive has a groupBy that is a non-empty string. | { "tallyDirectives": [{ "attribute": "groupLeader" }] } | tallyDirectives[0]: groupLeader needs a groupBy |
A directive's setKey, when present, is on a recordVsSet directive (nothing else reads it). | { "tallyDirectives": [{ "attribute": "recordVsGroup", "groupBy": "division", "setKey": "eligible" }] } | tallyDirectives[0]: setKey applies only to recordVsSet |
A recordVsSet directive has a setKey that is a non-empty string. | { "tallyDirectives": [{ "attribute": "recordVsSet" }] } | tallyDirectives[0]: recordVsSet needs a setKey |
A commonOpponents directive's minSample, when present, is a whole number of at least 1. | { "tallyDirectives": [{ "attribute": "commonOpponents", "minSample": 0 }] } | tallyDirectives[0]: minSample must be a whole number of at least 1 |
The policy's headToHead, when present, is an object (null is not). | { "headToHead": true } | headToHead must be an object |
precision, when present, is EXACT or a whole number of at least 0. | { "precision": -1 } | precision must be a whole number of decimal places, or 'EXACT' |
denominator, when present, is PLAYED or EXPECTED. | { "denominator": "ALL" } | denominator must be one of PLAYED, EXPECTED |
crossGroup, when present, is an array. | { "crossGroup": {} } | crossGroup must be an array |
Each crossGroup entry's attribute is a stored measure: a measure that is neither a ratio nor a graph measure. | { "crossGroup": [{ "attribute": "setsRatio" }] } | crossGroup[0]: setsRatio is not a stored measure |
preReduce, when present, is an object with a groupBy that is a non-empty string. | { "preReduce": {} } | preReduce must be an object with a groupBy |
resultPoints, when present, has rules: a non-empty array. | { "resultPoints": { "rules": [] } } | resultPoints.rules must be a non-empty array |
Each rule has an id, a non-empty string. | { "resultPoints": { "rules": [{ "winner": 2, "loser": 0 }] } } | resultPoints.rules[0] needs an id |
No two rules share an id. | { "resultPoints": { "rules": [{ "id": "win", "winner": 2, "loser": 0 }, { "id": "win", "winner": 2, "loser": 1 }] } } | resultPoints.rules[1]: duplicate id win |
A drawn rule (a truthy isDrawn) has points, a finite number. | { "resultPoints": { "rules": [{ "id": "draw", "isDrawn": true }] } } | resultPoints.rules[0]: a drawn rule needs finite points |
Any other rule is decided: it has winner and loser, both finite numbers. | { "resultPoints": { "rules": [{ "id": "win", "winner": 2 }] } } | resultPoints.rules[0]: a decided rule needs finite winner and loser points |
A rule's matchUpStatuses, when present, is an array. | { "resultPoints": { "rules": [{ "id": "wo", "winner": 2, "loser": 0, "matchUpStatuses": "WALKOVER" }] } } | resultPoints.rules[0]: matchUpStatuses must be an array |
A rule's loserSetsWon, when present, is an array of whole numbers of at least 0. | { "resultPoints": { "rules": [{ "id": "close", "winner": 2, "loser": 1, "loserSetsWon": [-1] }] } } | resultPoints.rules[0]: loserSetsWon must be an array of whole numbers |
A rule's loserMarginAtMost, when present, is a finite number of at least 0. | { "resultPoints": { "rules": [{ "id": "close", "winner": 4, "loser": 1, "loserMarginAtMost": -1 }] } } | resultPoints.rules[0]: loserMarginAtMost must be a finite number of at least 0 |
loserMarginAtMost is a condition on a decided result, so a drawn rule cannot have one. | { "resultPoints": { "rules": [{ "id": "draw", "isDrawn": true, "points": 2, "loserMarginAtMost": 7 }] } } | resultPoints.rules[0]: loserMarginAtMost applies only to a decided rule |
A rule's bonus, when present, is true or false. | { "resultPoints": { "rules": [{ "id": "win", "winner": 4, "loser": 0, "bonus": "yes" }] } } | resultPoints.rules[0]: bonus must be true or false |
The rules include one that is not a bonus: a bonus only adds to what a deciding rule awarded. | { "resultPoints": { "rules": [{ "id": "close", "winner": 0, "loser": 1, "loserMarginAtMost": 7, "bonus": true }] } } | resultPoints.rules needs a rule that is not a bonus |
A rule's decidedIn, when present, is a non-empty array of REGULATION, OVERTIME, DECIDER, EXTERNAL. | { "resultPoints": { "rules": [{ "id": "win", "winner": 3, "loser": 0, "decidedIn": ["PENALTIES"] }] } } | resultPoints.rules[0]: decidedIn must be a non-empty array of REGULATION, OVERTIME, DECIDER, EXTERNAL |
decidedIn is a condition on a decided result, so a drawn rule cannot have one. | { "resultPoints": { "rules": [{ "id": "draw", "isDrawn": true, "points": 1, "decidedIn": ["REGULATION"] }] } } | resultPoints.rules[0]: decidedIn applies only to a decided rule |
A rule's decidedBy, when present, is a non-empty array of SHOOTOUT, COMPETITION_RULE, LOTS, OFFICIAL_DECISION. | { "resultPoints": { "rules": [{ "id": "so", "winner": 2, "loser": 1, "decidedBy": [] }] } } | resultPoints.rules[0]: decidedBy must be a non-empty array of SHOOTOUT, COMPETITION_RULE, LOTS, OFFICIAL_DECISION |
decidedBy is a condition on a decided result, so a drawn rule cannot have one. | { "resultPoints": { "rules": [{ "id": "draw", "isDrawn": true, "points": 1, "decidedBy": ["LOTS"] }] } } | resultPoints.rules[0]: decidedBy applies only to a decided rule |
onSplit, when present, is RESTART, CONTINUE or EXTRACT_ONE. | { "onSplit": "RESTARTS" } | onSplit must be one of RESTART, CONTINUE, EXTRACT_ONE |
terminal, when present, is ADJUDICATE, SHARE or LOT. | { "terminal": "COIN" } | terminal must be one of ADJUDICATE, SHARE, LOT |
drawCredit, when present, is a finite number from 0 to 1. | { "drawCredit": 2 } | drawCredit must be a finite number between 0 and 1 |
outcomePoints, when present, is an object whose win, draw and loss are finite numbers. | { "outcomePoints": { "win": 3, "draw": 1 } } | outcomePoints requires finite win, draw and loss values |
A policy ranking by standingsPoints (its groupOrderKey or any directive's attribute) has outcomePoints. | { "groupOrderKey": "standingsPoints" } | standingsPoints ranking requires outcomePoints |
Each directive is checked in turn, through its own rules from attribute to idsFilter. Every rule in the
table can fail together with the others, except the last three: of drawCredit, outcomePoints and the
standingsPoints rule, only the first that fails is reported.
A policy that uses every option and passes:
{
"groupOrderKey": "classificationPoints",
"precision": "EXACT",
"denominator": "EXPECTED",
"onSplit": "EXTRACT_ONE",
"preReduce": { "groupBy": "division" },
"terminal": "LOT",
"drawCredit": 0.5,
"outcomePoints": { "win": 3, "draw": 1, "loss": 0 },
"headToHead": { "disabled": false },
"crossGroup": [{ "attribute": "gamesDiff" }, { "attribute": "pointsWon", "reversed": true }],
"resultPoints": {
"rules": [
{ "id": "close", "winner": 2, "loser": 1, "loserSetsWon": [2], "matchUpStatuses": ["COMPLETED"] },
{ "id": "win", "winner": 3, "loser": 0 },
{ "id": "draw", "isDrawn": true, "points": 1 }
]
},
"tallyDirectives": [
{ "attribute": "headToHead", "mode": "SWEEP" },
{ "attribute": "standingsPoints", "minParticipants": 2, "maxParticipants": 4 },
{ "attribute": "setsRatio", "zeroDivision": "SKIP", "when": { "purposes": ["MOVEMENT"], "phase": "FINAL" } },
{ "attribute": "buchholz", "idsFilter": false },
{ "attribute": "commonOpponents", "minSample": 4 },
{ "attribute": "groupLeader", "groupBy": "division" },
{ "attribute": "recordVsGroup", "groupBy": "conference" },
{ "attribute": "recordVsSet", "setKey": "eligible" },
{ "attribute": "external", "externalKey": "drawShot", "reversed": true }
]
}
Testing
Comprehensive test coverage in src/tests/documentation/roundRobinTallyPolicy.test.ts:
- ✅ All built-in policies
- ✅ Precision calculations
- ✅ maxParticipants thresholds
- ✅ Reversed attributes
- ✅ Disqualification rules
- ✅ Exclude match statuses
- ✅ Credit for incomplete matches
- ✅ groupTotals calculations
- ✅ idsFilter scoping
- ✅ Head-to-head configurations
- ✅ GEMscore generation
- ✅ TEAM event statistics
- ✅ Circular tie scenarios