Introduction to the MatchUp

Owned by Scott Dickinson (Deactivated)
Last updated: Jul 28, 2020
4 min read

DRAFT DOCUMENTATION

Please note that this documentation is in draft and is not finalised.

We would encourage you provide any comments, questions, or suggestions for changes by use in-line commenting on this page. To do so simply highlight a section of text and then click on the "Comment" option that appears.

The MatchUp is a key part of the Tennis Open Data Standards - allowing users to record the details of the MatchUp format, the progression of the MatchUp and the result.

1. What is a MatchUp?

A MatchUp entity hold the details of a tennis MatchUp between two players or pairs. It can provide details about how the MatchUp will be played, when the MatchUp will be played, who will play the MatchUp as well as information about what happens during a MatchUp and the final result.

2. MatchUp Schema

To see a graphical representation of the data model (schema) for the MatchUp entity please expand the link below:

 View Match Schema Diagram

3. Creating a MatchUp

The mandatory information required to create a MatchUpentity is a MatchUpId. However we strongly recommend that MatchUpType and MatchUpStatus are also included. If available MatchUpFormat should also be included.

You can create a MatchUp as soon as the Draw (or Tie) that it is part of has been created. It is perfectly normal to create the MatchUp entities before the players are known. Or for MatchUps to have only one side listed - for example when only one semi-final has been played so only one of the finalists is known.

XML 
<MatchUp>
  <MatchUpId>70290C29-A867-4756-8B25-54B32BF011CF</MatchUpId>
  <MatchUpType>SINGLES</MatchUpType>
  <Sides>
    <Side>
      <Number>1</Number>
      <Players>
        <Player>
          <Number>1</Number>
          <Participant>
            <ParticipantID>RND1234567</ParticipantID>
          </Participant>
        </Player>
      </Players>
    </Side>
  </Sides>
</Match>
Json 
{
	"MatchUp": {
		"MatchUpId": "70290C29-A867-4756-8B25-54B32BF011CF",
		"MatchUpType": "SINGLES",
		"Sides": {
			"Side": [
				{
				"Number": "1",
				"Players": {
					"Player": [
					    {
						"Number": "1",
						"Participant": {
							"ParticipantID": "RND1234567"
						}
					}
					]
				}
			}
			]
		}
	}
}

4. MatchUpId

In MatchUpId you must supply your unique identifier for the MatchUp. The value must be unique within the tournament. You can use any value but a unique identifier can easily be created by concatenating the DrawId with information about the draw.

When you’re exchanging information with a client or supplier it is possible that you both have an ID for the MatchUp. To make exchange easier TODS allows for any number of additional IDs to be included with MatchUp. See ‘How to include multiple identifiers’ for more information.

5. MatchUpFormat

The MatchUpFormat is defined by a string that can be decoded my humans and computers to understand how to interpret the result. The coding scheme has been designed to allow for an almost unlimited number of different formats. Some of the more common formats are listed in the MatchUp Format and Score Quick Reference. If none of the available codes are suitable for your MatchUp then you can create the correct code using the information available in Creating a valid MatchFormat code.

6. Adding Sides

As each side in the MatchUp becomes known it can be added to the MatchUp. A side can be a player or a pair (for doubles).

Each side has a number (1 or 2). The decision of which side is 1 is up to users of the TODS but where there are home and away sides the convention is that the home side is 1. When only one side is known it is perfectly valid for it to be side number 2.

Each Side must link back to a Participant listed in the Tournament and use the ParticipantID to do this.

For singles the Participant and the Player will be the same:

XML 
<Sides>
  <Side>
	<Number>1</Number>
	<Score>4-6;1-6</Score>
	<Players>
	  <Player>
		<Number>1</Number>
		<Participant>
		  <ParticipantID>RND1234567</ParticipantID>
		</Participant>
	  </Player>
	</Players>
  </Side>
  <Side>
	<Number>2</Number>
	<Score>6-4;6-1</Score>
	<Players>
	  <Player>
		<Number>1</Number>
		<Participant>
		  <ParticipantID>RND7654321</ParticipantID>
		</Participant>
	  </Player>
	</Players>
  </Side>
</Sides>
Json 
{
	"Sides": {
		"Side": [
			{
				"Number": "1",
				"Score": "4-6;1-6",
				"Players": {
					"Player": [
						{
							"Number": "1",
							"Participant": {
								"ParticipantID": "RND1234567"
							}
						}
					]
				}
			},
			{
				"Number": "2",
				"Score": "6-4;6-1",
				"Players": {
					"Player": [
						{
							"Number": "1",
							"Participant": {
								"ParticipantID": "RND7654321"
							}
						},
						{
							"Number": "1",
							"Participant": {
								"ParticipantID": "RND7654321"
							}
						}
					]
				}
			}
		]
	}
}

For doubles the Side/Participant will link the doubles pair Participant and the Players will link to the Participant entities for each of the individuals.

XML 
<Sides>
  <Side>
	<Number>1</Number>
	<Score>4-6;1-6</Score>
	<Participant>
	  <ParticipantID>RND1234567-RND4567123</ParticipantID>
	  <Members>
		  <Member>
		    <ParticipantID>RND1234567</ParticipantID>
		  </Member>
		  <Member>
		    <ParticipantID>RND4567123</ParticipantID>
		  </Member>
	  </Members>
	</Participant>
	<Players>
	  <Player>
		<Number>1</Number>
		<Participant>
		  <ParticipantID>RND1234567</ParticipantID>
		</Participant>
	  </Player>
	  <Player>
		<Number>2</Number>
		<Participant>
		  <ParticipantID>RND4567123</ParticipantID>
		</Participant>
	  </Player>
	</Players>
  </Side>
  <Side>
	<Number>2</Number>
	<Score>6-4;6-1</Score>
	<Participant>
	  <ParticipantID>RND7654321-RND1237654</ParticipantID>
	  <Members>
		  <Member>
		    <ParticipantID>RND7654321</ParticipantID>
		  </Member>
		  <Member>
		    <ParticipantID>RND1237654</ParticipantID>
		  </Member>
	  </Members>
	</Participant>
	<Players>
	  <Player>
		<Number>1</Number>
		<Participant>
		  <ParticipantID>RND7654321</ParticipantID>
		</Participant>
	  </Player>
	  <Player>
		<Number>2</Number>
		<Participant>
		  <ParticipantID>RND1237654</ParticipantID>
		</Participant>
	  </Player>
	</Players>
  </Side>
</Sides>
Json 
{
	"Sides": {
		"Side": [
			{
				"Number": "1",
				"Score": "4-6;1-6",
				"Participant": {
					"ParticipantID": "RND1234567-RND4567123",
					"Members": {
						"Member": [
							{
								"ParticipantID": "RND1234567"
							},
							{
								"ParticipantID": "RND4567123"
							}
						]
					}
				},
				"Players": {
					"Player": [
						{
							"Number": "1",
							"Participant": {
								"ParticipantID": "RND1234567"
							}
						},
						{
							"Number": "2",
							"Participant": {
								"ParticipantID": "RND4567123"
							}
						}
					]
				}
			},
			{
				"Number": "2",
				"Score": "6-4;6-1",
				"Participant": {
					"ParticipantID": "RND7654321-RND1237654",
					"Members": {
						"Member": [
							{
								"ParticipantID": "RND7654321"
							},
							{
								"ParticipantID": "RND1237654"
							}
						]
					}
				},
				"Players": {
					"Player": [
						{
							"Number": "1",
							"Participant": {
								"ParticipantID": "RND7654321"
							}
						},
						{
							"Number": "2",
							"Participant": {
								"ParticipantID": "RND1237654"
							}
						}
					]
				}
			}
		]
	}
}

7. MatchUp Result

Once the MatchUp is over the Score value can be provided. This is a string, written from the winner’s perspective, that follows the MatchUpFormat. The Score is designed to be human readable but also machine readable so clients of TODS messages can use the information to make calculations and do analysis.

MatchUp Format and Score Quick Reference shows how the write scores for different MatchUpFormat.

Users can choose to provide more detailed breakdown of the progression of the MatchUp using Set elements but it is not mandatory to do so. If Sets are used Score must still be provided.


TODS defines a set of standard attributes that are widely used within tennis. If you need to supply some extra information that doesn’t fit one of the standard attributes you can use an extension.
See ‘Extensions’ for more information.


Related Information


Go back to Tennis Open Data Standards home page.