FIRST Event Data Specification 1.0 RC8

Under Implementation

See the draft version for future implementation ideas.

Special Notes

Some teams have special characters in their names, such as accents. Being an XML specification, these characters are represented in Unicode. When converting between this and other formats, take note that not all formats will use Unicode. Some formats will use the iso-8859-1 character set that stores the same character as a different byte value, some HTML web pages (such as the FIRST team list) will send the characters as HTML entities, in which case you must use an XML parser to interpert the entities (such as À) into their characters (À).

Root Element «/»

The root element is one of "competition", "season" or "event".

The root element SHOULD have a version attribute that specifies a major.minor release number. If the version attribute is left off, the parser SHOULD assume the version is the latest version it knows about, and it MUST die with an error if it cannot parse the document in this event.

The XML namespace of this is "urn:first-unofficial:competitiondata"

The root opening tag may look similar to this:

<competition xmlns="urn:first-unofficial:competitiondata" version="1.0" game="FRC">

Child Elements

• team

«/competition» Element

The competition element is usually the root element, and used when multiple seasons of data are stored in the document.

Attributes

game	Name of a game that can use this data format. Use "FRC" for the FIRST Robotics Competition. "FTC" and "FLL" are other examples of values. This attribute is OPTIONAL.

«//season» Element

Specifies a season of a game. Each season may have slightly different rules, but teams with the same number remain the same teams between seasons inside the same competition.

Attributes

season	A unique ID for this season, which SHOULD be the year alone, e.g. "2008".
id	Year combined with a unique identifier, if the season is not the official FIRST season, e.g. "2008-team498-offseason". Defaults to the season attribute.
title	Title for/name of the season, e.g. "FIRST Overdrive"

Parent Elements

• competition
• May be the root element

«//event» Element

Specifies a single event within a season. Contains the matches that were played.

Attributes

name	Name of the event. SHOULD be specified in "Name Regional" format, for regionals. The Championship SHOULD be formatted as "Championship Division".
code	Abbreviation of the event, e.g. "NH"
start	Begin date of the event, when teams may use the field (e.g. practice day), in YYYY-MM-DD format.
end	End date of the event, in YYYY-MM-DD format.
timezone	Timezone of the location of the event, in hours from UTC.
location	Location of the event according to FIRST, e.g. "Phoenix, AZ, USA"
country	Two letter ISO code of the country, e.g. "US"

Parent Elements

• season
• may be the root element

Child Elements

• team (if the root element)
• match

«//match» Element

Support for match replays are entirely OPTIONAL, only support for officially counted matches is necessary.

Attributes

Parent Elements

• event

Child Elements

• alliance

«//alliance» Element

One element is given for each alliance in a match. The score attribute is required if the match has been played, and represents the final, official score. For example, in the FIRST Robotics Competition, regardless of penalties, the final score can never be less then zero, and likewise this attribute should not be negative to reflect the FRC rules.

Attributes

name	The name of the alliance, how the alliance is identified. For the FRC, this would be "red" or "blue".
score	Final, complete, official score by the alliance. When the match score is known this attribute MUST be specified. If the attribute is missing, it MAY be assumed the match was or has not yet been played even if other alliance elements under the same match specify a score. This element MUST supersede the sum of the score and penalty elements, see Calculating match scores for more information.
points	Total unpenalized score by the alliance. This attribute is OPTIONAL. If this number does not match the sum of the «.//score/@value» elements, it MUST be assumed the score components are incomplete, and this attribute is the actual unpenalized score. This value MUST be non-negative (greater then or equal to zero).
penalties	Total penalties received by the alliance. This attribute is OPTIONAL. Like the penalty elements, this value MUST be non-positive (less then or equal to zero). If this attribute shows a different value then the sum of the «.//penalty/@value» elements, it MUST be assumed that this value is authoritative and the penalty components are incomplete.

Parent Elements

• match

Child Elements

• team
• score
• penalty

«//season/team», «//event/team» Element

See also: «//alliance/team» Element

Provides information on all teams through for the competition season.

Full information must only be provided for «//event/team» if there are no «//season/team» elements to provide it. If there is a season element to get team data from, then «//event/team» SHOULD NOT provide more then the "number" attribute.

Attributes

season	Season the team information is valid for. This may be assumed to be the same as the season the team is inside.
number	Team number
nickname	Teams supplied nickname.
name	Teams full name, with sponsors and schools.
location	Location of the event according to FIRST, e.g. "Phoenix, AZ, USA"
country	Two letter ISO code of the country, e.g. "US"
website	Full path to the team's website

Parent Elements

• season
• event

«//alliance/team» Element

See also: «//season/team», «//event/team» Element

This element specifies that a previously defined team is a member of an alliance, as well as any scores or penalties the team may have incurred.

Attributes

number	Team number on the alliance. This MUST be provided.
position	What position the team is on ("1" for "Red 1", "2" for "Blue 2", etc). This element SHOULD be provided when that information is available.
disqualified	Set to the value "disqualified" if the team was disqualified for the match. The attribute SHOULD NOT appear if the team was not disqualified, and MUST be blank if it does.
surrogate	Set to the value "surrogate" if the team is designated as a surrogate for the match. The attribute SHOULD NOT appear if the team is not a surrogate, and MUST be blank if it does.

Parent Elements

• alliance

Child Elements

• score
• penalty

Calculating match scores

For a given alliance element «.» the score of an alliance can be calculated with the following Xpath expression:

sum(.//score/@value)+sum(.//penalty/@value)

A competition or season MAY define special rules to modify this score, such as the common rule that no score may be below zero. The score and penalty elements MAY be used as an incomplete representation of the score, for instance, to indicate that 20 points of the final score are from the endgame bonus, and the remaining points (not specified with a score element) are unknown. If the sum of the score and penalty elements conflict, the score attribute of the alliance is used as the authoritative score.

For example:

<match number="2">
	<alliance name="red" score="22">
		<team number="330"><penalty name="G20" value="-10"/></team>
		<team number="498"><score name="laps" value="10"/></team>
		<team number="2134"><score name="laps" value="10"/></team>
		<score name="bonus" value="12"/>
	</alliance>
	...
</match>

«//alliance//score» Element

Specifies a score for an alliance. The score can be broken down into pieces and placed under a team element to show one team scored the points. A "name" attribute SHOULD be used if the source of the score is known, e.g. "autonomous", "score", "bonus". The point total of the score is specified in a "value" attribute. Negative values MUST be rejected with an error.

Parent Elements

• alliance
• team

«//alliance//penalty» Element

Specifies a penalty on an alliance, or team of that alliance. The score can be broken down into pieces and placed under a team element to provide context. The name of the penalty SHOULD be placed in a "name" attribute. The score of the penalty MUST go in the "value" attribute. The value of the penalty MUST be negative, positive values MUST be rejected with an error.

Parent Elements

same as score

Example XML Document Trees

The attributes shown, prefixed with an "@", are the required attributes. There are other optional attributes.

competition as root node

competition
`- season @year
 +- team @number (with other data)
 `- event
 `- match @number
 `- alliance @name @score
  +- penalty @value
  +- score @value
  `- team @number
   +- penalty @value
   `- score @value

season as root node

season @year
+- team @number (with other data)
`- event
 `- match
 `- alliance @name @score
  +- penalty @value
  +- score @value
  `- team @number
   +- penalty @value
   `- score @value

event as root node

event
+- team @number (with other data)
`- match @number
 `- alliance @name @score
  +- penalty @value
  +- score @value
  `- team @number
   +- penalty @value
   `- score @value