tieFormats

Overview

A tieFormat both describes collections of singles and doubles tieMatchUps which are part of a { matchUpType: TEAM } matchUp, and defines the target value which must be achieved in order to win the matchUp.

There can be any number of collectionDefinitions in a tieMatchUp. For instance, there can be "Men's Singles", "Men's Doubles", "Womens's Singles", "Women's Doubles", and "Mixed Doubles".

Each collectionDefinition defines how many matchUps are in the collection, the matchUpType (SINGLES or DOUBLES), the matchUpFormat to be used for scoring, and how value is assigned to each matchUp. collectionDefinitions can optionally define category and gender.

Value Considerations

The score of a TEAM matchUp is the summation of the value assigned for the wins on each side. Value can be assigned in numerous ways. When there is no winCriteria specified, the valueGoal defaults to one more than half of the potential value within scope (which can be the tieFormat, a collectionDefinition, or a collectionGroup).

• matchUpValue - specified value is awarded for each matchUp win
• setValue - specified value is awarded for each set win
• collectionValue - specified value is awarded for winning a collection
• collecitonValueProfile - unique values are specified for each collectionPosition within a collection
• groupValue - specified value is awarded for reaching a valueGoal by accumulating value across collections in the group
• scoreValue - specified value is awarded for each sideScore (typically 1, typically used with aggregateValue formats)

See tieFormat type definitions

tieFormat Use

Generating Draws

The generation of drawDefinitions requires a tieFormat to determine how many tieMatchUps for each collection are contained in the matchUp between two teams. When tieMatchUps are generated they are assigned a collectionId and a collectionPosition. If there are six tieMatchUps in a collection, they will be assigned collectionPositions 1-6.

Mapping lineUps

A tieFormat determines the relationship between a team's lineUp and the tieMatchUps within a matchUp by defining the mapping between collectionIds, collectionPositions and participant collectionAssignments.

tieFormat Example

• each SINGLES matchUp has a value of 1
• the entire DOUBLES Collection has a value of 1
• the valueGoal is 4

const tieFormat = {
  winCriteria: {
    valueGoal: 4, // the value that must be achieved to win the match
  },
  collectionDefinitions: [
    {
      collectionId: 'singlesCollectionId',
      collectionGroupNumber: 1, // optional, if there are groups
      collectionName: 'Singles',
      matchUpFormat: 'SET3-S:6/TB7',
      matchUpType: SINGLES,
      matchUpCount: 6,
      matchUpValue: 1, // value awarded for each matchUp win
    },
    {
      collectionId: 'doublesCollectionId',
      collectionGroupNumber: 1, // optional, if there are groups
      collectionName: 'Doubles',
      collectionValue: 1, // value awarded for winning one more than half of the matchUps in the collection
      matchUpFormat: 'SET3-S:6/TB7-F:TB10',
      matchUpType: DOUBLES,
      matchUpCount: 3,
    },
  ],
  // optional group details
  collectionGroups: [
    {
      groupName: 'Day 1', // used to group collections, e.g. Laver Cup
      groupNumber: 1,
    },
  ],
};

tieFormat and lineUp propagation

tieFormats can be attached to a tournament record at multiple levels wthin the hierarchy event > drawDefinition > structure > matchUp. This means that when a tieFormat is not present on a matchUp the definition is resolved by walking the hierarchy. When a matchUp is scored, the appropriate tieFormat is attached to the matchUp. This is necessary because at any point in a structure or drawDefinition the scoped tieFormat may be edite/changed; for instance, if there is a rain delay, the format may be shortened for matchUps which have not yet been played. The mapping between participants in a lineUp must be preserved for matchUps which are IN_PROGRESS or COMPLETED.

As TEAM participants progress through draw structures the most recent lineUp is saved (via an extension on the drawDefinition) such that it can be propagated to subsequent matchUps. When a matchUp is scored or the lineUp changes, the lineUp is saved directly to the target matchUp.

Score source — derived vs reported

By default a TEAM matchUp score is derived: it is computed from the collection matchUps ("lines") beneath it. Many federations, however, publish only the team result — "3–2", or a games aggregate — and never the per-line detail. Those ties have no lines to derive from, and an empty scorecard beneath them is not missing data entry; it is the complete truth about what was published.

scoreSource on a tieFormat states which of the two applies:

Value	Meaning
DERIVED	Default. The tie score is computed from the lines
REPORTED	The aggregate result is authoritative and the lines are unpopulated by design

const tieFormat = {
  tieFormatName: 'LEAGUE_REPORTED',
  scoreSource: 'REPORTED',
  winCriteria: { valueGoal: 3 },
  collectionDefinitions: [/* still describes WHAT was played, even though the results are not published */],
};

Because scoreSource lives on the tieFormat, it resolves through the same hierarchy as everything else in this document — event > drawDefinition > structure > matchUp. A federation that never publishes line detail declares it once on the event rather than per tie, and an individual tie can still override it where detail does exist.

When the resolved score source is REPORTED:

• the reported score and winningSide are preserved — a recalculation will not overwrite them with a derivation from empty lines;
• no tieMatchUps are generated. Lines that can never be filled are not materialized: for a federation season that is the bulk of the record's weight, and it removes the ambiguity of an empty scorecard. The collectionDefinitions still describe what was played — only the unfillable matchUps are absent;
• the read model projects score_source: 'REPORTED' on the TIE row, so a consumer can render "no line detail published" rather than an empty scorecard awaiting entry (see cast).

Relationship to disableAutoCalc

disableTieAutoCalc sets disableAutoCalc on a single TEAM matchUp and has the same protective effect. The two express different things:

• disableAutoCalc — per-matchUp state: "this particular tie's score was entered by hand". Cleared when the score is removed.
• scoreSource: REPORTED — declarative and inherited: "ties under this format never have line detail". Carries no per-matchUp state.

Use disableAutoCalc for a one-off manual override; use scoreSource to describe how a competition publishes its results.

Related

• tieFormat Governor — methods for creating, modifying, deduplicating, and validating tieFormats
• tieMatchUps — the individual matchUps within a TEAM matchUp
• lineUp — how participants are assigned to collection positions