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.
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 & , < , and > , respectively
<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">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.
<name>Michael Smith</name>
<email_address>msmith@smithin2008.org</email_address>
</candidate>
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 |
Tag | Section |
---|---|
detailAddressType | Detail Address subtags |
simpleAddressType | Simple Address subtags |
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>
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>
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>
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>
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>
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>
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>
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. |
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>
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>
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>
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>
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>
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>
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. |
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>
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>
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>
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>
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>
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>
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>
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>
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>
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. |