API Schema
This is the JSON Hyper-Schema used to describe, specify and document the ITTF API. It was last updated on 20 November 2014. You may retrieve the most current schema at anytime from http://api.ittf.com/schema.json
To retrive a specific version of the schema, add the version number to the base url, like so http://api.ittf.com/{version}/schema.json
{
"$schema": "http://json-schema.org/draft-04/hyper-schema",
"definitions": {
"association": {
"$schema": "http://json-schema.org/draft-04/hyper-schema#",
"title": "ITTF API - Association",
"description": "A Table Tennis Association.",
"type": [
"object"
],
"definitions": {
"id": {
"description": "A unique three-letter identifier for this association",
"type": [
"string"
],
"maxLength": 3,
"example": "EGY"
},
"name": {
"description": "The name of this association, usually a country, but not always",
"type": [
"string"
],
"example": "Egypt"
}
},
"properties": {
"id": {
"$ref": "#/definitions/association/definitions/id"
},
"name": {
"$ref": "#/definitions/association/definitions/name"
}
}
},
"game": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Game",
"description": "In Table Tennis a Game is a contest between two Opponents that is usually part of a Match.",
"type": [
"object"
],
"definitions": {
"number": {
"description": "The number that identifies the sequence of this game within a match",
"type": [
"integer"
],
"example": 1
},
"matchId": {
"description": "The unique identifier for the Match to which this Game belongs",
"type": [
"integer"
],
"example": 125798
},
"opponentOne": {
"description": "The first opponent",
"$ref": "#/definitions/opponent"
},
"opponentTwo": {
"description": "The second opponent",
"$ref": "#/definitions/opponent"
},
"table": {
"description": "Name of the Table, usually a number, but left as string to accomodate special names like 'Feature Table' or 'Final Table'",
"type": [
"string"
],
"example": "Table 5"
},
"dateTime": {
"description": "The Date and Time of the game supplied as a string conforming to ISO 8601",
"type": [
"string"
],
"format": "date-time",
"example": "2014-11-15T13:15"
}
},
"properties": {
"number": {
"$ref": "#/definitions/game/definitions/number"
},
"matchId": {
"$ref": "#/definitions/game/definitions/matchId"
},
"opponentOne": {
"$ref": "#/definitions/game/definitions/opponentOne"
},
"opponentTwo": {
"$ref": "#/definitions/game/definitions/opponentTwo"
},
"table": {
"$ref": "#/definitions/game/definitions/table"
},
"dateTime": {
"$ref": "#/definitions/game/definitions/dateTime"
}
}
},
"matchStats": {
"$schema": "http://json-schema.org/draft-04/hyper-schema#",
"title": "Match Statistics",
"description": "Statistical information about a match",
"type": [
"object"
],
"definitions": {
"name": {
"description": "The name of the statistic",
"type": [
"string"
],
"example": "Serving wins"
},
"opponentOneStat": {
"description": "The first opponent's statistical value; can be anything from a number to a time period to a string",
"type": [
"string"
],
"example": "7"
},
"opponentTwoStat": {
"description": "The second opponent's statistical value; can be anything from a number to a time period to a string",
"type": [
"string"
],
"example": "4"
},
"matchId": {
"description": "Identifies the match to witch this stat belongs",
"type": [
"integer"
],
"example": 12356
}
},
"links": [
{
"description": "Return the statistics for a given match",
"href": "/stats",
"rel": "self",
"title": "Info (Not Implemented)",
"method": "GET",
"targetSchema": {
"properties": {
"meta": {
"$ref": "#/definitions/reponseMeta"
},
"data": {
"type": [
"array"
],
"description": "collection of statistics",
"items": {
"$ref": "#/definitions/matchStats"
}
}
}
},
"schema": {
"properties": {
"matchId": {
"$ref": "#/definitions/matchStats/definitions/matchId"
}
},
"required": [
"matchId"
]
}
}
],
"properties": {
"name": {
"$ref": "#/definitions/matchStats/definitions/name"
},
"opponentOneStat": {
"$ref": "#/definitions/matchStats/definitions/opponentOneStat"
},
"opponentTwoStat": {
"$ref": "#/definitions/matchStats/definitions/opponentTwoStat"
}
}
},
"match": {
"title": "ITTF API - Match",
"description": "A Match is a Contest that consists of a sequence of Games between two Opponents",
"$schema": "http://json-schema.org/draft-04/hyper-schema",
"type": [
"object"
],
"stability": "spec",
"definitions": {
"id": {
"description": "The unique identifier for a Match",
"type": [
"integer"
],
"example": 123498
},
"seriesId": {
"description": "The ID of the Series to which this match belongs; null when match is not part of a series",
"type": [
"integer",
"null"
],
"example": 3548912
},
"state": {
"description": "The state of the match. Can be UNASSIGNED; meaning no players have been assigned to this match yet, 'UPCOMING'; meaning the Match has yet to start, 'IN PROGRESS, or 'COMPLETE'",
"type": [
"string"
],
"enum": [
"UNASSIGNED",
"UPCOMING",
"IN PROGRESS",
"COMPLETE"
],
"example": "COMPLETE"
},
"opponentOne": {
"description": "The first opponent. In cases where the match is unassigned, this field is null.",
"$ref": "#/definitions/opponent"
},
"opponentTwo": {
"description": "The second opponent. In cases where this match is unassigne and in cases where the first opponent has received a Bye, this field is null.",
"$ref": "#/definitions/opponent"
},
"bestOf": {
"description": "The number of Games an Opponent must win in order to be declared the winner of this Match",
"type": [
"integer"
],
"example": 5
},
"startDateTime": {
"description": "The Date and Time the Match is scheduled to start supplied as a string conforming to ISO 8601",
"type": [
"string"
],
"example": "2014-11-15T13:15"
},
"table": {
"description": "The table that the current game is being played on. If all games have concluded this is a record of the last table upon which this Match was contested",
"type": [
"string"
],
"example": "Table 3"
},
"roundName": {
"description": "The name of the Round in which this Match was or is being played",
"type": [
"string"
],
"example": "Quarter Final"
},
"groupName": {
"description": "The name of the Group in which this Match was or is being played. Null when match is not part of a Group.",
"type": [
"string",
"null"
],
"example": "Group A"
},
"divisionName": {
"description": "The name of the Division in which this Match was or is being played. Null when match is not part of a Division.",
"type": [
"string",
"null"
],
"example": "Division 1"
},
"stageName": {
"description": "The name of the Stage in which this Match was or is being played. Null when match is not part of a Stage.",
"type": [
"string",
"null"
],
"example": "Main Draw"
},
"tournamentId": {
"description": "The Id of the Tournament in which this Match was or is being played",
"type": [
"integer"
],
"example": 546978
},
"eventType": {
"description": "The type of Event; usually denotes the plurality, gender and team indicator.",
"type": [
"string"
],
"example": "MS"
},
"duration": {
"description": "How long it took for the Match to complete in the form 'HH:MM:SS'",
"type": [
"string"
],
"example": "00:04:12"
},
"games": {
"description": "a list of Games that make up this Match.",
"type": [
"array"
],
"items": {
"$ref": "#/definitions/game"
}
},
"isBye": {
"description": "Indicates that this match only has a single opponent who will automatically move on to the next round",
"type": [
"boolean"
],
"example": false
},
"stats": {
"descriptions": "Statistics for this match",
"type": [
"array"
],
"items": {
"$ref": "#/definitions/matchStats"
}
},
"since": {
"description": "An ISO 8601 compliant date and time. If set, only returns matches that were updated since the given datetime",
"type": [
"string"
],
"example": "2014-11-16T14:55:03Z"
},
"data": {
"type": [
"array"
],
"items": {
"$ref": "#/definitions/match"
}
}
},
"links": [
{
"description": "The Match List endpoint returns a collection of matches along with meta data that specifies the interval in milliseconds at which match data is refreshed.",
"href": "/matches",
"rel": "instances",
"title": "List (not implemented)",
"method": "GET",
"targetSchema": {
"properties": {
"meta": {
"$ref": "#/definitions/reponseMeta"
},
"data": {
"$ref": "#/definitions/match/definitions/data"
}
}
},
"schema": {
"properties": {
"since": {
"$ref": "#/definitions/match/definitions/since"
},
"tournamentId": {
"$ref": "#/definitions/match/definitions/tournamentId"
},
"eventType": {
"$ref": "#/definitions/match/definitions/eventType"
},
"state": {
"$ref": "#/definitions/match/definitions/state"
}
}
}
}
],
"properties": {
"id": {
"$ref": "#/definitions/match/definitions/id"
},
"seriesId": {
"$ref": "#/definitions/match/definitions/seriesId"
},
"state": {
"$ref": "#/definitions/match/definitions/state"
},
"opponentOne": {
"$ref": "#/definitions/match/definitions/opponentOne"
},
"opponentTwo": {
"$ref": "#/definitions/match/definitions/opponentTwo"
},
"bestOf": {
"$ref": "#/definitions/match/definitions/bestOf"
},
"startDateTime": {
"$ref": "#/definitions/match/definitions/startDateTime"
},
"table": {
"$ref": "#/definitions/match/definitions/table"
},
"roundName": {
"$ref": "#/definitions/match/definitions/roundName"
},
"groupName": {
"$ref": "#/definitions/match/definitions/groupName"
},
"divisionName": {
"$ref": "#/definitions/match/definitions/divisionName"
},
"stageName": {
"$ref": "#/definitions/match/definitions/stageName"
},
"tournamentId": {
"$ref": "#/definitions/match/definitions/tournamentId"
},
"eventType": {
"$ref": "#/definitions/match/definitions/eventType"
},
"duration": {
"$ref": "#/definitions/match/definitions/duration"
},
"games": {
"$ref": "#/definitions/match/definitions/games"
},
"isBye": {
"$ref": "#/definitions/match/definitions/isBye"
},
"stats": {
"$ref": "#/definitions/match/definitions/stats"
}
}
},
"opponent": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Opponent",
"description": "A Table Tennis Opponent represents one side of a Table Tennis Series, Game or Match",
"type": [
"object",
"null"
],
"definitions": {
"name": {
"description": "A nickname for this Opponent",
"type": [
"string"
],
"example": "ZHANG Zoo"
},
"score": {
"description": "The number of points this Opponent has scored",
"type": [
"integer"
],
"example": 9
},
"position": {
"description": "The opponents current position within the Event",
"type": [
"integer"
],
"example": 15
},
"hasWon": {
"description": "Indicates wether or not this Opponent has won the Game, Match or Series. Omitted when false",
"type": [
"boolean"
],
"example": true
},
"players": {
"description": "The Players that make up this Opponent",
"type": [
"array"
],
"items": {
"$ref": "#/definitions/player"
}
},
"association": {
"description": "The Association this Opponent is representing",
"$ref": "#/definitions/association"
}
},
"properties": {
"name": {
"$ref": "#/definitions/opponent/definitions/name"
},
"score": {
"$ref": "#/definitions/opponent/definitions/score"
},
"position": {
"$ref": "#/definitions/opponent/definitions/position"
},
"hasWon": {
"$ref": "#/definitions/opponent/definitions/hasWon"
},
"players": {
"$ref": "#/definitions/opponent/definitions/players"
},
"association": {
"$ref": "#/definitions/opponent/definitions/association"
}
}
},
"player": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Player",
"description": "A Table Tennis Player.",
"type": [
"object"
],
"definitions": {
"id": {
"description": "A unique identifier for the Player",
"type": [
"integer"
],
"example": 19087
},
"firstName": {
"description": "The Player's first name",
"type": [
"string"
],
"example": "Xin"
},
"middleName": {
"description": "The Player's middle name",
"type": [
"string"
],
"example": "Zhen"
},
"lastName": {
"description": "The Player's last name",
"type": [
"string"
],
"example": "Xu"
},
"rankings": {
"description": "List of Rankings for this Player",
"type": [
"array"
],
"items": {
"$ref": "#/definitions/ranking"
}
},
"avatar": {
"description": "Url of an image of the player that can be used as his or her avatar",
"type": [
"string"
],
"example": "http://ittf.com/stories/pictures/xu_xin_16_11_14.jpg"
},
"images": {
"description": "A collection of image urls for this Player",
"type": [
"array"
],
"items": {
"type": [
"string"
],
"example": "http://ittf.com/stories/pictures/xu_xin_04_10_14.jpg"
}
},
"association": {
"description": "The association to which this Player belongs",
"$ref": "#/definitions/association"
},
"nationality": {
"description": "The Player's Nationality",
"type": [
"string"
],
"example": "Chinese"
},
"dateOfBirth": {
"description": "The Player's date of birth expressed as a string conforming to ISO 8601",
"type": [
"string"
],
"example": "1988-08-18"
},
"category": {
"description": "Not sure.",
"type": [
"string"
]
},
"gender": {
"description": "The Player's gender",
"enum": [
"MALE",
"FEMALE",
"OTHER"
],
"example": "MALE"
}
},
"properties": {
"id": {
"$ref": "#/definitions/player/definitions/id"
},
"firstName": {
"$ref": "#/definitions/player/definitions/firstName"
},
"middleName": {
"$ref": "#/definitions/player/definitions/middleName"
},
"lastName": {
"$ref": "#/definitions/player/definitions/lastName"
},
"rankings": {
"$ref": "#/definitions/player/definitions/rankings"
},
"avatar": {
"$ref": "#/definitions/player/definitions/avatar"
},
"images": {
"$ref": "#/definitions/player/definitions/images"
},
"association": {
"$ref": "#/definitions/player/definitions/association"
},
"nationality": {
"$ref": "#/definitions/player/definitions/nationality"
},
"dateOfBirth": {
"$ref": "#/definitions/player/definitions/dateOfBirth"
},
"category": {
"$ref": "#/definitions/player/definitions/category"
},
"gender": {
"$ref": "#/definitions/player/definitions/gender"
}
}
},
"ranking": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Ranking",
"description": "A Ranking.",
"type": [
"object"
],
"definitions": {
"system": {
"description": "Ranking system",
"type": [
"string"
],
"example": "World - Under 21"
},
"rank": {
"description": "Rank under the given system",
"type": [
"integer"
],
"example": 12
}
},
"properties": {
"system": {
"$ref": "#/definitions/ranking/definitions/system"
},
"rank": {
"$ref": "#/definitions/ranking/definitions/rank"
}
}
},
"reponseMeta": {
"$schema": "http://json-schema.org/draft-04/hyper-schema",
"title": "ITTF API - Response Meta",
"type": [
"object"
],
"description": "Response meta data",
"definitions": {
"message": {
"type": [
"string"
],
"description": "information about this response",
"example": "Success."
},
"count": {
"type": [
"integer"
],
"description": "when requested, contains a count of the number of records that would be returned to the given request"
},
"refreshInterval": {
"description": "The minimum number of milliseconds between updates to this resource. If a client requests this resource with the same parameters more than once within a single Refresh Interval it will receive the same data",
"type": [
"integer",
"null"
],
"example": 15000
}
},
"properties": {
"refreshInterval": {
"$ref": "#/definitions/reponseMeta/definitions/refreshInterval"
}
}
}
},
"properties": {
"association": {
"$ref": "#/definitions/association"
},
"game": {
"$ref": "#/definitions/game"
},
"matchStats": {
"$ref": "#/definitions/matchStats"
},
"match": {
"$ref": "#/definitions/match"
},
"opponent": {
"$ref": "#/definitions/opponent"
},
"player": {
"$ref": "#/definitions/player"
},
"ranking": {
"$ref": "#/definitions/ranking"
},
"reponseMeta": {
"$ref": "#/definitions/reponseMeta"
}
},
"type": [
"object"
],
"title": "ITTF API",
"id": "ittf-api",
"description": "The RESTful JSON Application Programming Interface for the International Table Tennis Federation",
"version": 1,
"links": [
{
"href": "http://api.ittf.com/1/",
"rel": "self",
"method": "GET"
}
]
}