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.

Interactive Example

Use the embedded component to dynamically generate matchUpFormat codes:

TODS MatchUp Format Code Generator

SET3-S:6/TB7

Scoring

• Standard Advantage
• Best of 3 Sets to 6 with Advantage

Best Of

3

Ad

Sets

to 6

TB to: 7

@ 6

Win by 2

Tiebreak

Final Set

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,
  setFormat: {
    setTo,
    tiebreakAt,
    tiebreakFormat: { tiebreakTo },
    tiebreakSet: { tiebreakTo },
  },
  finalSetFormat: {
    setTo,
    tiebreakAt,
    tiebreakFormat: { tiebreakTo },
    tiebreakSet: { tiebreakTo },
  },
} = matchUpFormatCode.parse(matchUpFormat);

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

matchUpFormat discovery

In TODS, 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,
});

parse and stringify

The Competition Factory utilizes matchUpFormatCode functions primarily for validation, but also in the calculation of Round Robin results when determining group finishing positions.

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
const {
  bestOf,
  setFormat: {
    setTo,
    tiebreakAt,
    tiebreakFormat: { tiebreakTo },
  },
  finalSetFormat: {
    setTo,
    tiebreakAt,
    tiebreakFormat: { tiebreakTo },
  },
} = matchUpFormatCode.parse(matchUpFormat);

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

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 Tennis Open Data Standards (TODS) specification.

Standard TODS 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 TODS specification. When interoperating with other TODS-compliant systems, tiebreak NOAD notation may not be recognized or may be interpreted differently.