VIP Format Specification Version 3.0

General Introduction

Welcome to the Voting Information Project's (VIP) open XML and flat file (CSV) format. This data format provides an easy way to produce data that lets programmers take a voter's address, compare it to street segments, and determine that voter's precinct (or precinct split). Knowing a voter's precinct allows information disseminators (such as Google and Microsoft) provide voters with their official polling locations (and early voting sites), ballots (including both candidates and referenda), local election administrations, and election officials.

General XML Specification

The actual election information specifies collections of elements, some containing links between each other. The entire set of tags must be encapsulated in a root object named vip_object. See the sample xml file and xsd file for more details.

Each top-level tag is a container for other fields, described in their own section. The only required top-level tags are the source object and the election object, each of which must be present exactly once. 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. The 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

Naming convention

The file containing the VIP feed should be named vipFeed-[FIPS code for state or county]-[election year]-[election month]-[election day].xml. If the file is zipped, the file extensions of .zip or .xml.zip are also acceptable.

For instance, vipFeed-19-2012-11-06.zip denotes Iowa's (the FIPS code for IA is 19) feed for the Nov 6, 2012 election.

Comma-delimited flat files (CSV)

If your office is producing flat files, they must be comma-delimited .txt files. The CSV column names differ slightly from XML tag names.

Examples of the flat files are below each XML example and include the necessary files to link those elements together as needed. To read more about the flat files, view complete file header templates, and review example files, you can do so in this GitHub repository.

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:


            


            

If your office is producing flat files, the source element is in a comma-delimited .txt file named source.txt. Example file for a source element:


          

Election items

The Election object represents an Election Day, which usually consists of many individual contests and/or referenda. A feed must contain exactly one Election object. All relationships in the feed (e.g., street segment to precinct [split] to polling location) are assumed to relate only to the Election specified by this object. It is permissible, and recommended, to combine unrelated contests (e.g., a special election and a general election) that occur on the same day into one feed with one Election object.
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:



            

If your office is producing flat files, the election element is in a comma-delimited .txt file named election.txt. Example file for an election element:


          

State items

The State object includes state-wide election information. The ID attribute is often the state's FIPS code. Subtag data must appear in the order below.
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.
early_vote_site_id Integer Optional;
multiple allowed
The early_vote_site_id specifies a link to the state's early vote or ballot drop locations. If early vote centers or ballot drop locations are state-wide (e.g., anyone in the state can use them), they should be specified here. If the early_vote_site_id field is missing or invalid, the implementation is required to ignore it.

Example XML for a state element:



            

If your office is producing flat files, the state element is in a comma-delimited .txt file named state.txt. Example file for a state element:


          

Locality items

The Locality object represents the jurisdiction below the state (e.g., county). Subtag data must appear in the order below.
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, village, 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.
early_vote_site_id Integer Optional;
multiple allowed
The early_vote_site_id specifies a link to the locality's early vote or ballot drop locations. If early vote centers or ballot drop locations are locality-wide, they should be specified here. If the early_vote_site_id field is missing or invalid, the implementation is required to ignore it. However, the implementation should still check to see if there are any early vote sites associated with this locality's state.

Example XML for a locality element:



            

If your office is producing flat files, the locality elements are in a comma-delimited .txt file named locality.txt. Example file for localities:


          

Precinct

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

While the id attribute does not have to be static across feeds for one election, the combination of vip_id, locality.name, precinct.ward, precinct.name, and precinct.number should remain constant across feeds for one election. (Note that not all of the fields just mentioned are required -- omitting those non-required fields is fine.
Tag Data type   Description Error handling
name String Required The name specifies the precinct's name (or number if no name exists) If the name field is invalid or not present, the implementation is required to ignore the precinct element containing it.
number String Optional The number specifies the precinct's number (e.g., 32 or 32A -- alpha characters are legal). Should be used if the name field is populated by a name and not a number. If the code field is invalid or not present, the implementation is required to ignore 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 if 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 early vote sites or ballot drop location. This tag is especially important for precinct-specific vote sites or drop locations, but should be disregarded for locality-level (i.e., county-level) sites where multiple drop locations serve multiple precincts. In this case, precinct multiple early_vote_site_id tags may be specified, but would constitute redundant information. If the early_vote_site_id field is missing or invalid, the implementation is required to ignore it with the following exception. In all cases, but especially if the precinct is mail-only: if the early_vote_site_id field is missing then the implementation is required to assume that any early_vote_site objects linked from this precinct's locality object are valid early vote/drop locations for this precinct.
ballot_style_image_url String Optional The ballot_style_image_url specifies a URL that points to an image of the ballot that a person who lives in this precinct will vote on. If multiple ballot styles exist in this precinct, ignore this field. If the ballot_style_image_url field is missing or invalid, the implementation is required to ignore it.

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.


            

            


            

If your office is producing flat files, the precinct elements are in a comma-delimited .txt file named precinct.txt. Example file for precincts:


          

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.
early_vote_site_id Integer Optional;
multiple allowed
The early_vote_site_id specifies a link to the precinct split's early vote sites or ballot drop location. This tag is especially important for precinct split-specific vote sites or drop locations, but should be disregarded for precinct-level or locality-level (i.e., county-level) sites where multiple drop locations serve multiple precinct splits. In this case, multiple early_vote_site_id tags at the precinct-split level may be specified, but would constitute redundant information. If the early_vote_site_id field is missing or invalid, the implementation is required to ignore it with the following exception. In all cases, but especially if the precinct-split is mail-only: if the early_vote_site_id field is missing then the implementation is required to assume that any early_vote_site objects linked from this precinct split's precinct object or (failing that) this precinct split's locality object are valid early vote/drop locations for this precinct split.
ballot_style_image_url String Optional The ballot_style_image_url specifies a URL that points to an image of the ballot that a person who lives in this precinct split will vote on. If the ballot_style_image_url field is missing or invalid, the implementation is required to ignore it.

Example XML for a precinct split element:



            

If your office is producing flat files, the precinct split elements are in a comma-delimited .txt file named precinct_split.txt. Example file for precinct_splits:


          

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.
what_is_on_my_ballot_url String Optional The what_is_on_my_ballot_url specifies web address for information on what is on an individual's ballot. If the whats_on_my_ballot_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:



            

If your office is producing flat files, the election administration elements are in a comma-delimited .txt file named election_administration.txt. Example file for election administration offices:


          

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:



            

If your office is producing flat files, the election official elements are in a comma-delimited .txt file named election_official.txt. Example file for election officials:


          

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.
photo_url String Optional The photo_url is a url that points to a picture of this polling location. At the moment, one picture is permitted per polling location, though multiple pictures may be allowed in future revisions. If the photo_url field is invalid or missing, the implementation is required to ignore it.

Example XML for a polling location element:



            

If your office is producing flat files, the polling location elements are in a comma-delimited .txt file named polling_location.txt. Example file for polling locations:



            

If your office is producing flat files, the polling location elements are linked to precincts or precinct splits through a comma-delimited .txt file named precinct_polling_location.txt or precinct_split_polling_location.txt. Example files for polling locations linked to precincts or precinct splits:


            

          

Early Vote Site items

The Early Vote Site object represents a place where ballots can be cast prior to the election, or drop boxes 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.
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 early vote/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.
start_date Date Optional Highly recommended. The start_date specifies the first date for early voting (or ballot drop-off) at this site. If the start_date field is invalid or not present, the implementation is required to ignore it and assume that the early vote site is operational.
end_date Date Optional Highly recommended. The end_date specifies the last date for early voting (or ballot drop-off) at this site. If the end_date field is invalid or not present, the implementation is required to ignore it and assume that the early vote site is operational.
days_times_open String Optional The days_times_open item specify dates and times that the location is open for voter services. Please specify the days of the week (e.g., "Monday through Saturday") and times (e.g., "9am to 6pm"). If the days_times_open field is invalid or not present, the implementation is required to ignore it.

Example XML for an early vote element:



            

If your office is producing flat files, the early vote site elements are in a comma-delimited .txt file named early_vote_site.txt. Example file for early vote sites:



            

If your office is producing flat files, the early vote site elements are linked to localities, state or precincts through a comma-delimited .txt file named locality_early_vote_site.txt, state_early_vote_site.txt or precinct_early_vote_site.txt. Example files for early vote sites linked to localities, state or precincts:


            

            

          

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 Optional 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". (This field may is a candidate for deletion.) 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 Highly recommended (except for referenda). The office field specifies the name of the office that the contest is deciding and should be identical to what the voter sees on his/her ballot. Should only be blank for referenda. If the office field is invalid, the implementation is required to ignore it.
filing_closed_date Date Optional The filing_closed_date field specifies the last date to file as a candidate for this contest. If the filing_closed_date 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. Numbers need not be consecutive. If the ballot_placement field is invalid, the implementation is required to ignore it. In this case, the implementation should order a ballot in a logical way (i.e., more important elections toward the top) but note that the actual order by be different.

Example XML for a contest element:



            

If your office is producing flat files, the contest elements are in a comma-delimited .txt file named contest.txt. Example file for contests:


          

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.


            


            

If your office is producing flat files, the electoral district elements are in a comma-delimited .txt file named electoral_districts.txt. Example file for electoral districts:



            

If your office is producing flat files, the electoral district elements are linked to precincts or precinct splits through a comma-delimited .txt file named precinct_electoral_district.txt or precinct_split_electoral_district.txt. Example files for electoral districts linked to precincts or precinct splits:


            

          

Ballot items

The Ballot object represents the ballot item 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. Deprecated and flagged for removal: This element has an optional attribute named sort_order that may be specified, giving the ordering of the candidates as they appear on the actual ballot; however, this tag is deprecated -- use candidate.sort_order instead. If the candidate_id field is invalid, the implementation is required to ignore it. If the sort_order attribute is invalid or missing the implementation is required to ignore it. In this case, the implementation should check for sort_order data in the candidate element. If none exists, the candidates should be ordered either alphabetically or randomly with a note specifying this ordering and that the true ballot ordering is likely to be different.
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:



            

If your office is producing flat files, the ballot elements are in a comma-delimited .txt file named ballot.txt. Example file for ballot records (races or referenda):


          

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 specifies the email address of the candidate. If the email field is invalid the implementation is required to ignore it.
sort_order Integer Optional Recommended. The sort_order specifies position of the candidate on the ballot item for that contest. If the sort_order field is invalid the implementation is required to: order the candidates either alphabetically or randomly with a note specifying this ordering and that the true ballot ordering is likely to be different.

Example XML for a candidate element:



            

If your office is producing flat files, the candidate elements are in a comma-delimited .txt file named candidate.txt. Example file for candidates:



            

If your office is producing flat files, the ballot elements are linked to candidates through a comma-delimited .txt file named ballot_candidate.txt. Example file for candidates linked to ballot records:


          

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 present or the field is invalid, the implementation is required to ignore the referendum element containing it.

Example XML for a referendum element:



            

If your office is producing flat files, the referendum elements are in a comma-delimited .txt file named referendum.txt. Example file for a referendum element:



            

If your office is producing flat files, the referendum elements are linked to ballot responses through comma-delimited .txt files named ballot_response.txt and referendum_ballot_response.txt. Example file for a referendum element linked to ballot responses and referendum ballot responses:


            

          

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 sort_order that may be specified, giving the ordering of the elements as they appear on the actual ballot. If the ballot_response_id field is missing or invalid, the implementation is required to ignore the custom ballot element containing it.

Example XML for a custom ballot element:



            

If your office is producing flat files, the custom ballot elements are in a comma-delimited .txt file named custom_ballot.txt. Example file for custom ballot records:


          

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.
sort_order Integer Optional Recommended. The sort_order specifies position of the punches on the ballot item for that type of contest. Recommended for types of contests where the positions of the punches are fixed. Numbers are relative (with lowest appearing first) and need not be consecutive. If the sort_order field is invalid the implementation is required to ignore it. The implementation should check for a sort order in the ballot element. If none exists, the candidates should be ordered either alphabetically or randomly with a note specifying this ordering and that the true ballot ordering is likely to be different.

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


	    

	    

	    


            

If your office is producing flat files, the custom ballot response elements are in a comma-delimited .txt file named custom_ballot_response.txt. Example file for custom ballot responses:


          

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. To specify any house on the street (or when using the "*" wildcard for street name), the best practice is to put 0 in this field. 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. To specify any house on the street (or when using the "*" wildcard for street name), the best practice is to put a very large number such as 999999 in this field. 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:



            

If your office is producing flat files, the street segment elements are in a comma-delimited .txt file named street_segment.txt. Example file for street segments:


          

Contest Result

A Contest Result item gives the contest-wide information (e.g., overvotes) for a given contest and a specified geography. In addition to id attribute, includes required attribute called certification of type certificationEnum.
Tag Data type   Description Error handling
contest_id Integer Required The contest_id references the contest that this result element refers to. If the contest_id field is not present or invalid, the implementation is required to ignore the contest result element containing it.
jurisdiction_id Integer Required The jurisdiction_id references the jurisdiction (e.g., state, locality, precinct, precinct split) that these results are from. This id number can refer to a state_id, locality_id, precinct_id, precinct_split_id, or (in the case of complete results) an electoral_district_id. Districts that split jurisdictions are fine, these results need not be for the entire referenced jurisdiction, just the part of the jurisdiction that intersects with the district. If the jurisdiction_id field is not present or invalid, the implementation is required to ignore the contest result element containing it.
entire_district yesNoEnum Required The entire_district field specifies whether the results represent the entire electoral district of the contest. The default is "no." If the entire_district field is not present or invalid, the implementation is required default to no.
total_votes Integer Optional The total_votes field represents the total number of all votes, including blank votes, overvotes, write-ins, and accepted provisional ballot. In the schema, total_votes = total_valid_votes + overvotes + blank votes. If the total_votes field is not present or invalid, the implementation is required to ignore it.
total_valid_votes Integer Optional The total_valid_votes field represents the total number of votes that counted for a candidate, including write-ins that were counted and accepted provisional ballot. This total excludes write-ins that were not tabulated, overvotes, blank votes, and rejected provisional ballots. If the total_valid_votes field is not present or invalid, the implementation is required to ignore it.
overvotes Integer Optional The overvotes field represents the number of votes in which the voter marked the ballot for more candidates than allowed. If the overvotes field is not present or invalid, the implementation is required to ignore it.
blank_votes Integer Optional The blank_votes field represents the number of votes that did not contribute to any valid candidate's total. Most common examples are: completely blank ballots and write-in ballots that were not aggregated. If the blank_votes field is not present or invalid, the implementation is required to ignore it.
accepted_provisional_votes Integer Optional The accepted_provisional_votes field represents the number of provisional votes that were accepted. If the accepted_provisional_votes field is not present or invalid, the implementation is required to ignore it.
rejected_votes Integer Optional The rejected_votes field represents the number of votes that were rejected, including both provisional ballots and judicially-rejected ballots. If the rejected_votes field is not present or invalid, the implementation is required to ignore it.

Example XML for a contest result element:



            

If your office is producing flat files, the contest result elements are in a comma-delimited .txt file named contest_results.txt. Example file for contest results:


          

Ballot Line Result (e.g. Candidate Result)

A Ballot Line Result provides the candidates' or referenda responses' vote totals. In addition to id attribute, includes required attribute called certification of type certificationEnum.
Tag Data type   Description Error handling
contest_id Integer Required The contest_id references the contest that this result element refers to. If the contest_id field is not present or invalid, the implementation is required to ignore the ballot line result element containing it.
jurisdiction_id Integer Required The jurisdiction_id references the jurisdiction (e.g., state, locality, precinct, precinct split) that these results are from. This id number can refer to a state_id, locality_id, precinct_id, precinct_split_id, or (in the case of complete results) an electoral_district_id. Districts that split jurisdictions are fine, these results need not be for the entire referenced jurisdiction, just the part of the jurisdiction that intersects with the district. If the jurisdiction_id field is not present or invalid, the implementation is required to ignore the ballot line result element containing it.
entire_district yesNoEnum Required The entire_district field specifies whether the results represent the entire electoral district of the contest. The default is "no." If the entire_district field is not present or invalid, the implementation is required default to no.
candidate_id Integer Optional The candidate_id references the candidate that these results apply to. If the candidate_id field is not present or invalid, the implementation should look for a ballot_response_id. If neither a candidate_id nor a ballot_response_id is present, the implementation is required to ignore the ballot line result element.
ballot_response_id Integer Optional The ballot_response_id references the ballot response element that these results apply to. Ignore this item for contests with candidates; use for referenda and custom ballots. If the ballot_response_id field is not present or invalid, the implementation should look for a ballot_response_id. If neither a ballot_response_id nor a candidate_id is present, the implementation is required to ignore the ballot line result element.
votes Integer Required The votes field represents the total number of votes that the candidate received. If the votes field is not present or invalid, the implementation is required to ignore the element containing it.
victorious yesNoEnum Optional Whether the candidate or referendum response was elected/won. Multiple candidates can have victorious=yes in elections which elect multiple candidates. This field is very optional and feed providers should feel no compunction to perform the interesting queries that may be needed to calculate this information. The victorious items always reflects the district-wide results, even in ballot_line_response objects that correspond to sub-jurisdictions of the district (e.g., a precinct in a congressional district). If the victorious field is not present or invalid, the implementation is required to ignore it.

Example XML for a ballot line result element:



            

If your office is producing flat files, the ballot line result elements are in a comma-delimited .txt file named ballot_line_result.txt. Example file for ballot line results:


          

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 each of house_number, house_number_suffix, and house_number_prefix is blank, the address represents the entire street.
house_number_prefix String Optional The house_number_prefix is the house number part of a street address. It may contain letters or slashes (e.g., 'B' in 'B22 Main St'). If the house_number_prefix field is not present or invalid, the implementation is required to ignore it. If each of house_number, house_number_suffix, and house_number_prefix is 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_suffix field is not present or invalid, the implementation is required to ignore it. If each of house_number, house_number_suffix, and house_number_prefix is 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. A special wildcard, "*", denotes every street in the given city/town. 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"), however this is not preferred. Preferred is street name alone (e.g. "Capitol"). 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 Highly recommended. The zip specifies the zip code of the address. It may be 5 or 9 digits, and it may include a hyphen ('-'). It is required 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 Detail Addresses, which would appear within Street Segment objects:


            

	    


          

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 Locations, Early Vote Sites, Candidates, and Election Administrations:


	    

            

          

Certification Enumeration

The Certification Enumeration provides information of the level of completeness of results.
Enumeration Description
unofficial_partial Results are unofficial and incomplete. Total is expected to increase.
unofficial_complete Results are unofficial, but complete. All sub-jurisdictions have reported. Results may change.
certified Results are complete and certified.

Term definitions

Required
Any implementation that does not implement things noted as required is not considered a conforming implementation.
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.