XML samples - XML

Some example XML files will help you get a sense of the formats I have described. The official DTDs or schemas (ideally using RELAX NG in production) are still sufficiently subject to change that I do not want to fixate on those. To save space, I'll simplify the demonstration election that the OVC has used, but keep at least one example of each contest type. First, the ballot file:

Listing 1. ballot-election.xml

<ballot election_date="2008-11-04" country="US" state="CA"
        county="Santa Clara County" precinct="2216">
  <contest ordered="No" coupled="Yes"
           allow_writein="Yes" name="Presidency">
    <selection party="Reform"
               name="President">Martin Luther King</selection>
    <selection party="Reform"
               name="Vice President">John Anderson</selection>
    <selection party="Workers"
               name="President">Helen Keller</selection>
    <selection party="Workers"
               name="Vice President">Amelia Earhart</selection>
    <selection party="Socialist"
               name="President">V. I. Lenin</selection>
    <selection party="Socialist"
               name="Vice President">Karl Marx</selection>
  </contest>
  <contest ordered="No" coupled="No"
           allow_writein="Yes" name="Senator">
    <selection party="Green">Frances E. Willard</selection>
    <selection party="Libertarian">Lucy Stone</selection>
    <selection party="Democrat">Karl Menninger</selection>
    <selection party="Labor">William Lloyd Garrison</selection>
  </contest>
  <contest ordered="No" coupled="No" allow_writein="No"
           name="Transportation Initiative">
    <summary>
      <scope>Constitutional Amendment Article X, Section 19</scope>
      <type>initiative</type>
      <title>California Transportation Initiative For Statewide Solar
        Powered Magnetic Levitation System</title>
    </summary>
    <description>
      To reduce traffic and increase travel alternatives, this amendment
      provides for development of a high-speed solar powered magnetic
      levitation system to run along Interstate 5.  Construction to begin
      November 1, 2004.
    </description>
    <selection>Yes</selection>
    <selection>No</selection>
  </contest>
  <contest ordered="Yes" coupled="No" allow_writein="Yes"
           name="County Commissioner">
    <selection>William Hewlett</selection>
    <selection>Steve Wozniak</selection>
    <selection>William Shockely</selection>
    <selection>Gordon Moore</selection>
    <selection>Philip Kahn</selection>
  </contest>
</ballot>

Some of the attributes of <contest> merit further explanation. Contests may be ordered to allow ranked preference votes. Ranked preference votes allow a voter to assign a preference (first, second, third, and so on) among a number of candidates -- you might use many different methods to score those ranks (all outside the scope of this article), but an Instant Runoff is probably the least rare in the U.S. In any case, since a few jurisdictions use ranked preference voting, this ballot XML format needs to accommodate it. Missing from the current ballot DTD is an attribute to indicate the maximum number of ranks that are assignable -- I will show you how to add this shortly.

Contests can either allow write-in votes or not. In the example, it makes little sense to write in a vote on a Yes/No initiative; other types of contests may or may not allow write-ins, depending on jurisdictional rules. The name attribute is straightforward -- it simply describes what a contest is in a short phrase. In some contests, child elements may be needed to present the details of a contest to voters (such as initiative descriptions). Again, the exact content is jurisdiction dependent.

The coupled attribute is probably a hack, but it's not clear whether there's a better approach. In U.S. presidential elections, we have a relatively unusual system in which votes for a President and Vice President must be paired together -- no a la carte menu selection of "one of each" is allowed, even though both candidate names still appear. For now, this design lists each candidate within a <selection> element, but if coupled is set to Yes, candidates are presented two-at-a-time rather than individually.

As I mentioned, a cast ballot (EBI) roughly subsets a raw ballot, but a few details are changed too. EBIs follow a naming convention that indicates both the place and date of the election, and also a distinct ballot ID number (which is not reused on a single machine):

Listing 2. v-20081104-US-CA-Santa_Clara_County-2216-1274.xml

<cast_ballot election_date="2008-11-04" country="US" state="CA"
             county="Santa Clara County" precinct="2216"
             number="1274" serial="213" source="voting_machine">
  <contest ordered="No" coupled="Yes" name="Presidency">
    <selection writein="No" name="President">V. I. Lenin</selection>
    <selection writein="No" name="Vice President">Karl Marx</selection>
  </contest>
  <contest ordered="No" coupled="No" name="Senator">
    <selection writein="No">William Lloyd Garrison</selection>
  </contest>
  <contest ordered="No" coupled="No" name="Transportation Initiative">
    <selection writein="No">Yes</selection>
  </contest>
  <contest ordered="Yes" coupled="No" name="County Commissioner">
    <selection writein="Yes">David Packard</selection>
    <selection writein="No">Gordon Moore</selection>
    <selection writein="No">William Hewlett</selection>
  </contest>
</cast_ballot>

Notice that the attribute writein now appears within <selection> tags. In a sense, you could deduce whether a vote is a write-in by looking at a corresponding ballot-election.xml file that contains <selection> PCDATA content, but using the attribute adds some useful redundancy. If a non-write-in candidate fails to match the raw ballot, that is a sure sign that you have a data integrity problem. But some jurisdictions only count specific write-in names if certain thresholds are met (contest margin-of-victory, total write-ins, and others); you may never need to look at the content of selections indicated as writein="Yes".