matchUpFormat Codes

Overview

A matchUpFormat code describes the scoring method used for a specific matchUp, for all matchUps within a structure, for all matchUps within a drawDefinition, or for all matchUps within an event.

While originally designed for tennis, the format code grammar supports any sport that uses segmented scoring: pickleball, padel, squash, badminton, table tennis, volleyball, and even timed-segment sports like soccer, basketball, and combat sports.

See also: matchUpFormat Governor for the parse(), stringify(), and isValidMatchUpFormat() API reference.

Interactive Format Editor

Configure matchUp formats interactively and generate CODES-compliant format codes:

Format Code Grammar

A matchUpFormat code has the structure:

{ROOT}{count}[X][A]-S:{setSpec}[-G:{gameSpec}][-F:{setSpec}][-M:{matchConstraint}]

Segment	Description	Examples
{ROOT}	Match root type (see table below)	SET, HAL, QTR, PER, RND, FRM, MAP, MAT, INN
{count}	Number of segments	3, 5, 7, 12
X	Exactly this many segments (not best-of)	SET7X = exactly 7 sets
A	Aggregate scoring across segments	HAL2A = 2 halves, aggregate
-S:	Segment (set) format specification	-S:6/TB7, -S:T10P, -S:TB11, -S:O3
-G:	Game-level format within segments	-G:3C, -G:TN3D
-F:	Final segment format (when different)	-F:TB10, -F:6/TB7@12
-M:	Match-level constraint	-M:T50 (50-minute match time cap)

Simplified Form

Single-set timed formats can use a shortened form:

T{minutes}[P|G]

Examples: T20 (20-minute timed), T10P (10-minute points-based).

Match Root Types

Root	Sport / Concept	Example
SET	Tennis, padel, pickleball, volleyball, table tennis, badminton, squash, racquetball, fencing	SET3-S:6/TB7
HAL	Soccer, handball, NCAA basketball	HAL2A-S:T45
QTR	Basketball (NBA/FIBA), water polo, lacrosse	QTR4A-S:T12
PER	Ice hockey, wrestling	PER3A-S:T20
RND	Boxing, MMA	RND12A-S:T3
FRM	Table tennis (best-of-7+), badminton	FRM7-S:TB11
MAP	Esports (CS2, Valorant)	MAP3-S:TB13
MAT	Multi-match formats	reserved
INN	Innings-based sports (baseball, wiffle ball)	INN4XA-S:O3-M:T50

Backward Compatibility

When the root is SET (the default), it is omitted from the parsed object. Non-SET roots are included as matchRoot in the parsed result. This ensures all existing tennis/pickleball/padel format code consumers continue to work unchanged.

Set Format Specification (-S:)

The -S: section describes how each segment is scored:

Pattern	Description	Example
{games}	Games to win set	-S:6 (first to 6, no tiebreak)
{games}/TB{points}	Games with tiebreak	-S:6/TB7 (tiebreak to 7 at 6-6)
{games}/TB{points}@{at}	Tiebreak at specific count	-S:4/TB5@3 (TB at 3-3)
{games}NOAD	No-advantage games	-S:6NOAD (no deuce)
{games}WB{n}	Win-by override (no-tiebreak sets only)	-S:5WB1 (first to 5 wins, e.g. TYPTI: 4–5, 1–5)
{games}NOADWB{n}	NoAD games + win-by override	-S:4NOADWB1
TB{points}	Tiebreak-only set	-S:TB11 (first to 11, win by 2)
TB{points}NOAD	No-deuce tiebreak set	-S:TB15NOAD
TB{points}@{modifier}	Tiebreak with modifier	-S:TB21@RALLY
TB{points}NOAD@{modifier}	No-deuce tiebreak with modifier (NOAD first)	-S:TB11NOAD@RALLY
T{minutes}	Timed set (games-based)	-S:T20
T{minutes}P	Timed set (points-based)	-S:T10P
T{minutes}G	Timed set (games-based, explicit)	-S:T10G (same as -S:T10)
T{minutes}/TB{points}	Timed set, a tiebreak if level at time	-S:T20/TB7
T{minutes}@{modifier}	Timed set with modifier	-S:T20@RALLY
O{outs}	Outs-based segment (baseball/wiffle ball)	-S:O3 (3 outs per team per inning)

@RALLY is the one modifier the engine acts on: rally scoring, where every rally scores whoever served. Pickleball plays it — SET3-S:TB11@RALLY is best of three rally games to 11, win by two, and SET3-S:TB11NOAD@RALLY the same won by one. Without it a pickleball game is scored side-out: only the serving side scores. NOAD is written before the modifier; a modifier cannot contain NOAD, so TB11@RALLYNOAD is refused rather than read as a modifier named RALLYNOAD.

Game Format Specification (-G:)

The -G: section describes game-level scoring within each set:

Pattern	Description	Example
TN	Traditional tennis/padel game scoring (0-15-30-40)	-G:TN (explicit traditional)
TN{n}D	Traditional with deuce cap	-G:TN3D (Star Point: decisive at 3rd deuce)
{count}C	Consecutive points to win a game	-G:3C (3 consecutive points)
{count}C{n}D	Consecutive with deuce cap	-G:3C3D

Deuce Spec ({n}D)

The {n}D suffix caps the number of deuce cycles before a decisive point:

Code	Meaning
1D	Golden point — decisive at 1st deuce (equivalent to NOAD)
3D	Star Point (Padel 2026) — up to 2 advantages, decisive at 3rd deuce
(none)	Unlimited advantages (traditional)

Match Constraint Specification (-M:)

The -M: section describes match-level constraints that apply across all segments:

Pattern	Description	Example
T{minutes}	Match time cap (total game clock)	-M:T50 (50-minute match time cap)

Unlike segment-level timed formats (-S:T45) where each segment is independently timed, a match constraint applies a single clock across the entire match. For example, INN4XA-S:O3-M:T50 means the game ends when either all 4 innings are complete or 50 minutes elapse, whichever comes first.

Match-Level Modifiers

Modifier	Description	Example
X	Exactly N segments (not best-of)	SET4X-S:T10P
A	Aggregate scoring across all segments	SET7XA-S:T10P, HAL2A-S:T45
XA	Combined: exactly N, aggregate	SET7XA-S:T10P (INTENNSE format)

In an XA format, -F: describes the sudden-death decider that settles level aggregate totals (SET3XA-S:T10-F:TB1). The decider is not one of the N sets: it is set N + 1, played only when the totals are level, so -F: governs set N + 1 and never set N (since 7.5.0). See aggregateDeciderSetNumber / finalSetGoverns.

parse and stringify

import { matchUpFormatCode } from 'tods-competition-factory';

const matchUpFormat = 'SET3-S:6/TB7';

// validate matchUpFormat codes
const valid = matchUpFormatCode.isValidMatchUpFormat({ matchUpFormat });

// parse matchUpFormat codes into an object representation
// tiebreakFormat and tiebreakSet are mutually exclusive
const {
  bestOf,
  matchRoot, // only present for non-SET roots (e.g., 'HAL', 'QTR', 'INN')
  aggregate, // true when match-level A modifier is present
  gameFormat, // { type: 'TRADITIONAL', deuceAfter: 3 } or { type: 'CONSECUTIVE', count: 3 }
  matchUpConstraint, // { timed: true, minutes: 50 } for -M:T50
  setFormat: {
    setTo,
    tiebreakAt,
    tiebreakFormat: { tiebreakTo },
    tiebreakSet: { tiebreakTo },
    outs, // number of outs per team per inning (for -S:O3)
  },
  finalSetFormat: {
    setTo,
    tiebreakAt,
    tiebreakFormat: { tiebreakTo },
    tiebreakSet: { tiebreakTo },
  },
} = matchUpFormatCode.parse(matchUpFormat);

// stringify object representation
const result = matchUpFormatCode.stringify({
  bestOf: 1,
  setFormat: { timed: true, minutes: 20 },
});

See also: matchUpFormat Governor for detailed API documentation including return types, parameters, and edge cases.

matchUpFormat discovery

In CODES, a drawDefinition is a collection of structures. For example, a MAIN structure and a CONSOLATION structure are considered to be part of the same drawDefinition because they have a logical relationship whereby participants move from one structure to another.

 tournament.events[].drawDefinitions[].structures[].matchUps[]

An application using the Competition Factory can request the matchUpFormat for a given matchUp and the factory engine will traverse the hierarchy from bottom up looking to see at what level a matchUpFormat has been defined. This method will also return any matchUpFormat codes encountered in the hierarchy within which a matchUp is found:

const { matchUpFormat } = engine.getMatchUpFormat({
  matchUpId,
  drawId,
});

To set the matchUpFormat at each level:

engine.setMatchUpFormat({
  matchUpFormat,
  structureId, // optional
  eventId, // optional
  drawId, // optional
});

The matchUpFormat for a matchUp is set at the time of score entry:

engine.setMatchUpStatus({
  matchUpFormat,
  matchUpId,
  outcome,
  drawId,
});

Cross-Sport Format Reference

Racquet Sports

Tennis

Format	Code	Notes
Standard match	SET3-S:6/TB7	Best of 3 sets, tiebreak to 7 at 6-6
Grand Slam	SET5-S:6/TB7	Best of 5 sets
ATP Doubles	SET3-S:6/TB7-F:TB10	Final set is match tiebreak to 10
Wimbledon 2019	SET5-S:6/TB7-F:6/TB7@12	Final set tiebreak at 12-12
Australian Open 2019+	SET5-S:6/TB7-F:6/TB10	Final set tiebreak to 10
Short sets	SET3-S:4/TB7	Sets to 4
Fast4	SET3-S:4/TB5@3	Tiebreak at 3-3
Pro set	SET1-S:8/TB7	Single set to 8
College pro set	SET1-S:8/TB7@7	Tiebreak at 7-7
World Team Tennis	SET5-S:5NOAD/TB9NOAD@4	NoAD games and tiebreaks
Timed 20 min	T20	Simplified timed format
Points-based timed	T10P	10-minute points-based

INTENNSE (Timed Aggregate Tennis)

Format	Code	Notes
Standard INTENNSE	SET7XA-S:T10P	Exactly 7 timed sets, aggregate, points-based
Shortened	SET5XA-S:T10P	Exactly 5 timed sets, aggregate, points-based

TYPTI

Format	Code	Notes
Standard	SET5-S:5-G:3C	5 sets to 5 points, 3 consecutive points per game
Shortened	SET3-S:4-G:2C	3 sets to 4, 2 consecutive

Pickleball

Format	Code	Notes
USA Pickleball standard	SET3-S:TB11	Best of 3 to 11, win by 2
Rally scoring to 11	SET3-S:TB11@RALLY	Rally modifier
Traditional to 15	SET3-S:TB15	Older format
No-deuce to 15	SET3-S:TB15NOAD	First to 15 wins
Traditional to 21	SET3-S:TB21	Outdoor/recreational
Rally to 21	SET3-S:TB21@RALLY	Rally scoring
No-deuce rally to 21	SET3-S:TB21NOAD@RALLY	No-deuce rally
MLP (Major League Pickleball)	SET5-S:TB21@RALLY-F:TB15@RALLY	4 games to 21, 5th to 15
Single game tiebreaker	SET1-S:TB11@RALLY	MLP singles format

A pickleball game is a tiebreak set — a race to a target with no games beneath it. Two tokens carry the rules that differ between pickleball variants:

• @RALLY — rally scoring: every rally scores a point regardless of who served. It is scoring-significant, not cosmetic: the scoring engine skips server derivation under it. Absent the modifier the format is traditional side-out scoring, where only the serving side can score.
• NOAD — sudden death at the target (win by 1). Absent it, a game continues past the target until a side leads by two.

Named presets for these are published as fixtures.matchUpFormats.FORMAT_PICKLEBALL*, and fixtures.competitionFormats.PICKLEBALL_STANDARD carries the parts a format code cannot express — server rule, timeouts, penalties, and the sport's point vocabulary (including non-volley-zone faults).

Padel

Format	Code	Notes
Standard	SET3-S:6/TB7	Same as tennis
Golden point (no advantage)	SET3-S:6NOAD/TB7	Premier Padel Tour
Short sets	SET3-S:4/TB7	Shortened format
With match tiebreak	SET3-S:6/TB7-F:TB10	Final set tiebreak
Golden point + short + MTB	SET3-S:4NOAD/TB5@3-F:TB10	Exhibition format
Star Point (2026)	SET3-S:6/TB7-G:TN3D	Decisive at 3rd deuce
Golden point (deuce cap)	SET3-S:6/TB7-G:TN1D	Decisive at 1st deuce
Star Point + match tiebreak	SET3-S:6/TB7-G:TN3D-F:TB10	Star Point + final TB

Squash

Format	Code	Notes
Modern PAR-11	SET5-S:TB11	Best of 5 to 11, win by 2
Women's/junior	SET3-S:TB11	Best of 3 to 11
Old English scoring	SET5-S:TB9	Best of 5 to 9
Traditional to 15	SET5-S:TB15	Hand-in/hand-out scoring

Badminton

Format	Code	Notes
Standard BWF	SET3-S:TB21	Best of 3 to 21, win by 2
Single game	SET1-S:TB21	Exhibition/qualifier
BWF experimental	SET5-S:TB11	Best of 5 to 11

Table Tennis

Format	Code	Notes
Standard	SET5-S:TB11	Best of 5 to 11
Shortened	SET3-S:TB11	Best of 3 to 11
Olympic/World final	FRM7-S:TB11	Best of 7 (uses FRM root since >5)
Old rules	SET5-S:TB21	Best of 5 to 21

Racquetball

Format	Code	Notes
Standard	SET3-S:TB15-F:TB11	Best of 3 to 15, tiebreaker to 11
Pro	SET5-S:TB15-F:TB11	Best of 5 to 15, tiebreaker to 11
Single game	SET1-S:TB15	Single rally game

Non-Racquet Sports

Volleyball

Format	Code	Notes
Indoor	SET5-S:TB25-F:TB15	Best of 5 to 25, final to 15
Beach	SET3-S:TB21-F:TB15	Best of 3 to 21, final to 15
Single set	SET1-S:TB25	Training/exhibition

Fencing

Format	Code	Notes
Pool bout	SET1-S:TB5	Single game to 5 touches
Direct elimination	SET1-S:TB15	Single game to 15 touches
Team relay	SET3-S:TB5	Best of 3 bouts to 5

Soccer / Football

Format	Code	Notes
Standard	HAL2A-S:T45	2 halves of 45 min, aggregate
Youth	HAL2A-S:T30	2 halves of 30 min
Extra time	HAL2A-S:T15	2 halves of 15 min

Basketball

Format	Code	Notes
NBA	QTR4A-S:T12	4 quarters of 12 min
FIBA	QTR4A-S:T10	4 quarters of 10 min
NCAA	HAL2A-S:T20	2 halves of 20 min
3x3	QTR1A-S:T10	Single 10-min period

Ice Hockey

Format	Code	Notes
Standard	PER3A-S:T20	3 periods of 20 min
Overtime	PER1A-S:T5	Single 5-min period

Combat Sports

Format	Code	Notes
Boxing championship	RND12A-S:T3	12 rounds of 3 min
Boxing undercard	RND4A-S:T3	4 rounds of 3 min
MMA standard	RND3A-S:T5	3 rounds of 5 min
MMA championship	RND5A-S:T5	5 rounds of 5 min

Wiffle Ball / Baseball

Format	Code	Notes
BLW standard	INN4XA-S:O3-M:T50	4 innings, 3 outs, aggregate, 50-min match cap
BLW (no time cap)	INN4XA-S:O3	4 innings, 3 outs, aggregate
World Wiffle Ball	INN6XA-S:O3	6 innings, 3 outs, aggregate
Timed innings (approx.)	INN4XA-S:T12	Timed approximation (~12 min/inning)

Other Sports

Sport	Code	Notes
Handball	HAL2A-S:T30	2 halves of 30 min
Water polo	QTR4A-S:T8	4 quarters of 8 min
Lacrosse	QTR4A-S:T15	4 quarters of 15 min
Wrestling	PER2A-S:T3	2 periods of 3 min
CS2 / Valorant	MAP3-S:TB13	Best of 3 maps, 13 rounds

Note on NoAD in Tiebreak Formats (Non-Standard Extension)

Non-Standard Extension

The use of NOAD applied to tiebreak formats (e.g., TB10NOAD) is a non-standard extension for recreational tennis use and is not part of the official ITF TODS specification.

Standard Behavior

• NOAD is officially documented only for game-level scoring (e.g., SET3-S:6NOAD)
• All standard tennis tiebreak formats require win-by-2:
  • 7-point tiebreak: first to 7, win by 2 → valid scores: 7-5, 8-6, 9-7, etc.
  • 10-point match tiebreak: first to 10, win by 2 → valid scores: 10-8, 11-9, 12-10, etc.

Non-Standard Extension: NOAD in Tiebreaks

When NOAD is applied to a tiebreak format (e.g., SET3-S:6/TB7@5-F:TB10NOAD):

• Behavior: Changes winBy from 2 to 1 (first to reach tiebreakTo wins immediately)
• Example: TB10NOAD allows scores like [10-9], [10-8] (winner needs exactly 10 points)
• Use case: Recreational leagues and club play for time management
• Not recognized by: ITF, ATP, WTA, USTA official formats

Implementation Note

This implementation supports tiebreakSet.NoAD to enable recreational formats, but developers should be aware this is an extension beyond the CODES specification. When interoperating with other CODES-compliant systems, tiebreak NOAD notation may not be recognized or may be interpreted differently.

Win-By Override (WB{n} on No-Tiebreak Sets)

The WB{n} modifier overrides the default game-margin required to win a set when no tiebreak is configured. It is only accepted on standard sets that omit a tiebreak (/TB…); pairing it with a tiebreak is rejected as syntactically invalid.

Default Behavior

• Sets that omit a tiebreak (e.g., -S:6) are advantage sets — a side must win by two games (6-4, 7-5, 8-6, …). This is the implicit default and produces winBy = 2.
• The WB{n} modifier overrides the implicit win-by, so the parsed setFormat.winBy reflects the explicit value.

WB1 — First Past the Post

WB1 means the first side to reach setTo games wins outright, regardless of margin.

Format	Parsed setFormat	Example legal scores
SET3-S:5WB1	{ setTo: 5, noTiebreak: true, winBy: 1 }	5–0, 5–4, 4–5, 1–5
SET5-S:5WB1-G:3C	TYPTI win-by-1 variant: 3 consecutive points per game	5–4, 4–5, 1–5
SET3-S:4NOADWB1	{ setTo: 4, NoAD: true, noTiebreak: true, winBy: 1 }	NoAD games, fast set

Canonical Stringify

• WB2 is the implicit default and is elided during stringify (SET3-S:5WB2 stringifies as SET3-S:5). SET3-S:5WB2 is still a valid, equivalent spelling.
• Only winBy values that differ from the default (typically WB1) appear in canonical output.
• Modifier ordering is canonical: {games} → NOAD → WB{n}. The parser rejects WB-before-NOAD to keep canonical form unambiguous.

Use Case: TYPTI Win-By-1 Rules

In TYPTI rule variants where a set is won by reaching the target game count without any margin requirement, use the WB1 modifier alongside the existing -G:{n}C consecutive-points game format:

SET5-S:5WB1-G:3C

This expresses: best of 5 sets, sets to 5 games (first to 5 wins, e.g. 1–5, 4–5, 5–4), 3 consecutive points per game.

Combined Rally Totals

SET1-S:P32 represents one segment ending when both sides' rally scores total 32. P32DP adds a deciding rally only after a tied base segment; P32WB2 continues from that tie until a two-point margin. An unequal result at the base total is complete under every variant. Plain P32 permits a completed 16–16 without a winner.

Even totals with the tie-allowed rule are refused in elimination structures that advance a match winner, both during draw generation and format changes. Odd totals, DP and WB cannot end tied. A winnerless COMPLETED result is also refused in winner-advancing structures. Ordinary round-robin tie tally semantics remain a separate policy decision.

The P segment is restricted to SET1, without final-set, game, aggregate or timed modifiers. Scores use side1Score and side2Score; mixed tiebreak or game-point fields are refused. See live scoring support.