Voting Information Project Format Specification, Version 2.0 Proposed (2009-05-19)

General introduction

Term definitions

  1. Required - Any implementation that does not implement things noted as required is not considered a conforming implementation.
  2. Optional - Conforming implementations may validly ignore anything marked optional and still be considered conforming.

Field types

Field type Description
Date Date fields are required to be valid xs:date format (as defined by The XML Schema specification), which is yyyy-mm-dd <optional timezone info>
DateTime DateTime fields are required to be valid xs:dateTime format (as defined by The XML Schema specification), which is "YYYY-MM-DDThh:mm:ss" <optional timezone info>
String String fields contain arbitrary UTF-8 text. These fields are required to be valid UTF-8. Further restrictions on the content of a String field may be included in each field description
Integer Integer fields describe a numeric value. The value of an integer field is required to be representable as a two's complement 64 bit signed integer. That is, the value must be between -9223372036854775807 and 9223372036854775807

An implementation must not rely on identifiers being the same over multiple fetches of the same data.

General Specification

The actual election information specifies collection of elements, some containing links between each other. The entire set of tags must be encapsulated in a root object named vip_object (VIP is short for "voting information project"). See the sample xml file and xsd file for more details. The file naming standard is here.

Each top-level tag is a container for other fields, described in their own section. The only required top-level tag is the source object. All other top-level tags can be repeated an unlimited number of times, or not included at all; order of top-level tags does not matter. Each top-level tag is required to have a single attribute, "id", which is required to be: (1) an integer, and (2) unique in a data file. The id attribute for the state object is often the state's FIPS number, but this is not required. As mentioned above, id attributes are not required to remain constant for the same piece of semantic data across multiple productions of the feed. (For example, candidate Michael Smith, running for dogcatcher in Iowa, is not required to have the same candidate id attribute each time the state of Iowa publishes data.)

In general, subtag data can appear a maximum of one time within each top-level tag object and in any order. Exceptions are noted below.

For the data itself, the special characters &, <, and > need to be encoded as &amp; , &lt; , and &gt; , respectively

Linking Externally

Each element other than the root vip_object may (i.e., optionally) include the attributes external_source_vip_id and external_source_datetime, which indicate that the linked element is not found in the current document but in an external document with the specified vip_id and datetime in the external document's top-level source object. For this reason, the source object is required in every feed document. Two examples might elucidate the above discussion of external linking. Consider the case when an organization supplements Iowa's data on candidates with candidates' statements on issues. In the candidate_statement object, the organization links to state data by specifying 
     <candidate_id external_source_vip_id="19" external_source_datetime="2008-06-05T15:45:10">321113<candidate_id>
where 321113 matches Michael Smith's candidate id attribute in the Iowa feed published on 2008-06-05 at 15:45:10. Note that the organization supplementing Iowa's data never has to specify the candidate's name. In a second case, the organization supplementing Iowa's data knows Michael Smith's email address. Here, the organization adds to the candidate object by specifying 
      <candidate candidate_id external_source_vip_id="19" external_source_datetime="2008-06-05T15:45:10" external_source_object_id="321113" id="3705">
        <name>Michael Smith</name>
        <email_address>msmith@smithin2008.org</email_address>
      </candidate>
where again 321113 is the id in the Iowa file, and 3705 is the id in the supplementing file. If the supplementing file needs to link to Michael Smith (e.g., for a candidate statement), it should link internally, using the 3705 ID.

Top level items

Tag Section
source Source subtags
election Election subtags
state State subtags
locality Locality subtags
precinct Precinct subtags
precinct_split Precinct Split subtags
election_administration Election Administration subtags
election_official Election Official subtags
polling_location Polling Location subtags
early_vote_site Early Vote Site subtags
contest Contest subtags
electoral_district Electoral District subtags
ballot Ballot subtags
candidate Candidate subtags
campaign_issue Campaign Issue subtags
candidate_statement Candidate Statement subtags
referendum Referendum subtags
custom_ballot Custom Ballot subtags
ballot_response Ballot Response subtags
street_segment Street Segment

Custom Types

Tag Section
detailAddressType Detail Address subtags
simpleAddressType Simple Address subtags

Source items

The Source object represents the organization that is publishing the information. This object is the only required object in the feed file, and only one source object is allowed to be present.

Tag Data type
Description Error handling
name String Required The name field specifies the name of the organization that is providing the information. If the name field is invalid, the implementation is required to ignore the source element containing it.
vip_id Integer Required The vip_id field specifies the ID of the organization as assigned by VIP. This ID is not an attribute so as not to interfere with organizations' own numbering conventions (since id attributes must be unique across the entire file). If the vip_id field is invalid, the implementation is required to ignore the source element containing it.
datetime DateTime Required The datetime field specifies the date and time of the feed production. The date/time is considered to be in the timezone local to the organization. This datetime is required to match the datetime specified in the feed's filename. If the datetime field is not present or invalid, the implementation is required to ignore the source element containing it.
description String Optional The description specifies both the nature of the organization providing the data and what data is in the feed. If the description is invalid, the implementation is required to ignore it.
organization_url String Optional The organization_url field contains a URL to the home page of the organization publishing the data If the organization_url field is invalid, the implementation is required to ignore it.
feed_contact_id Integer Optional The feed_contact_id is a reference to (an election official object) the person who will respond to inquiries about the information contained within the file. If the feed_contact_id field is invalid, the implementation is required to ignore it.
tou_url String Optional The tou_url is the website where the Terms of Use for the information in this file can be found. If the tou_url field is invalid, the implementation is required to ignore it.

Example XML for a source element: 

      <source id="0">
        <name>State of Alabama</name>
        <vip_id>1</vip_id>
        <datetime>2008-06-05T15:45:10</datetime>
        <description>The State of Alabama is the official source of eletion information in Alabama. This feed provides information on election dates, districts, offices, candidates, and precinct boundaries.</description>
        <organization_url>http://www.sos.state.al.us/Elections</organization_url>
        <feed_contact_id>1555122</feed_contact_id>
        <tou_url>http://www.sos.state.al.us/vipFeed/terms_of_use.html</tou_url>
    </source>
    

      <source id="0">
        <name>League of Informed Voters</name>
        <vip_id>101</vip_id>
        <datetime>2008-12-05T14:37:01</datetime>
        <description>The League of Informed Voters provides the public with information on candidate positions. This feed provides information on candidate statements and links to the feeds provided by the states.</description>
        <organization_url>http://www.leagueofinformedvoters.org</organization_url>
        <feed_contact_id>14415</feed_contact_id>
        <tou_url>http://www.leagueofinformedvoters.org/feed/terms.html</tou_url>
    </source>

Election items

The Election object represents an Election Day, which can consist of many individual contests and/or referenda.

Tag Data type
Description Error handling
date Date Required The date field specifies when the election is being held. The date is considered to be in the timezone local to the state holding the election. If the date is not present or invalid, the implementation is required to ignore the election element containing it.
election_type String Optional The election_type field specifies the highest controlling authority for election (e.g., federal, state, county, city, town, etc.) If the election_type field is invalid, the implementation is required to ignore the election_type field.
state_id Integer Required The state_id specifies a link to the state element where the election is being held. If the state_id is not present or invalid, the implementation is required to ignore the election element containing it.
statewide yesNoEnum Optional The statewide specifies whether the election is statewide. Valid items are "yes" and "no". If the statewide is not present or invalid, the implementation is required to default to "yes".
registration_info String Optional The registration_info specifies information about registration for this election either as text or a URL. If the registration_info field is invalid, the implementation is required to ignore it.
absentee_ballot_info String Optional The absentee_ballot_info specifies information about requesting absentee ballots either as text or a URL If the absentee_ballot_info field isinvalid, the implementation is required to ignore it.
results_url String Optional The results_url field contains a URL where results for the election may be found If the results_url field is invalid, the implementation is required to ignore it.
polling_hours String Optional The polling_hours field contains the hours (in local time) that Election Day polling locations are open. If polling hours differ in specific polling locations, alternative hours may be specified in the Polling Location object. If the polling_hours field is invalid or missing, the implementation is required to ignore it.
election_day_registration yesNoEnum Optional The election_day_registration specifies if a voter can register on the same day of the election (i.e., the last day of the election). Valid items are "yes" and "no". If the election_day_registration field is invalid or missing, the implementation is required to ignore it and not assume one way or the other.
registration_deadline Date Optional The registration_deadline field specifies the last day to register for the election with the possible exception of Election Day registration. If the registration_deadline field is invalid or missing, the implementation is required to ignore it.
absentee_request_deadline Date Optional The absentee_request_deadline field specifies the last day to request an absentee ballot. If the absentee_request_deadline field is invalid or missing, the implementation is required to ignore it.

Example XML for an election element: 

      <election id="12345">
        <date>2007-09-15</date>
        <statewide>yes</statewide>
        <state_id>49</state_id>
        <election_type>Federal</election_type>
        <results_url>http://elections.results.org</results_url>
        <registration_info>To register for this election, blah blah blah</registration_info>
        <absentee_ballot_info>To request an absentee ballot, blah blah blah</absentee_ballot_info>
        <polling_hours>7am-8pm</polling_hours>
        <election_day_registration>yes</election_day_registration>
        <registration_deadline>2009-10-01</registration_deadline>
        <absentee_request_deadline>2009-11-01</absentee_request_deadline>
      </election>

State items

The State object includes state-wide election information. The ID attribute is the state's FIPS code.

Tag Data type
Description Error handling
name String Required The name is the name of a state, such as Alabama If the name field is not present or invalid, the implementation is required to ignore the state element containing it.
election_administration_id Integer Optional The election_administration_id links to the state's election administration object. If the election_administration_id field is invalid the implementation is required to ignore it.

Example XML for a state element: 

      <state id="1">
        <name>Alabama</name>
        <election_administration_id>23455</election_administration_id>
      </state>

Locality items

The Locality object represents the jurisdiction below the state (e.g., county).

Tag Data type
Description Error handling
name String Required The name specifies the locality's name If the name field is invalid or not present, the implementation is required to ignore the locality element containing it.
state_id Integer Required The state_id links to the locality's state If the state_id field is invalid or not present, the implementation is required to ignore the locality element containing it.
type String Required The type specifies the locality's type. Valid values are: county, city, town, township, borough, parish, and region (for Alaska). If the type field is invalid or not present, the implementation is required to ignore the locality element containing it.
election_administration_id Integer Optional The election_administration_id links to the locality's election administration object. If the election_administration_id field is invalid the implementation is required to ignore it.

Example XML for a locality element: 

      <locality id="1000">
        <name>Howard</name>
        <state_id>49</state_id>
        <type>county</type>
        <election_administration_id>23456</election_administration_id>
      </locality>

Precinct

The Precinct object represents a precinct, which is contained within a Locality. Subtag data must appear in the order below.

Tag Data type
Description Error handling
name String Required The name specifies the precinct's name (or number) If the name field is invalid or not present, the implementation is required to ignore the precinct element containing it.
locality_id Integer Required The locality_id links to the locality that comprises the precinct If the locality_id field is invalid or not present, the implementation is required to ignore the precinct element containing it.
electoral_district_id Integer Optional;
multiple allowed		 The electoral_district_id links to an electoral district (e.g., congressional district, state house district, school board district) that the precinct belongs to. Highly Recommended if candidate information is to be provided. Multiple allowed and recommended to specify the geography of multiple electoral districts. If an electoral district splits a precinct, use the precinct_split object and do not specify that particular electoral district in this object. If the electoral_district_id field is invalid or not present, the implementation is required to ignore the precinct element containing it.
ward String Optional The ward specifies the ward the precinct is contained within If the ward field is missing or invalid, the implementation is required to ignore it.
mail_only yesNoEnum Optional The mail_only specifies whether voters in the precinct vote only by mailing their ballots (with the possible option of dropping off their ballots as well). Valid values are "yes" and "no", with "no" being the default is the tag is not present. If the mail_only field is missing or invalid, the implementation is required to default to "no".
polling_location_id Integer Optional; multiple allowed The polling_location_id specifies a link to the precinct's polling location object. Multiple polling_location_id tags may be specified, but this use should be reserved for when multiple Election-Day-only vote locations serve specific precincts. Use the early_vote_site for early vote centers. If the polling_location_id field is missing or invalid, the implementation is required to ignore it.
early_vote_site_id Integer Optional;
multiple allowed		 The early_vote_site_id specifies a link to the precinct's ballot drop location. This tag is especially important for precinct-specific drop locations, but less important for locality-level (i.e., county-level) drop locations where multiple drop locations serve multiple precincts. In the latter case, precinct multiple early_vote_site_id tags may be specified. Also if the precinct is mail-only then if no early_vote_site_id is present the implementation should assume that drop locations in the same locality (e.g., county) are valid locations. If the early_vote_site_id field is missing or invalid, the implementation is required to ignore it with the following exception. If the precinct is mail-only and the early_vote_site_id field is missing then the implementation is required to assume that any early_vote_site objects within the same locality are valid drop locations for this precinct.

Three example XML's for a precinct element. The first is a standard, in-person precinct. The second is a mail-in precinct with a precinct specific drop location. The third is a mail-in precinct with multiple drop locations spread around the county. 

      <precinct id="4567">
        <name>Camelot</name>
        <locality_id>568</locality_id>
        <electoral_district_id>100044</electoral_district_id>
        <electoral_district_id>100055</electoral_district_id>
        <polling_location_id>3845</polling_location_id>
      </precinct>
    
      <precinct id="1003">
        <name>2</name>
        <locality_id>168</locality_id>
        <electoral_district_id>100044</electoral_district_id>
        <electoral_district_id>100056</electoral_district_id>
        <ward>1</ward>
        <mail_only>yes</mail_only>
       <early_vote_site_id>1324</early_vote_site_id>
      </precinct>
    
      <precinct id="1043">
        <name>Multiple-drop precinct</name>
        <locality_id>169</locality_id>
        <electoral_district_id>100044</electoral_district_id>
        <electoral_district_id>100056</electoral_district_id>
        <mail_only>yes</mail_only>
        <early_vote_site_id>1334</early_vote_site_id>
        <early_vote_site_id>1335</early_vote_site_id>
        <early_vote_site_id>1336</early_vote_site_id>
      </precinct>

Precinct Split

The Precinct Split object represents a part of a precinct. The Precinct Split object will link to its "parent" Precinct object. Subtag data must appear in the order below.

Tag Data type
Description Error handling
name String Required The name specifies the precinct split's name (or number) If the name field is invalid or not present, the implementation is required to ignore the precinct split element containing it.
precinct_id Integer Required The precinct_id specifies the precinct that comprises the precinct split. If the precinct_id field is invalid or not present, the implementation is required to ignore the precinct split element containing it.
electoral_district_id Integer Optional;
multiple allowed		 The electoral_district_id links to an electoral district (e.g., congressional district, state house district, school board district) that the precinct split belongs to. Highly Recommended if candidate information is to be provided. Multiple allowed and recommended to specify the geography of multiple electoral districts. If the electoral_district_id field is invalid or not present, the implementation is required to ignore the precinct element containing it. Takes precedence over any conflicting information in the parent precinct object.
polling_location_id Integer Optional; multiple allowed The polling_location_id specifies a link to the precinct split's polling location object. Multiple polling_location_id tags may be specified, but this use should be reserved for when multiple Election-Day-only vote locations serve specific precincts splits. Use the early_vote_site for early vote centers. If the polling_location_id field is invalid, the implementation is required to ignore it.

Example XML for a precinct split element: 

      <precinct_split id="104567">
        <name>Camelot_a</name>
        <precinct_id>4567</precinct_id>
        <electoral_district_id>100032</electoral_district_id>
        <electoral_district_id>100062</electoral_district_id>
        <polling_location_id>1325</polling_location_id>
      </precinct_split>

Election Administration

The Election Administration represents an institution for serving a locality's (or state's) election functions.

Tag Data type
Description Error handling
name String Optional The name specifies the name of the office/administration. While this field is optional for backwards compatibility reasons, it is recommended to be specified. Note the default value if unspecified. If the name field is invalid or not present, the implementation is required to use "Election Administration" as the default.
eo_id Integer Optional The eo_id links to the election official object for the person in charge of the office/administration. If the eo_id field is invalid or not present, the implementation is required to ignore it.
ovc_id Integer Optional The ovc_id links to the election official object for the contact person for overseas voters. If the ovc_id field is invalid or not present, the implementation is required to ignore it.
physical_address simpleAddressType Optional The physical_address element specifies the election administration's office street address. If the physical_address field is invalid or not present, the implementation is required to ignore it.
mailing_address simpleAddressType Optional The mailing_address element specifies the election administration's mailing address. If the mailing_address field is invalid or not present, the implementation is required to ignore it.
elections_url String Optional The elections_url specifies web address the administration's website. If the elections_url field is invalid or not present, the implementation is required to ignore it.
registration_url String Optional The registration_url specifies web address for information on registering to vote. If the registration_url field is invalid or not present, the implementation is required to ignore it.
am_i_registered_url String Optional The am_i_registered_url specifies the web address for information on whether an individual is registered. If the am_i_registered_url field is invalid or not present, the implementation is required to ignore it.
absentee_url String Optional The absentee_url specifies the web address for information on absentee or early voting. If the absentee_url field is invalid or not present, the implementation is required to ignore it.
where_do_i_vote_url String Optional The where_do_i_vote_url specifies web address for information on where an individual votes based on their address. If the where_do_i_vote_url field is invalid or not present, the implementation is required to ignore it.
rules_url String Optional The rules_url specifies a URL for the election rules and laws (if any) for the jurisdiction of the administration If the rules_url field is invalid the implementation is required to ignore it.
voter_services String Optional The voter_services item specify the services available voters at the election administration building. Services might include: registration, absentee ballot request, or early voting. Please use complete sentences. If the voter_services field is invalid or not present, the implementation is required to ignore it.
hours String Optional The hours element specifies the hours of operation (in local time) of the election administration office. If the hours field is invalid or not present, the implementation is required to ignore it.

Example XML for an election administration element: 

      <election_administration id="3456">
        <name>Howard County Board of Elections</name>
        <eo_id>12345</eo_id>
        <ovc_id>12346</ovc_id>
        <physical_address>
          <location_name>Government Center</location_name>
          <line1>12 Chad Ct.</line1>
          <city>Tempe</city>
          <state>AZ</state>
          <zip>88898</zip>
        </physical_address>
        <mailing_address>
          <line1>P.O. Box 32</line1>
          <city>Tempe</city>
          <state>AZ</state>
          <zip>88898</zip>
        </mailing_address>
        <elections_url>http://www.localelections.st.gov</elections_url>
        <registration_url>http://www.localelections.st.gov/register.html</registration_url>
        <am_i_registered_url>http://www.localelections.st.gov/check_reg.html</am_i_registered_url>
        <absentee_url>http://www.localelections.st.gov/early_absentee.html</absentee_url>
        <where_do_i_vote_url>http://www.localelections.st.gov/where_vote.html</where_do_i_vote_url>
        <rules_url>http://www.localelections.st.gov/election_law.html</rules_url>
        <voter_services>Early voting and absentee ballot request are available beginning October 1. Voter registration is always available.</voter_services>
        <hours>M-F 9am-6pm Sat 9am-Noon</hours>
      </election_administration>

Election Official

The Election Official object comprises the name and contact information for an election official.

Tag Data type
Description Error handling
name String Required The name specifies the election official's name If the name field is invalid or not present, the implementation is required to ignore the Election Official element containing it.
title String Optional The title element specifies the election official's title in the office. If the title field is invalid or not present, the implementation is required to ignore it.
phone String Optional The phone element specifies the election official's phone number, optionally including the extension. If the phone field is invalid or not present, the implementation is required to ignore it.
fax String Optional The fax element specifies the election official's fax number. If the fax field is invalid or not present, the implementation is required to ignore it.
email String Optional The email element specifies the election official's email address. If the email field is invalid or not present, the implementation is required to ignore it.

Example XML for an election official element: 

      <election_official id="1023">
        <name>Roberta Smith</name>
        <title>Registrar</title>
        <phone>(101) 555-1212</phone>
        <fax>(101) 555-1213</fax>
        <email>rsmith@state.gov</email>
      </election_official>

Polling Location

The Polling Location object represents a site where voters cast ballots on Election Day.

Tag Data type
Description Error handling
address simpleAddressType Required The address specifies the polling location's address. It also optionally includes the polling location's name (e.g., Springfield Elementary). If the address field is invalid or not present, the implementation is required to ignore the polling location element containing it.
directions String Optional The directions specify further instructions for locating the polling location. If the directions field is invalid or not present, the implementation is required to ignore it.
polling_hours String Optional The polling_hours field contains the hours (in local time) that Election Day polling locations are open. This information overrides any information specified in the Election object. If the polling_hours field is invalid or missing, the implementation is required to ignore it.

Example XML for a polling location element: 

      <polling_location id="4567">
        <address>
          <location_name>Springfield Elementary</location_name>
          <line1>123 Main St.</line1>
          <city>Springfield</city>
          <state>IL</state>
          <zip>44444</zip>
        </address>
        <directions>Enter through gym door.</directions>
        <polling_hours>7:30am-8:30pm</polling_hours>
      </polling_location>

Early Vote Site items

The Early Vote Site object represents a place where completed ballots can be returned prior to the election, or on Election Day. This object can represent: a registrar's office that offers early voting, a temporary early vote site, a ballot drop box, or similar location.

Tag Data type
Description Error handling
name String Optional The name specifies the ballot drop location's name. Including the name of the main service will be helpful: "Springfield Ballot Drop Location 2" or "East Springfield Early Vote Center" is preferred to "Springfield Center 2". If the name field is invalid or not present, the implementation is required to ignore it.
address simpleAddressType Required The address specifies the ballot drop location's address If the address field is invalid or not present, the implementation is required to ignore the ballot drop location element containing it.
state_id Integer Optional The state_id links to the ballot drop location's state. Either the state_id or locality_id is required. Use the state_id if the ballot can be dropped anywhere in the state. If the state_id field is invalid or not present, the implementation is required to ignore it.
locality_id Integer Optional The locality_id links to the ballot drop location's locality. Either the locality_id or state_id is required. Use the locality_id if the ballot must be dropped in the correct locality. If the state_id field is invalid or not present, the implementation is required to ignore it.
directions String Optional The directions specify further instructions for locating the ballot drop location. If the directions field is invalid or not present, the implementation is required to ignore it.
voter_services String Optional The voter_services item specify the services available voters at the ballot drop location. Services might include: registration, absentee ballot request, or early voting. Please use complete sentences. If the voter_services field is invalid or not present, the implementation is required to ignore it.
dates_times_open String Optional The dates_times_open item specify dates and times that the location is open for voter services. Please specify the exact dates (rather than "21 days before the election"), days of the week (e.g., "Monday through Saturday"), and times (e.g., "9am to 6pm"). If the dates_times_open field is invalid or not present, the implementation is required to ignore it.

Example XML for a polling location element: 

      <early_vote_site id="5467">
        <name>Springfield Ballot Drop</name>
        <address>
          <location_name>Early Vote Kiosk Number 52</location_name>
          <line1>321 Main St.</line1>
          <city>Springfield</city>
          <state>IL</state>
          <zip>44444</zip>
        </address>
        <state_id>32</state_id>
        <locality_id>101</locality_id>
        <directions>Next to Post Office.</directions>
        <voter_services>Early voting is available.</voter_services>
        <dates_times_open>October 1, 2008 to November 2, 2008. Mon-Fri: 9am - 6pm. Sat. and Sun.: 10am - 7pm.</dates_times_open>
      </early_vote_site>

Contest items

The Contest object represents a single contest, which could be between candidates, adoption of a resolution, or retention of judges (among other possibilities). The geographic scope of the Contest object is the Electoral District, which the Contest object links to.

Tag Data type
Description Error handling
election_id Integer Required The election_id specifies a link to the election under which this contest is being held. If the election_id is not present or invalid, the implementation is required to ignore the contest element containing it.
electoral_district_id Integer Required The electoral_district_id specifies a link to the electoral district for the contest (e.g., congressional district, state senate district). If the electoral_district_id is not present or invalid, the implementation is required to ignore the contest element containing it.
type String Required The type specifies the type of contest that is being run (i.e., general, primary, run-off, referendum). If the type field is invalid or not present, the implementation is required to ignore the contest element containing it.
partisan yesNoEnum Required The partisan field specifies whether the contest is partisan (i.e., the candidates are official affiliated with a party, including contests that are partisan primaries). Data should be either "yes" or "no". If the partisan field is invalid, the implementation is required to ignore it.
primary_party String Optional The primary_party field specifies the name of the party the contest is for, if this is a single-party contest (such as a Democratic primary). If the primary_party field is invalid, the implementation is required to ignore it.
electorate_specifications String Optional The electorate_specifications field specifies any changes to the eligible electorate for this contest past the usual, "all registered voters" electorate. This subtag will most often be used for primaries and local elections. In primaries, voters may have to be registered as a specific party to vote, or there may be special rules for which ballot a voter can pull. In some local elections, non-citizens can vote. If the electorate_specifications field is invalid, the implementation is required to ignore it, and the implementation may assume that all registered voters are eligible to vote.
special yesNoEnum Optional The special field specifies whether the contest is being held outside of the normal cycle for that office. Data should be either "yes" or "no"; the default is "no". If the special field is invalid, the implementation defaults to "no".
office String Optional The office field specifies the name of the office that the contest is deciding. If the office field is invalid, the implementation is required to ignore it.
number_elected Integer Optional The number_elected field specifies the number of candidates elected to the office in this contest. If the number_elected field is invalid or missing, the implementation defaults to 1.
number_voting_for Integer Optional The number_voting_for field specifies the number of candidates elected to the office in this contest. If the number_voting_for field is invalid or missing, the implementation defaults to 1.
ballot_id Integer Optional The ballot_id field specifies a link to the ballot for this contest. If the ballot_id field is invalid, the implementation is required to ignore it.
ballot_placement Integer Optional The ballot_placement the placement of this contest among the other contests in the election. For instance, the gubernatorial contest, on the top of the ballot, would have an a ballot_placement value of "1" and all of the congressional contests might have a value attribute of "2". Since each voter only votes in one congressional contest, there would be no ambiguity for ballot placement. If the ballot_placement field is invalid, the implementation is required to ignore it.

Example XML for a ballot element: 

    <contest id="122312">
      <election_id>12345</election_id>
      <type>Primary run-off</type>
      <electoral_district_id>37</electoral_district_id>
      <partisan>yes</partisan>
      <primary_party>Federalist</primary_party>
      <electorate_specifications>Must be registered with the party in question by August 10, 2008 to vote in the primary election.</electorate_specifications>
      <special>yes</special>
      <office>County supervisor</office>
      <number_elected>1</number_elected>
      <number_voting_for>1</number_voting_for>
      <ballot_id>30017</ballot_id>
      <ballot_placement>1</ballot_id>
    </contest>

Electoral District items

The Electoral District object represents the geographic area in which a single contest is held. Examples of Electoral District include: statewide, congressional district, a state senate district, and a fire district. The geographic area that comprises a Electoral District is defined by which precinct or precinct splits link to the Electoral District

Tag Data type
Description Error handling
name String Required The name specifies the electoral area's name If the name field is invalid or not present, the implementation is required to ignore the electoral area element containing it.
type String Optional The type specifies the type of electoral area (e.g., statewide, state senate district, state house district, fire district, congressional district, school district, etc.) If the type field is invalid or not present, the implementation is required to ignore it.
number Integer Optional The number specifies the district number of the district. Example: 34, in the case of the 34th State Senate District. If a number is not applicable, instead of leaving the field blank, leave this field out of the object; empty strings are not valid for xs:integer fields. If the number field is invalid or not present, the implementation is required to ignore it.

Two examples of electoral area element. 

      <electoral_district id="1000">
        <name>statewide</name>
        <type>statewide</type>
      </electoral_district>
      <electoral_district id="1034">
        <name>SD-34</name>
        <type>senate district</type>
        <number>34</number>
      </electoral_district>

Ballot items

The Ballot object represents the ballot for one contest. The Ballot object is linked to by the corresponding Contest object. The Ballot object links to the Candidate objects or Referendum objects that compose the ballot. Subtag data must appear in the order below.

Tag Data type
Description Error handling
referendum_id Integer Optional The referendum_id specifies a link to a referendum element, and is used to link to a single referendum item on a ballot. If the referendum_id field is invalid, the implementation is required to ignore it.
candidate_id Integer Optional; multiple allowed The candidate_id specifies a link to a candidate element, and is used to link to a single candidate on a ballot. Multiple (or zero) candidate_id tags may be present. This element has an optional attribute named order that may be specified, giving the ordering of the candidates as they appear on the actual ballot. If the candidate_id field is invalid, the implementation is required to ignore it.
custom_ballot_id Integer Optional The custom_ballot_id specifies a link to a custom ballot element, and is used to place an uncommon ballot element (e.g., recall, retention) on the ballot. If the candidate_id field is invalid, the implementation is required to ignore it.
write_in yesNoEnum Optional The write_in field specifies whether the ballot includes a place for write-ins. Valid items are "yes" and "no". If the write_in field is invalid, the implementation is required to default to "yes" if a candidate_id element is present and "no" otherwise.
image_url String Optional The image_url links to a picture of this specific ballot item (i.e., one contest). This is not a link to the entire ballot with multiple contests. Because of the hundreds (or thousands) of possible permutations of ballot items combining into one full ballot, this schema does not provide for the linking to a full ballot. If the image_url field is invalid, the implementation is required to ignore it.

Example XML for a ballot element: 

      <ballot id="234122">
        <candidate_id order="1">3705</candidate_id>
        <candidate_id order="2">3706</candidate_id>
        <write_in>yes</write_in>
        <image_url>http://elections.state.gov/ballots/images.php?race=sen15</image_url>
      </ballot>

Candidate items

The candidate object represents a candidate. If a candidate is running in multiple contests, the same Candidate object may be used provided that the candidate's name, party, etc. appear the same in the ballot items for both contests.

Tag Data type
Description Error handling
name String Required The name specifies the full complete name of the candidate, as it will appear on the ballot. If the name field is not present or invalid, the implementation is required to ignore the candidate element containing it.
party String Optional The party specifies the candidate's party affiliation If the party field is invalid the implementation is required to ignore it.
candidate_url String Optional The candidate_url specifies the URL for the candidate's official website If the candidate_url field is invalid the implementation is required to ignore it.
biography String Optional The biography specifies the candidate's biographical information. If the biography field is invalid the implementation is required to ignore it.
phone String Optional The phone specifies the candidate's phone number. If the phone field is invalid the implementation is required to ignore it.
photo_url String Optional The photo_url specifies the URL for a photo of the candidate. If the photo_url field is invalid the implementation is required to ignore it.
filed_mailing_address simpleAddressType Optional The filed_mailing_address specifies the mailing address the candidate when the candidate filed. If the filed_mailing_address field is invalid the implementation is required to ignore it.
email String Optional The email_address specifies the email address of the candidate. If the email_address field is invalid the implementation is required to ignore it.

Example XML for a candidate element: 

      <candidate id="3705">
        <name>Daniel Berlin</name>
        <party>Democrat</party>
        <website_url>http://www.dberlin.org</website_url>
        <bio>Daniel Berlin is a lawyer</bio>
        <phone>123-456-7890</phone>
        <photo>http://www.dberlin.org/dannyb.jpg</photo>
        <filed_mailing_address>
          <line1>123 Fake St.</line1><city>Rockville</city><state>OH</state><zip>20852</zip>
        </filed_mailing_address>
        <email_address>dberlin@example.org</email_address>
      </candidate>

Campaign Issue items

The campaign issue object represents an issue that candidates take positions on. A campaign issue object is linked to an election (not a contest) so that multiple candidates across contests can take positions on the same issue.

Tag Data type
Description Error handling
name String Required The name specifies the name of the issue. If the name field is not present or invalid, the implementation is required to ignore the campaign issue element containing it.
description String Optional The description specifies the a short explanation of the issue. If the description field is invalid the implementation is required to ignore it.
category String Optional The category specifies the classification of this issue according to the organization publishing issue information. If the category field is invalid the implementation is required to ignore it.
election_id Integer Required The election_id specifies the election for which this issue is relevant. If the election_id field is invalid the implementation is required to ignore the campaign issue element containing it.

Example XML for a campaign issue element: 

      <campaign_issue id="77777">
        <name>School Vouchers</name>
        <description>Whether to provide public funds to help parents pay for the private education of their children.</description>
        <category>Education</category>
        <election_id>1</election_id>
      </campaign_issue>

Candidate Statement items

The candidate statement object represents a position that a candidate has taken on an issue.

Tag Data type
Description Error handling
candidate_id Integer Required The candidate_id specifies the candidate who has taken a position on the issue. If the candidate_id field is not present or invalid, the implementation is required to ignore the candidate statement issue containing it.
campaign_issue_id Integer Required The campaign_issue_id specifies the campaign issue on which the candidate has taken a position. If the campaign_issue_id field is not present or invalid, the implementation is required to ignore the candidate statement issue containing it.
statement String Required The statement specifies the text of the candidates stated position on the issue. If the statement field is not present or invalid the implementation is required to ignore the candidate statement issue containing it.
date Date Optional The date specifies the date that the candidate made the statement. If the date field is invalid the implementation is required to ignore it.

Example XML for a candidate statement element: 

      <candidate_statement id="88888">
        <candidate_id>3705</candidate_id>
        <campaign_issue_id>77777</campaign_issue_id>
        <statement>I think they need to be studied more.</statement>
        <date>2008-06-01</date>
      </candidate_statement>

Referendum items

The Referendum object provides information about a referendum before the voters, including summary statements on each side.

Tag Data type
Description Error handling
title String Required The title specifies the full title of the referendum, as it will appear on the ballot. If the title field is not present or invalid, the implementation is required to ignore the referendum element containing it.
subtitle String Optional The subtitle specifies the subtile for a referendum, as it appears on the ballot below the title. If the subtitle field is invalid the implementation is required to ignore it.
brief String Optional The brief specifies a short summary of the referendum that is on the ballot below the title but above the text. If the brief field is invalid the implementation is required to ignore it.
text String Required The text specifies the full text of the referendum as it appears on the ballot. If the text field is not present or invalid the implementation is required to treat it as if the text was an empty string.
pro_statement String Optional The pro_statement specifies a statement in favor of the referendum. It does not necessarily appear on the ballot. If the pro_statement field is invalid the implementation is required to ignore it.
con_statement String Optional The con_statement specifies a statement in opposition to the referendum. It does not necessarily appear on the ballot. If the con_statement field is invalid the implementation is required to ignore it.
passage_threshold String Optional The passage_threshold specifies the threshold of votes that the referendum needs in order to pass. The default is a simple majority (50% plus one vote). Other common thresholds are "three-fifths" and "two-thirds". If the passage_threshold field is invalid or not present the implementation defaults to "simple majority" or 50% + one vote.
effect_of_abstain String Optional The effect_of_abstain specifies what effect abstaining (not voting) on this proposition will have (i.e., whether abstaining is considered a vote against it.) If the effect_of_abstrain field is invalid or not present the implementation is required to ignore it.
ballot_response_id Integer Required; multiple allowed The ballot_response_id specifies a link to a ballot response element. Multiple ballot_response_id tags may be present. This element has an optional attribute named order that may be specified, giving the ordering of the responses as they appear on the actual ballot. If no ballot_response_id field is invalid, the implementation is required to ignore the referendum element containing it.

Example XML for a candidate element: 

      <referendum id="30001">
        <title>Proposition 37</title>
        <subtitle>A referendum to give Daniel Berlin more money</subtitle>
        <text>Blah blah blah</text>
        <passage_threshold>three-fifths</passage_threshold>
        <effect_of_abstain>Abstaining is equivalent to voting no</effect_of_abstain>
        <ballot_response_id order="1">111111</ballot_response_id>
        <ballot_response_id order="2">111112</ballot_response_id>
      </referendum>

Custom Ballot items

A Custom Ballot object represents a ballot for a contest that neither pits candidates against each other nor is a referendum. Examples include recall elections and the retention of judges. A Custom Ballot object consists of multiple Ballot Response objects and it links to these objects.

Tag Data type
Description Error handling
heading String Required The heading specifies the text at the top of the ballot item. If the heading field is not present or invalid, the implementation is required to ignore the custom ballot element containing it.
ballot_response_id Integer Required; multiple allowed The ballot_response_id specifies a link to a ballot response element. Multiple ballot_response_id tags may be present. This element has an optional attribute named order that may be specified, giving the ordering of the elements as they appear on the actual ballot. If no ballot_response_id field is invalid, the implementation is required to ignore the custom ballot element containing it.

Example XML for a custom ballot element: 

      <custom_ballot id="50001">
        <heading>Should Judge Smith be retained?</heading>
        <ballot_response_id order="1">120001</ballot_response_id>
        <ballot_response_id order="2">120002</ballot_response_id>
      </custom_ballot>

Ballot Response items

A Ballot Response object represents a line on the ballot. Common examples might include "yes" or "no" for referenda, or a judge's name for a retention contest.

Tag Data type
Description Error handling
text String Required The text specifies the text of the response. If the text field is not present or invalid, the implementation is required to ignore the ballot response element containing it.

Four example XML's for a custom ballot response element: 

      <ballot_response id="120001">
        <text>Yes</text>
      </ballot_response>
    
      <ballot_response id="120002">
        <text>No</text>
      </ballot_response>
    
      <ballot_response id="120003">
        <text>Retain</text>
      </ballot_response>
    
      <ballot_response id="120004">
        <text>Do Not Retain</text>
      </ballot_response>

Street Segment

A Street Segment objection represents a portion of a street and the links to the precinct (and possibly precinct split) that this geography (i.e., segment) is contained within. The start address house number must be less than the end address house number unless the segment consists of only one address in which case these values are equal.

Tag Data type
Description Error handling
start_house_number Integer Required The start_house_number is the house number that street segment start at. This value is very necessary for the street segment to make any sense. It must be less than (or equal to) the end_house_number. If the start_house_number field is not present or invalid, the implementation is required to ignore the street segment element containing it. If the start_house_number is greater than the end_house_number the implementation may reverse the start or or end points or it may ignore the element containing it.
end_house_number Integer Required The end_house_number is the house number that street segment ends at. This value is very necessary for the street segment to make any sense. It must be greater than (or equal to) the start_house_number. If the end_house_number field is not present or invalid, the implementation is required to ignore the street segment element containing it. If the end_house_number is less than the start_house_number the implementation may reverse the start or or end points or it may ignore the element containing it.
odd_even_both oebEnum Optional The odd_even_both field specifies whether the odd side of the street (in terms of house numbers), the even side, or both are in included in the street segment. Valid strings are "odd", "even", or "both". It does not apply to start_apartment_number or end_apartment_number If the odd_even_both field is not present or invalid, the implementation is required default to odd.
start_apartment_number Integer Optional The start_apartment_number is the apartment number that street segment start at. If this value is present then start_house_number must be equal to end_house_number. If the start_apartment_number field is not present or invalid, the implementation is required to ignore it and assume no distinction is made between apartment along the street segment.
end_apartment_number Integer Optional The end_apartment_number is the apartment number that street segment ends at. If this value is present then start_house_number must be equal to end_house_number. If the end_apartment_number field is not present or invalid, the implementation is required to ignore it and assume no distinction is made between apartment along the street segment.
non_house_address detailAddressType Required The non_house_address is the common street address (as well as city, state, and zip) of the start and end points of the segment. Note the type is a detailAddressType; specific information such as street direction should be included. If the non_house_address field is not present or invalid, the implementation is required to ignore the street segment element containing it.
precinct_id Integer Required The precinct_id references the precinct that contains the entire street segment If the precinct_id field is not present or invalid, the implementation is required to ignore the street segment element containing it.
precinct_split_id Integer Optional The precinct_split_id references the precinct split that contains the entire street segment If the precinct_split_id field is not present or invalid, the implementation is required to ignore the it.

Example XML for a street segment element: 

      <street_segment id="1210001">
        <start_street_address_id>1000001</start_street_address_id>
        <end_street_address_id>1000002</end_street_address_id>
        <odd_even_both>both</odd_even_both>
        <non_house_address>
          <street_direction>E</street_direction>
          <street_name>Guinevere</street_name>
          <street_suffix>Dr</street_suffix>
          <address_direction>SE</address_direction>
          <apartment>616S</apartment>
          <state>VA</state>
          <city>Annandale</city>
          <zip>22003</zip>
        </non_house_address>
        <precinct_id>101001</precinct_id>
      </street_segment>

Detail Address (Type) items

A Detail Address is an address that includes details such as street direction. It is a type and not an object, so no ID is required.

Tag Data type
Description Error handling
house_number Integer Optional The house_number is the house number part of a street address. It may only be numeric. It is optional because: (1) some addresses do not have numbers ("A Second St."), (2) some addresses only have house number suffixes ("1/2 Second St."), and (3) a DetailAddress within a street_segment should not have a house number as it represents only the common aspects of the address. If the house_number field is not present or invalid, the implementation is required to ignore it. If both house_number and house_number_suffix are blank, the address represents the entire street.
house_number_suffix String Optional The house_number_suffix is the house number part of a street address. It may contain letters or slashes (e.g., B or 1/2). If the house_number field is not present or invalid, the implementation is required to ignore it. If both house_number and house_number_suffix are blank, the address represents the entire street.
street_direction String Optional The street_direction specifies the (inter-)cardinal direction of the street address (e.g., the "E" in "100 E Capitol St NE"). If the street_direction field is not present or invalid, the implementation is required to ignore it.
street_name String Required The street_name is the name of the street for the address. It optionally may contain street direction, street suffix or address direction (e.g., both "Capitol" and "E Capitol St NE" are acceptable for the address "100 E Capitol St NE"). If the street_name field is not present or invalid, the implementation is required to ignore the address element containing it.
street_suffix String Optional The street_suffix is the abbreviated, non-directional suffix to the street name. An example is "St" for the address "100 E Capitol St NE". If the street_suffix field is not present or invalid, the implementation is required to ignore it.
address_direction String Optional The address_direction specifies the (inter-)cardinal direction of the entire address. An example is "NE" for the address "100 E Capitol St NE". If the address_direction field is not present or invalid, the implementation is required to ignore it.
apartment String Optional The apartment specifies the intra-building address. A prefix (e.g., "Apt", "Suite") is optional. Examples are "Apt 303", "303", "4G", "4th Floor". If the apartment field is not present or invalid, the implementation is required to ignore it.
city String Required The city specifies the city or town of the address. If the city field is not present or invalid, the implementation is required to ignore the address element containing it.
state String Required The state specifies the two-letter state abbreviation of the address. If the state field is not present or invalid, the implementation is required to ignore the address element containing it.
zip String Required The zip specifies the zip code of the address. It may be 5 or 9 digits, and it may include a hypen ('-'). It is requires as it helps with geocoding, which is crucial for distributors. If the zip field is not present or invalid, the implementation is required to ignore the address element containing it.

Example XML for a Detail Addresses, which would appear within Street Segment objects: 

      <non_house_address>
        <street_direction>E</street_direction>
        <street_name>Guinevere</street_name>
        <street_suffix>Dr</street_suffix>
        <address_direction>SE</address_direction>
        <apartment>616S</apartment>
        <state>VA</state>
        <city>Annandale</city>
        <zip>22003</zip>
      </non_house_address>
    
      <non_house_address>
        <street_name>E Guinevere Dr</street_name>
        <address_direction>SE</address_direction>
        <apartment>616S</apartment>
        <city>Annandale</city>
        <state>VA</state>
        <zip>22003</zip>
      </non_house_address>


      <non_house_address>
        <house_number>1120B</house_number>
        <street_name>E Guinevere Dr SE</street_name>
        <city>Annandale</city>
        <state>VA</state>
        <zip>22003-2021</zip>
      </non_house_address>

Simple Address (Type) items

A Simple Address is an address that combines each address line into one string. It is a type and not an object, so no ID is required.

Tag Data type
Description Error handling
location_name String Optional The location_name is names of the location specified by the address. It is optional. Example: Martin Luther King, Jr. Library. If the location_name field is not present or invalid, the implementation is required to ignore it.
line1 String Required The line1 field is the first line of the address. It is required. Example: 1 Main St. NW If the line1 field is not present or invalid, the implementation is required to ignore the address element containing it.
line2 String Optional The line2 field specifies the second line of the address. Example: Second Floor If the line2 field is not present or invalid, the implementation is required to ignore it.
line3 String Optional The line3 field specifies the third line of the address. Example: Cambridge University, Carlton Hall If the line3 field is not present or invalid, the implementation is required to ignore it.
city String Required The city specifies the city or town of the address. If the city field is not present or invalid, the implementation is required to ignore the address element containing it.
state String Required The state specifies the two-letter state abbreviation of the address. If the state field is not present or invalid, the implementation is required to ignore the address element containing it.
zip String Optional The zip specifies the zip code of the address. It may be 5 or 9 digits, and it may include a hypen ('-'). It is requires as it helps with geocoding, which is crucial for distributors. If the zip field is not present or invalid, the implementation is required to ignore it.

Example XML for a Simple Addresses, which would appear within Polling Location and Early Vote Site items (among others): 

      <address>
        <line1;543 E Falls Church Rd. </line1>
        <line2gt;Second Floor</line2>
        <city>Annandale</city>
      </address>
    
      <address>
        <street_name>E Guinevere Dr</street_name>
        <address_direction>SE</address_direction>
        <apartment>616S</apartment>
        <city>Annandale</city>
        <zip>22003</zip>
      </address>


      <address>
        <house_number>1120B</house_number>
        <street_name>E Guinevere Dr SE</street_name>
        <city>Annandale</city>
      </address>

Revision information

Date Author Description
10-23-2007 dannyb Entry for initial draft.
10-24-2007 dannyb Added more top level items, finished off listing of tags
10-26-2007 dannyb Edited text of some entries, added race objects, registration info became a URL.
11-7-2007 Aaron Strauss Added geographic elements, including tabulation district. Added custom ballots.
11-12-2007 Aaron Strauss Added ballot drop location. Switched referendum to ballot response items. Added statewide tabulation area. Fixed typos.
11-21-2007 Aaron Strauss Races link to elections rather than the other way around
11-26-2007 Aaron Strauss Minor fixes to referendum (effect_of_abstain) and races (partisan and party_primary)
11-28-2007 dannyb Add a root element and rename a few elements for consistency/niceness.
12-05-2007 Aaron Strauss Minor changes.
12-15-2007 Aaron Strauss Races now called contests. Fixed documentation for contest.partisan, contest.primary_party, and referendum.effect_of_abstain. Added ballot.write_in.
01-08-2008 Aaron Strauss Added number of candidates elected and voting for in the Contest object. Added polling hours.
03-06-2008 Aaron Strauss Added source object. Added custom note object. Added election adminstration and election official objects. Added street segment and street address objects. Backwards Incompatibility: removed elections_url and rules_url from the state object; these fields are now in the election administration object linked from a state. The source object is required.
04-22-2008 Aaron Strauss Added campaign issues and candidate statements. Added two more tags in the source object. Added three more URLs to the election_administration object. Added inter-contest ordering to overall ballots. Backwards Incompatibility: Changed EIP to VIP.
06-24-2008 Aaron Strauss Added subtags to Ballot Drop Location, Election Administration, Contest, and Referendum. Backwards Incompatibility: Changed Candidate objects's subtag street_address to filed_mailing_address.
10-01-2008 Aaron Strauss Added subtags of mail-only and ballot_drop_location_id to precinct. Added subtag zip to street_address.
10-10-2008 Aaron Strauss Added voter_services subtag to election_administration. Allowed multiple polling_location_id subtags in the precinct and precinct_split objects.
05-19-2009 Aaron Strauss See Blog Posting for the numerous changes.