GGP.org Match Data Format

"You know what burns me? Matches." (Jay London)

All matches on GGP.org are stored as JSON objects. This format was chosen because it is succinct, human-readable, and extensible. But not every JSON object qualifies as a match. Before a match can be published to GGP.org it undergoes validation to ensure that it is well-formed.

Matches can contain the following fields. Fields marked "required" must be present in order for a match to be well-formed.

Unique Identification
matchId	REQUIRED	String	A string to be used as the name for the match.
startTime	REQUIRED	Number	A number indicating when the match began, in milliseconds since the era.
randomToken	REQUIRED	String	A string that is chosen uniformly at random from a space of size at least 2^64.
matchHostPK	OPTIONAL	String	Cryptographic public key, chosen by the host server for this match. Can be randomly chosen, or used across multiple matches to identify the host server.
Match Protocol
startClock	REQUIRED	Number	A number indicating how long players have before their first moves begin, in seconds.
playClock	REQUIRED	Number	A number indicating how long each player has to play each move, in seconds.
Match History
states	REQUIRED	Array	An ordered JSON array containing strings. Each string contains a Symbol List, encoding a single game state. These strings are ordered so that the first element of the list is the first state in the game, and so on.
moves	REQUIRED	Array	An ordered JSON array containing JSON arrays, each of which contains the moves...
errors	OPTIONAL	Array	An ordered JSON array containing JSON arrays, each of which contains a string indicating whether an error occurred... error strings MUST be empty or start with "TO", "IL", "IN" or "CE"...
stateTimes	REQUIRED	Array	An ordered JSON array containing numbers, each corresponding to an element of states, indicating when that state occurred, in milliseconds after the era.
isCompleted	OPTIONAL	Boolean	A boolean indicating whether the match is successfully completed or not. MUST be consistent with the match's current state and the game's rules.
isAborted	OPTIONAL	Boolean	A boolean indicating whether the match has been aborted mid-way through.
goalValues	OPTIONAL	Array	An ordered JSON array containing numbers, each corresponding to an element of gameRoleNames, indicating the score that player has. Should only ever be present when isCompleted is true. MUST be consistent with the match's current state and the game's rules.
Game Information
gameMetaURL	REQUIRED	String	Game metadata file URL. MUST point to a repository server. MUST be qualified with a version.
gameRoleNames	OPTIONAL	Array	DEPRECATED An ordered JSON array containing the role names for the game, as strings. MUST be consistent with the game's rulesheet.
gameName	OPTIONAL	String	DEPRECATED The name of the game. This MUST be consistent with the game's metadata file.
Player Information
playerNamesFromHost	OPTIONAL	Array	An ordered JSON array containing the match host's names for the players in the match. Only really useful for host-signed matches: each host is responsible for keeping their player namespace sane.
isPlayerHuman	OPTIONAL	Array	An ordered JSON array of booleans indicating whether the players in the match are controlled by humans or machines.
Security
matchHostSignature	OPTIONAL	String	Cryptographic signature of all the canonicalized match information, using the private key associated with matchHostPK.
Misc
tournamentNameFromHost	OPTIONAL	String	The match host's the name for the tournament this match was involved in. Only really useful for host-signed matches: each host is responsible for keeping their tournament namespace sane.
scrambled	OPTIONAL	Boolean	Were the game rules scrambled before being sent to the players?
weight	OPTIONAL	Number	Optional suggested weight for statistics computation; may or may not be used by systems that actually compute statistics.

Matches may have additional fields that are not defined here, but such fields must be prefixes with "x-". This ensure that they don't collide with future official fields.

None of these fields may contain null values.

Every match contains a URL where the game being played can be found. See here for more details on the data format for games.