Last saved by: Windows User

Rationale

All debate tournaments require the same basic information for registration and tabulation.  Placing the information in universal format allows compatibility that improves the ability of software and website developers to support the overall community.  The Universal Data Structure (UDS) proposes a ubiquitous data format.  If websites produce registration files that adhere to the format then any tabulation software developer can produce software that can read the registration information from any website.  If results files should follow the format then website developers can accept results from any tabulation software.  XML – often called “the language of the web” – is the obvious choice to support these formats.

Abstract: Overall structure

There are a total of 4 files in the UDS.  Three are required for registration (2 of which are optional) and one is for results.

The registration file necessary to start the tournament is called “TourneyData.xml” and is supported by the schema file “TourneyData.xsd”.  Use of the schema file is optional; it is possible to read the .xml file directly without the schema file, however, almost all software platforms anticipate a formatting file to validate .xml data against.  The TourneyData.xml file only includes information that is minimally necessary to run a tournament.  Users are free to add tables and fields at run time, and sites are free to include additional information at download.

The file should include all school records for a given circuit, including those schools not competing, and should store all the information in the schools table.  In the event that changes to the entries are made after the download, having all school records available will allow users to affiliate offline entry changes to existing school records in a central database.  Few circuits have so many schools that storage space becomes an issue.

If the site supports it and the user wants it, all master user unique identifier numbers are stored in a separate file called “TourneyDataMaster.xml” – both users and judges are stored in this file.  If the site of download maintains separate judge and competitor records, they can be downloaded with duplicate record identifiers so long as there are not multiple judges or competitors with the same number (i.e., a judge with ID# 723 and a competitor with ID# 723 are OK, but two judges with ID# 723 are not).

Note that TourneyData.xml allows (1) specification of the site from which the data are downloaded, and (2) includes the unique record identifiers used by the site.  This is standard practice at present.  For example, both JoyofTournaments.com and DebateResults.com produce files that the TRPC uses to read registration information, and both include the unique record identifiers for judges, competitors, and schools.  Among other things, this allows the synchronization of offline data with changes made online without requiring a complete re-initialization of all offline data.

When the tournament is done, the results are stored in a file called “TourneyDataResults.xml”.  TourneyDataResults.xml contains the ENTRY, ENTRY_STUDENT, EVENT, SCHOOL, and TOURN tables (as defined in the TourneyData.xsd file) and three additional tables; one to store the teams in order with their final tiebreaker scores, an identical table for the speakers, and a table that stores the round-by-round results for every debate that occurred.

TourneyData.XML file

<!-- Integer fields cannot be left blank; use zeros instead --> 

<TOURNAMENT>
	<TOURN>
		<ID>			<!-- Integer --> 
		</ID>
		<TOURNNAME></TOURNNAME>
		<STARTDATE></STARTDATE>
		<ENDDATE></ENDDATE>
		<DOWNLOADSITE></DOWNLOADSITE>
	</TOURN>
	<ENTRY>
		<ID>			<!-- Integer --> 
		</ID>
		<SCHOOL>		<!-- Integer --> 
		</SCHOOL>
		<EVENT>		<!-- Integer -->
		</EVENT>
<!-- fields below are optional; CODE is the same as Acronym, and ADA is an acronym that indicates disability -->
		<RATING></RATING>
		<CODE></CODE>
		<FULLNAME></FULLNAME>
		<DROPPED></DROPPED>
		<ADA>	</ADA>
		<NOTES></NOTES>
	</ENTRY>
	<ENTRY_STUDENT>
		<ID>		<!—Integer/ can duplicate DOWNLOADRECORD --> 
		</ID>
<DOWNLOADRECORD> <!—Integer/ record # in the central database -->
</DOWNLOADRECORD>
		<ENTRY>			<!-- Integer --> 
		</ENTRY>
		<FIRST></FIRST>
		<LAST></LAST>
		<SCHOOL>		<!-- Integer --> 
		</SCHOOL>
	</ENTRY_STUDENT>
	<EVENT>
		<ID>			<!-- Integer --> 
		</ID>
		<EVENTNAME></EVENTNAME>

    <!-- fields below are optional; supported TYPES are Policy, Parli, LD, and WUDC -->
		<ABBR></ABBR>
		<TYPE></TYPE>
	</EVENT>
	<JUDGE>
		<ID>			<!-- Integer --> 
		</ID>
		<DOWNLOADRECORD>	<!-- Integer --> 
		</DOWNLOADRECORD>
		<SCHOOL>		<!-- Integer --> 
		</SCHOOL>
		<FIRST></FIRST>
		<LAST></LAST>
		<OBLIGATION></OBLIGATION>
		<HIRED></HIRED>
		<NOTES></NOTES>
	</JUDGE>
<SCHOOL>             <!—on & offline, all schools in the circuit -->    
		<ID>			<!-- Integer --> 
		</ID>
<DOWNLOADRECORD> <!—Integer/ record # in the central database -->
</DOWNLOADRECORD>
		<REGION>		<!-- Integer --> 
		</REGION>
		<CODE>		<!--Abbreviation or short school name--> 
		</CODE>
		<SCHOOLNAME></SCHOOLNAME>
	</SCHOOL>
</TOURNAMENT>

ANNOTATED DATA SAMPLES

<!-- TOURN table for the 2012 NDT with registration held on debateresults.com; ID is the website-generated identifier for the tournament.  -->

<TOURN>
  <ID>107</ID>
  <TOURNNAME>National Debate Tournament</TOURNNAME>
  <STARTDATE>3/27/2012</STARTDATE>
  <ENDDATE>4/2/2012</ENDDATE>
  <DOWNLOADSITE>DebateResults.com</DOWNLOADSITE>
</TOURN>

<!—Team entry for Emporia WW; EVENT and SCHOOL refer to values in other tables of the same name; the rating of “3” is on a scale of 1-100 and indicates they are a pretty good team.  The rating is used for preset round pairing schemes that seek to equalize quality of opponent.  ID is the unique identifier for the entry generated by the website.  -->

<ENTRY>
    <ID>5613</ID>
    <SCHOOL>53</SCHOOL>
    <EVENT>226</EVENT>
    <RATING>3</RATING>
    <CODE>Emporia WW</CODE>
    <FULLNAME>LaToya Williams-Green and Ryan Wash</FULLNAME>
    <DROPPED>False</DROPPED>
  </ENTRY>
<!—Student entries for Wash and Williams-Green; DOWNLOADREC is the permanent identifier used by the website, and ID is the unique identifier used for this entry and this tournament.  They may be identical.  School and entry fields reference values in other tables of the same name; in this case, entry 5613 is the Emporia team of Wash and Williams-Green, and 53 is the school code for Emporia.  -->

  <ENTRY_STUDENT>
    <ID>24540</ID>
    <SCHOOL>53</SCHOOL>
    <ENTRY>5613</ENTRY>
    <FIRST>Ryan</FIRST>
    <LAST>Wash</LAST>
    <DOWNLOADRECORD>24540</DOWNLOADRECORD>
  </ENTRY_STUDENT>
  <ENTRY_STUDENT>
    <ID>22838</ID>
    <SCHOOL>53</SCHOOL>
    <ENTRY>5613</ENTRY>
    <FIRST>LaToya</FIRST>
    <LAST>Williams-Green</LAST>
    <DOWNLOADRECORD>22838</DOWNLOADRECORD>
  </ENTRY_STUDENT>

<!—Defines the event; many users may think of events as “divisions.”  ID is the unique identifier for the event assigned by the website. -->

  <EVENT>
    <ID>226</ID>
    <EVENTNAME>Open Policy at the National Debate Tournament</EVENTNAME>
    <ABBR>Open</ABBR>
    <TYPE>Debate</TYPE>
  </EVENT>

<!— ID is the unique identifier for the event assigned by the website.  It should maintain referential integrity with the JUDGE and ENTRY tables.   In this case, the school has no record in the database, so there is no downloadrecord -->

  <SCHOOL>
    <ID>53</ID>
    <DOWNLOADRECORD>0</DOWNLOADRECORD>
    <REGION>3</REGION>
    <CODE>Emporia</CODE>
    <SCHOOLNAME>Emporia State University</SCHOOLNAME>
  </SCHOOL>

<!—Judge entry for Tom Seaver; DOWNLOADREC is the permanent identifier used by the website, and ID is the unique identifier used for this entry and this tournament.  They may be identical.  School and field references a value in the table of the same name; in this case, Seaver is judging 5 rounds for Emporia.  -->

<JUDGE>
  <ID>9524</ID>
  <DOWNLOADRECORD>9524</DOWNLOADRECORD>
  <SCHOOL>53</SCHOOL>
  <FIRST>Mike</FIRST>
  <LAST>Seaver</LAST>
  <OBLIGATION>5</OBLIGATION>
  <HIRED>0</HIRED>
  <NOTES></NOTES>
</JUDGE>

TourneyDataMaster.xml (a dump of the unique identifiers in the Database; download all for the circuit

<DATABASERECORDS>
      <USER>
            <ID></ID>				<!-- Integer --> 
            <FIRST></FIRST>
            <LAST></LAST>
            <SCHOOL></SCHOOL>
            <EMAIL></EMAIL>
            <ROLE></ROLE>			<!-- supported roles are competitor or judge --> 
       </USER>
</DATABASERECORDS>

RESULTS TABLES STRUCTURE

TourneyDataResults.xml contains the ENTRY, ENTRY_STUDENT, EVENT, SCHOOL, and TOURN tables (as defined above) and the 2 additional tables below, FINALRANK and ROUNDRESULT.

<!—Following are the 2 mandatory results tables -->
<!—the first one just puts the teams in seed order; like the print teams in order from TRPC -->

<!—“EventID” is an attribute that references the EVENT table above by the ID field -->
<!—“RankFor” is an attribute that identifies whether it’s a table for speakers or teams  -->

<FINALRANK EventID=”n” RankFor=”Speaker/Team”>

<!—EntryID is a property that matches ID from ENTRY or ENTRY_STUDENT table -->

		<COMPETITOR EntryID=”n” >

<!—“TB_name” is a property that is the name of the tiebreaker, like “high-low pts” or “wins” -->
<!--"SortOrder" is the order of the tiebreaker; 1=1st tiebreaker, 2=2nd, etc. -->
<!--"SortDirection" tells whether to sort it up or down -->

		  <TIEBREAKER TB_name=”XXXX” SortOrder=”n” SortDirection="ASC/DESC">	
		  </TIEBREAKER>
</COMPETITOR>
</FINALRANK>

ANNOTATED EXAMPLE: EntryID 5613 references the ENTRY table above and is Emporia WW.  Emporia is the #1 seed at the end of the tournament (either by winning the tournament or as ranked by the tournament scoring system).  EventID references the EVENT table above.  The team had 8 wins, 22 ballots, 392 high/low adjusted points, and 440 total points.  Had more tiebreakers been used, those would have been included as well.

<FINALRANK EventID="226" RankFor=”Team”>
  <COMPETITOR EntryID="5613">
    <TIEBREAKER TB_Name="SEED" Sortorder="1" SortDirection="ASC">1</TIEBREAKER>
    <TIEBREAKER TB_Name="WINS" Sortorder="2" SortDirection="DESC">8</TIEBREAKER>
    <TIEBREAKER TB_Name="BALLOTS" Sortorder="3" SortDirection="DESC">22</TIEBREAKER>
    <TIEBREAKER TB_Name="HI/LO POINTS" Sortorder="4" SortDirection="DESC">392</TIEBREAKER>
    <TIEBREAKER TB_Name="TOTAL POINTS" Sortorder="5" SortDirection="DESC">440</TIEBREAKER>
  </COMPETITOR>
…

</FINALRANK>
<!-- ROUNDRESULT element Identifies the round of competition -->
<!-- If results are simply being reported, the optional fields can be dropped.  If the data -->
<!—are being exported for use by another tab program, they should be included -->
<!—exports for other tab software will require ROUND and ROOM tables, which are -->
<!—documented in the full schema file -->
<!-- "RoundName" attribute is a string that contains the name of the round, like "Doubles" -->
<!-- For CAT2, it's the same as the "label" on the rounds table -->
<!-- "SortOrder" attribute is an integer that tells us how to order the rounds, so that we -->
<!-- put the prelims before the elims, doubles before octos, etc. -->
<!-- "RoundType" attribute is a string that identifies “prelim,” “elim,” etc. -->
<!-- "EventID" references the Event table -->
<!-- "RoundD" is optional and references the ROUND table -->

<ROUNDRESULT RoundName="xxxx" SortOrder="n" RoundType=”xxxx” EventID=”n” RoundID=”n>

<!—Store JudgeID from judges table -->
<!—Panel identifies the round, and only matters if there are multiple-judge panels -->
<!—Room is optional; if present, there must be a ROOM table that it can reference -->
<!—Flight is optional; indicates the flight in a flighted round (numeric)-->

	  <RESULT_BALLOT JudgeID=”n” PanelID=”n” RoomID=”n” Flight=”n”>

<!—Each score each judge gave to each recipient; usually just wins, ranks, and points -->
<!—Score_Name is a property that names the score; supported values are “Ballots” -->
<!—“TeamPoints” “Points” and “Rank” -->
<!—ScoreFor is a property that identifies whether it’s a team or speaker score; “Team” and -->
<!—“Speaker” are the only supported values. -->
<!—“Recipient” is either the team ID in the ENTRY table or the speaker ID in the ENTRY_SPEAKER -->
<!—Table-->
<!—Side is optional and should only be used if the ScoreFor property=”Team”; 1=Aff, 2=Neg -->
<!—For parli, 1=gov, 2=opp; for WUDC 1=opening gov, 2=opening opp, 3=closing gov, 4=closing opp-->

		< RESULT_SCORE Score_Name="xxxx" ScoreFor="Team/Speaker" Recipient="ID" Side=”n”>
		</ RESULT_SCORE>
  </RESULT_BALLOT>
</ROUNDRESULT>

ANNOTATED EXAMPLE: This is an example from the first round, named “Prelim rd 1.”  It is sortorder 1, which says that the round should be sorted first, and RoundType indicates that this is a preliminary round.  EventID references the EVENT table above.  This is a 3-judge panel.  The first judge voted for Emporia WW (Entry # 5613), and assigned points of 28.8 and 29.5 to them.  The opposing team received 28.3 and 28 points.  The second judge also voted for Emporia, but the 3^rd judge voted for their opponent (Entry # 5735).  The affirmative team appears first.

<ROUNDRESULT RoundName="Prelim rd 1" Sortorder="1" RoundType="Prelim" EventID="226">
    <RESULT_BALLOT JudgeID="8219" Panel="18548">
      <RESULT_SCORE SCORE_NAME="RESULT_BALLOT" ScoreFor="Team" Recipient="5613">1</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="24540">28.8</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="24540">2</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="22838">29.5</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="22838">1</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="RESULT_BALLOT" ScoreFor="Team" Recipient="5735">0</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="26981">28.3</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="26981">3</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="31101">28</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="31101">4</RESULT_SCORE>
    </RESULT_BALLOT>
    <RESULT_BALLOT JudgeID="8394" Panel="18548">
      <RESULT_SCORE SCORE_NAME="RESULT_BALLOT" ScoreFor="Team" Recipient="5613">1</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="24540">28.8</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="24540">1/SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="22838">28.7</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="22838">2</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="RESULT_BALLOT" ScoreFor="Team" Recipient="5735">0</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="26981">28.4</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="26981">3</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="31101">28.3</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="31101">4</RESULT_SCORE>
    </RESULT_BALLOT>
    <RESULT_BALLOT JudgeID="9592" Panel="18548">
      <RESULT_SCORE SCORE_NAME="RESULT_BALLOT" ScoreFor="Team" Recipient="5613">0</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="24540">29.1</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="24540">3</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="22838">29.2</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="22838">2</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="RESULT_BALLOT" ScoreFor="Team" Recipient="5735">1</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="26981">28.4</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="26981">1</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Points" ScoreFor="Speaker" Recipient="31101">28</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Rank" ScoreFor="Speaker" Recipient="31101">4</RESULT_SCORE>
    </RESULT_BALLOT>
…
</ROUNDRESULT>  

ELIMINATION ROUND: This is an example of the finals decision; no speaker points are recorded.  The first judge (ID# 229) voted for the negative, but the 2^nd and 3^rd judges (ID# 787 and ID# 1075) each voted for Emporia on the affirmative.

  <ROUNDRESULT RoundName="Finals" Sortorder="16" RoundType="Elim"" EventID="226">
    <RESULT_BALLOT JudgeID="229" Panel="18930">
      <RESULT_SCORE SCORE_NAME="Ballot" ScoreFor="Team" Recipient="5613">0</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Ballot" ScoreFor="Team" Recipient="5665">1</RESULT_SCORE>
    </RESULT_BALLOT>
    <RESULT_BALLOT JudgeID="787" Panel="18930">
      <RESULT_SCORE SCORE_NAME="Ballot" ScoreFor="Team" Recipient="5613">1</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Ballot" ScoreFor="Team" Recipient="5665">0</RESULT_SCORE>
    </RESULT_BALLOT>
    <RESULT_BALLOT JudgeID="1075" Panel="18930">
      <RESULT_SCORE SCORE_NAME="Ballot" ScoreFor="Team" Recipient="5613">1</RESULT_SCORE>
      <RESULT_SCORE SCORE_NAME="Ballot" ScoreFor="Team" Recipient="5665">0</RESULT_SCORE>
    </RESULT_BALLOT>
  </ROUNDRESULT>

Notes on sample TourneyDataResults.xml

Note that the file with the first 6 tables (ENTRY, EVENT, ENTRY_STUDENT, SCHOOL, JUDGE, and TOURN) is the same as the original download file.  With the addition of the FINALRANK and ROUNDRESULT tables it constitutes the final results file.

The sample includes a single division that clears to semi-finals.