Referendum XML format

This document describes XML messages that are used for referendum events.

Message types available

  • Rushes
  • Results
  • Recounts
  • Running totals

W3C schemas

All message types are specified by a set of W3C schema files.

Click Here to Download a ZIP file, which includes the following referendum schema files:

  1. DataTypes.xsd – essential prerequisite for the other schema files
  2. ReferendumRush.xsd – the schema for referendum rushes
  3. ReferendumResult.xsd – the schema for referendum results
  4. ReferendumRecount.xsd – the schema for messages announcing a recount in a voting area in a referendum. Note that the root element is now ReferendumRecount, no longer the same as for assembly recount messages, which use Recount.
  5. ReferendumRunningTotals.xsd – the schema for running totals in a referendum

Filenames

Referendum XML messages generally follow a filename pattern that provides the referendum name, the message type, the voting area, and a revision or sequence number e.g.

EU_result_Swindon_1.xml

Voting areas

A referendum is divided into a number of voting areas, each of which may be part of a region. The messages supply the number of each area, which is typically a sequence starting from one to the number of areas. The name of each area is also provided.

Referendum propositions and answers

A referendum will consist of one or more propositions, each of which has two or more answers that may receive votes. For each voting area covered in a referendum event, the messages supply the propositions and their answers, with votes for each answer.

Recounts

The referendum recount message conveys that there has been a recount in the affected voting area. Since there may be multiple recounts in a given area, the message filename has an revision number that increments each time a new message is produced for the area. Within, the recount attribute declares how many recounts there have been e.g. 2 = 2nd recount.

Example recount filename:

EU_recount_Boston_2.xml

Example recount message:

<ReferendumRecount xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ReferendumRecount.xsd" revision="2">
  <Referendum name="EU" date="2016-06-23">
    <VotingArea number="31" name="Boston" recount="2"/>
  </Referendum>
</ReferendumRecount>

Rushes

The referendum rush message simply conveys the winning answer(s) for each proposition, for a given voting area. At this point the votes and majority are not known, so the XML simply supplies the winning answer text in the winningAnswerText attribute of the Proposition element. In the case of a tie between two or more answers, this value will be set to “Tied”.

The answers within a proposition are best identified by the shortText attribute, which is fixed for the event. Note that this value may be suffixed with the word “Test” in referendum test messages.

The enclosed Answer elements also contain a ‘winning’ attribute that is set to true if that answer has been declared as having the most votes. In the case of a tie there will be two or more answers having this value set to true.

Rushes have a revision number in both the last part of the filename and the XML, which is incremented whenever there is a change that requires a new rush e.g. a change in the winning answer.

Example rush filename:

EU_rush_Aberdeen_1.xml

Example rush message:

<ReferendumRush xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ReferendumRush.xsd" revision="1" declarationTime="2016-05-18T14:06:29+01:00">
  <Referendum name="EU" date="2016-06-23">
    <VotingArea number="1" name="Aberdeen" electorate="169678">
      <Proposition text="Should the UK remain a member of the EU or leave the EU?" winningAnswerText="Remain a member of the EU">
        <Answer winning="true" text="Remain a member of the EU" shortText="Remain"/>
        <Answer winning="false" text="Leave the EU" shortText="Leave"/>
      </Proposition>
    </VotingArea>
  </Referendum>
</ReferendumRush>

Results

The referendum results messages follow the same rules as above except that the votes and majority values are also supplied. Of course the answer with the largest number of votes is the winning answer. In the case of a tie the votes counts will clearly be seen to be equal for two or more answers.

The results messages always supersede the rush messages, and should be used in preference once received. Should there be a change to the winning answers or votes for an answer, the rush and results messages will be repeated but with an incremented revision number (the last part of the XML filename and also a revision attribute in the root element).

Example result filename:

EU_result_Aberdeen_1.xml

Example result message:

<ReferendumResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ReferendumResult.xsd" revision="1" declarationTime="2016-05-18T14:06:29+01:00">
  <Referendum name="EU" date="2016-06-23">
    <VotingArea number="1" name="Aberdeen" electorate="169678">
      <Proposition text="Should the UK remain a member of the EU or leave the EU?" turnout="97147" percentageTurnout="57.25" winningAnswerText="Remain a member of the EU" majority="943" percentageMajority="0.97">
        <Answer winning="true" text="Remain a member of the EU" shortText="Remain" votes="49045" percentageShare="50.49"/>
        <Answer winning="false" text="Leave the EU" shortText="Leave" votes="48102" percentageShare="49.51"/>
      </Proposition>
    </VotingArea>
  </Referendum>
</ReferendumResult>

Any test XML produced by PA referendum tests, will have the suffix “Test” added to the shortText attribute of the Answer elements in both the rushes and results. You may need to configured your system to expect this suffix when parsing the XML, to help identify each answer. Messages produced for a live event will not have this suffix, and you should configure your system to expect this accordingly.

Running Totals

The referendum running totals message conveys the votes share and percentage gained by each answer in a proposition. It also provides a running total of areas that have voted for that answer to win. In the case of a tie break over two or more answers, the ‘win’ count of areas will not be incremented against those answers, although the votes and percentage figures will still be increased (since they were still gained). Instead a “Tied” element will appear within the proposition, providing the number of areas that have tied. The sum of areas that are voted for each answer to win, and those tied, will be equal to the number of results received so far.

Example running total filename:

EU_running_totals_74.xml

Example running total message:

<RunningTotals xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ReferendumRunningTotals.xsd" numberOfResults="74" totalVotingAreas="382">
  <Referendum name="EU" date="2016-06-23">
    <Proposition text="Should the UK remain a member of the EU or leave the EU?">
      <Answer text="Remain a member of the EU" shortText="Remain" votingAreas="38" votes="2276346" percentageShare="49.88"/>
      <Answer text="Leave the EU" shortText="Leave" votingAreas="36" votes="2287177" percentageShare="50.12"/>
    </Proposition>
  </Referendum>
</RunningTotals>