How to include multiple identifiers

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.

When exchanging data between different sources it is common that each source uses a different identifier for the same entity and there is no universal identifier. TODS allows entities to contain multiple ids to facilitate easier data transfer.

Primary identifier

Each entity in a TODS message has an attribute for the identifier. For example, every Tournament entity must have a TournamentId. This primary identifier is always the identifier used by the source. The source knows this is unique.

Each Id in TODS sits in a URN-style namespace. Tennis:<Entity>:<Provider>:<Identifier>

Let's consider a Tournament exchanged between two sources Source A (whose ProviderId is SOURCE-A) and Source B (SOURCE-B).

Source A could send a message like this:

XML

<Tennis>
	<Header>
		<ProviderId>SOURCE-A</ProviderId>
		<Date>2019-04-17</Date>
		<DataStandardsVersion>Draft 0.3</DataStandardsVersion>
	</Header>
		<Tournament>
			<TournamentId>T182747</TournamentId>
			<Name>Junior Easter Cup</Name>
			…
		</Tournament>
</Tennis>

Json

{
	"Tennis": {
		"Header": {
			"ProviderId": "SOURCE-A",
			"Date": "2019-04-17",
			"DataStandardsVersion": "Draft 0.3"
		},
		"Tournament": {
			"TournamentId": "T182747",
			"Name": "Junior Easter Cup"
		}
	}
}

The ProviderId in the header tells us which provider all the primary ids are from. So this Tournament is Tennis:Tournament:SOURCE-A:T182747

Source B receives this Tournament, adds it to it's systems and generates its own id for it. If we assume Source A is the national association and Source B is the organiser we can imagine that Source B will now update the Tournament with more information and send that update to Source A.

Source B will set the Primary Identifier to its own id - but it wants to make sure that Source A knows this is an update to an existing Tournament. So Source B will include an additional identifier.

XML

<Tennis>
	<Header>
		<ProviderId>SOURCE-B</ProviderId>
		<Date>2019-04-18</Date>
		<DataStandardsVersion>Draft 0.3</DataStandardsVersion>
	</Header>
		<Tournament>
			<TournamentId>ghttERaaI</TournamentId>
			<Ids>
				<Id>SOURCE-A:T182747</Id>
			</Ids>
			<Name>Junior Easter Cup</Name>
			…
		</Tournament>
</Tennis>

Json

{
	"Tennis": {
		"Header": {
			"ProviderId": "SOURCE-B",
			"Date": "2019-04-18",
			"DataStandardsVersion": "Draft 0.3"
		},
		"Tournament": {
			"TournamentId": "ghttERaaI",
			"Ids": {
				"Id": "SOURCE-A:T182747"
			},
			"Name": "Junior Easter Cup",
		}
	}
}

The Primary Identifier has been set to Source B's (Tennis:Tournament:SOURCE-B:ghttERaaI in full) and Source A's identifier has been included too. Both sources now know this is a single Tournament and how each identifies it.

This is not limited to two identifiers, Sources may also want to include other ids. Let's assume that this Tournament is also exchanged with the ITF. Source B could also include that identifier when sending messages about the Tournament.

XML

<Tennis>
	<Header>
		<ProviderId>SOURCE-B</ProviderId>
		<Date>2019-04-18</Date>
		<DataStandardsVersion>Draft 0.3</DataStandardsVersion>
	</Header>
		<Tournament>
			<TournamentId>ghttERaaI</TournamentId>
			<Ids>
				<Id>SOURCE-A:T182747</Id>
				<Id>ITF:2019-J-O-NOR</Id>
			</Ids>
			<Name>Junior Easter Cup</Name>
			…
		</Tournament>
</Tennis>

Json

{
	"Tennis": {
		"Header": {
			"ProviderId": "SOURCE-B",
			"Date": "2019-04-18",
			"DataStandardsVersion": "Draft 0.3"
		},
		"Tournament": {
			"TournamentId": "ghttERaaI",
			"Ids": {
				"Id": [
					"SOURCE-A:T182747",
					"ITF:2019-J-O-NOR"
				]
			},
			"Name": "Junior Easter Cup",
		}
	}
}

Related Information

Go back to Tennis Open Data Standards home page.