Which SportsML version does this map to?
The mapping uses SportsML 3.1, the newest version on iptc.org. IPTC released it in June 2019. The tennis part of the standard is a plugin schema, sportsml-specific-tennis.xsd, which the main schema includes. Both files carry IPTC's CC BY 4.0 notice.
The mapping was read from the schema files, the tennis plugin documentation, the core schema documentation and IPTC's own tennis example. It is our reading. IPTC has not reviewed it.
Our own comparison of tennis score notation formats sets SportsML beside three other formats.
How does each Score field map to SportsML?
The rows follow the Score schema in the spec, every field in its order. Each SportsML name links to the section of IPTC's documentation that defines it.
| Score field | SportsML 3.1 | Notes |
|---|---|---|
sets | player-stats/ | Sets won. Each player gets the value from their slot of the array. IPTC's Davis Cup example puts sets won in this attribute. |
games | stats-tennis-set/stats-tennis-set/sub-score/ | One stats-tennis-set per set and player. IPTC's example also writes the same numbers as sub-score. SportsML has no match tie-break, so the fixtures write one as a set won 1-0, with its points in score-tiebreaker. |
points | action/action/event-metadata-tennis/event-metadata-tennis/ | On an action and on event-metadata-tennis the game score is ordered by server, and ours by player. 0 becomes love and AD becomes ad. The fixtures write 40-40 as 40 and 40, though the list also has deuce. A tie-break count has no code, so tie-break points carry no game score. |
server | event-metadata-tennis/event-metadata-tennis/participant/ | server-idref exists only on event-metadata-tennis. On an action the server is a participant with a role. IPTC publishes no tennis role codes, so the fixtures use ltapirole:server. A null server leaves the attribute out. |
is_tiebreak | No direct equivalent | No attribute says the current game is a tie-break. score-tiebreaker gives a set's tie-break points, but not whether the breaker is still being played. |
win_probability_p1 | No direct equivalent | A model output. SportsML has no field for it. wagering-odds holds a bookmaker's line, and the generic stat element would need a code of our own. |
danger | No direct equivalent | The value the break_point frame calls prob_swing. |
win_probability_p1_model | No direct equivalent | The same model read without the market-prior anchor. |
win_probability_meta | No direct equivalent | The model version and the time the two probabilities were made. |
timestamp | No direct equivalent | Our clock, refreshed while a source keeps sending the same state. action/@date-time is when the play took place on court, which this field never claims. last-modified is closest, but a state sent again is not a change to the record. |
accepted_at | action/ | The instant we accepted the state, stamped once. IPTC describes created as the time the action record was made. |
sequence | action/ | Our per-match accept counter. In the fixtures, the action for a point carries the sequence of the state that point produced. |
age_seconds | No direct equivalent | Seconds since the score last changed. |
stale | No direct equivalent | Our staleness verdict on a live match. |
observed_age_seconds | No direct equivalent | Seconds since any source last confirmed the state. |
sources_count | No direct equivalent | How many sources reported the match in the last 60 seconds. |
changing_sources_count | No direct equivalent | How many sources changed the score in the last 300 seconds. |
corroborated | No direct equivalent | Whether a second source sent this exact state. |
corroborated_age_seconds | No direct equivalent | Seconds since that second source confirmed it. |
detail | No direct equivalent | Why something is withheld, for example a null games array. |
verdict | No direct equivalent | Why a read is not the newest state we judged, for example a withdrawn state. |
Read the arrays the usual way. sets, games and points put
player 1 first and player 2 second.
Which match and point fields does SportsML cover?
A SportsML match document also says who played, how the match ended and what happened on each point.
These fields come from the Match, LivePoint and HistoryTapeRow
schemas.
| Field | SportsML 3.1 | Notes |
|---|---|---|
Match.players | playerplayer-metadata/ | The fixtures give the two players the ids p1 and p2. |
Match.format | event-metadata-tennis/ | BO3 is 3 and BO5 is 5. |
Match.status | event-metadata/ | The codes come from speventstatus. An upcoming match is pre-event, live is mid-event and cancelled is canceled. A completed match is post-event unless its outcome says otherwise. |
Match.outcome | event-metadata/event-metadata/event-metadata/event-metadata/ | IPTC has no code for a retirement or a default. The fixtures mark retired, walkover and default as forfeited and add the reason withdrawal to the first two. A default also gets the outcome type authority-decision. The note holds our outcome value. The fixtures do not cover abandoned or unresolved. |
Match.winner | player-stats/ | speventoutcome win for the winner, loss for the other player. |
Match.withdrew | No direct equivalent | The fixtures show it only through the loser's loss and the note. |
LivePoint.winner | participant/ | The point winner is a participant too. IPTC's Davis Cup example uses a vendor code, ball-winner. The fixtures use ltapirole:point-winner. |
LivePoint.set | action/event-metadata-tennis/ | The set the point was played in. |
LivePoint.game | action/event-metadata-tennis/ | 13 is the game number of a tie-break at six all. The fixtures count a match tie-break as game 1. |
LivePoint.serve | action/event-metadata-tennis/ | It takes first or second on event-metadata-tennis. On an action it takes a code, and IPTC publishes no list for it. The fixtures leave it out. |
HistoryTapeRow.tiebreak_final | stats-tennis-set/ | The breaker's closing score, on the row that closes a tie-break set. |
| Court time of a point | action/ | We publish no court time. LivePoint.ts is when our pipeline committed the state. |
Worked example: a match decided by a match tie-break
Player A and Player B are synthetic. They split the first two sets 6-4 and 4-6. A ten-point match tie-break replaces the third set and Player A wins it 10-8.
These are the last two score states, at 9-8 in the breaker and after the match point. The deciding set's slot holds the breaker's points while it is played. The last state shows the match over.
[
{"sets": [1, 1], "games": [[6, 4, 9], [4, 6, 8]], "points": ["9", "8"], "server": 1, "is_tiebreak": true, "timestamp": "2026-01-05T10:11:20Z", "accepted_at": "2026-01-05T10:11:20Z", "sequence": 318},
{"sets": [2, 1], "games": [[6, 4, 10], [4, 6, 8]], "points": ["0", "0"], "server": null, "is_tiebreak": false, "timestamp": "2026-01-05T10:12:00Z", "accepted_at": "2026-01-05T10:12:00Z", "sequence": 319}
]
The same match as a SportsML document. The third set is written as a set won 1-0, with the breaker's
points in score-tiebreaker. The action is the match point.
<?xml version="1.0" encoding="UTF-8"?>
<!-- SYNTHETIC tennis scoring fixture. No real players, matches or results.
Fixture: 02-match-tiebreak. Licence: CC BY 4.0, https://creativecommons.org/licenses/by/4.0/
From the Live Tennis API SportsML fixtures, https://github.com/livetennisapi/openapi/tree/main/examples/sportsml -->
<sports-content xmlns="http://iptc.org/std/nar/2006-10-01/">
<sports-metadata doc-id="ltapi-synthetic-02-match-tiebreak" date-time="2026-01-05T10:12:00Z" language="en">
<catalogRef href="http://www.iptc.org/std/catalog/catalog.IPTC-Sports_1.xml"/>
<sports-title>Synthetic fixture: match tie-break to ten</sports-title>
</sports-metadata>
<sports-event>
<event-metadata event-status="speventstatus:post-event">
<event-metadata-tennis number-of-sets="3"/>
</event-metadata>
<player id="p1">
<player-metadata><name>Player A (synthetic)</name></player-metadata>
<player-stats score="2" event-outcome="speventoutcome:win">
<player-stats-tennis>
<stats-tennis-set set-number="1" score="6"/>
<stats-tennis-set set-number="2" score="4"/>
<stats-tennis-set set-number="3" score="1" score-tiebreaker="10"/>
</player-stats-tennis>
</player-stats>
</player>
<player id="p2">
<player-metadata><name>Player B (synthetic)</name></player-metadata>
<player-stats score="1" event-outcome="speventoutcome:loss">
<player-stats-tennis>
<stats-tennis-set set-number="1" score="4"/>
<stats-tennis-set set-number="2" score="6"/>
<stats-tennis-set set-number="3" score="0" score-tiebreaker="8"/>
</player-stats-tennis>
</player-stats>
</player>
<actions>
<!-- 17 earlier points, one action each, are in the fixture file -->
<action type="sptenaction:point" sequence-number="319" created="2026-01-05T10:12:00Z" set="3" game="1">
<participant idref="p1" role="ltapirole:server"/>
<participant idref="p2" role="ltapirole:receiver"/>
<participant idref="p1" role="ltapirole:point-winner"/>
</action>
</actions>
</sports-event>
</sports-content>
The Score schema says a finished match tie-break is often published as a one-game set, 1-0. The
fixture keeps the breaker's points in that slot instead. Take the winner from sets either way.
Test fixtures for tennis scoring edge cases
The examples/sportsml folder holds six synthetic matches. No player, match or result in them is real. Each fixture is two files. One is the sequence of score states as JSON. The other is the same match as a SportsML document. The fixtures are under CC BY 4.0.
| Fixture | What it covers | States | Files |
|---|---|---|---|
| Deciding-set tie-break at six all | The third set reaches 6-6 and a seven-point tie-break decides it, 9-7. | 17 | JSON SportsML |
| Match tie-break to ten | A ten-point match tie-break replaces the third set and ends 10-8. | 19 | JSON SportsML |
| No-ad games | Two games reach 40-40. One deciding point is a break and the other wins the match. | 15 | JSON SportsML |
| Retirement | Player B retires serving at 15-30 in the second set. | 4 | JSON SportsML |
| Walkover | Player A withdraws before a ball is struck, so the fixture has no score states. | 0 | JSON SportsML |
| Default | Player A is defaulted while serving at advantage Player B, after deuce, in the second set. | 8 | JSON SportsML |
The folder's check script validates every SportsML document against the IPTC schema. It replays each point from the first JSON state with the rules of tennis and compares every state. It also compares the result and the way the match ended.
pip install lxml
python examples/sportsml/check_fixtures.py
The IPTC schema files are vendored unchanged, with their CC BY 4.0 notice and source address. The script refuses to run if one differs from its pinned SHA-256.
Where does SportsML 3.1 leave tennis open?
Writing the fixtures needed a choice in each of these places. Each one is in the published files.
- No match tie-break.
score-tiebreakeris documented as an integer, generally 0 through 7. Nothing says how to write a ten-point breaker that replaces a set. - No scoring format. No attribute says a match uses no-ad games, a final-set tie-break or a match tie-break.
- No code for a tie-break count. The sptengameresult codes are love, 15, 30, 40, game, ad and deuce, so a tie-break point has no score.
- No tennis role codes. An action names the server through a participant role, and
IPTC's example uses vendor codes for it.
server-idrefexists only onevent-metadata-tennis. - One score, two types.
server-scoretakes a code on an action and a plain value onevent-metadata-tennis.setandgameare integers on an action and strings there. - No retirement or default. The event status list has forfeited, and the only status reason is withdrawal. The nearest outcome type for a default is authority-decision.
- Set score wording. The annotation on
stats-tennis-set/@scorereads "Either love, 15, 30, 40, or game". IPTC's own example puts the games won there.