VxSuite Election Definition
Last updated
Last updated
The VxSuite Election Definition is a data format for defining an election that is specific to VxSuite. It is a JSON file which defines the essential features of an election - metadata, contests, parties, precincts, districts, ballot styles, candidates, and more. In addition to defining that basic structure of the election, the format contains translations for any text which may appear on the ballots and ballot layouts to map the bubbles on each ballot to contest options.
The Election entity is the top-level entity that contains all other entities.
ballotLayout
Physical ballot metadata
ballotStrings
ballotStyles
All ballot styles
contests
All contests
gridLayouts
county
County metadata
date
string - YYYY-MM-DD
Date of the election
districts
All districts
id
string
Unique identifier
parties
All parties
precincts
All precincts
seal
string - SVG file format
Seal for the election
state
string
Name of the state
title
string
Title of the election
type
string - "general" or "primary"
Type of the election
The ballot layout entity includes basic information about the physical ballots used for the election.
paperSize
string
Indicates physical length of the ballot
metadataEncoding
string
Indicates how the ballot metadata will be encoded on the ballot
The paperSize attribute accepts the following valid options:
The metadataEncoding attribute must be "qr-code".
Each ballot style corresponds to a single- or multi-sheet ballot. The contests on a ballot style are determined by its associated districts - every contest belonging to an associated district is considered a part of the ballot style. A ballot style may be used in multiple precincts, one ballot style might correspond to multiple ballot PDFs that have identical contest layouts but different precinct labels.
id
string
Unique identifier
precincts
The IDs of all precincts which use the ballot style
districts
The IDs of all districts whose contests are included in the ballot style
partyId
Optional. The ID of the party to which the ballot belongs, if a primary
languages
array - string
Optional. The language codes for the languages covered by the ballot style
There are two types of contests - candidate contests and yes-no contests. Both types share core attributes:
id
string
Unique identifier
districtId
The associated district of the contest such as a state, county, or ward
title
string
Title of the contest
type
string - "candidate" or "yesno"
Type of the contest
In a candidate contest, the voter makes a selection between pre-defined candidates or write-in options. The following attributes extend the shared Contest attributes:
seats
number
The number of selections a voter can make
candidates
Candidate options for the contest
allowWriteIns
boolean
Whether the contest allows write-ins
partyId
Optional. The ID of the party to which the contest belongs, if a primary
termDescription
string
Optional. Description of the term of the position, such as "For three years"
id
string
Unique identifier
name
string
Name as it appears on the ballot
partyIds
Optional. The IDs of the parties associated with the candidate. The party name will appear next to the candidate
In a yes-no contest, also known as a ballot measure, the voter makes a selection between two options. The following attributes extend the shared Contest attributes:
id
string
Contest description
yesOption
"Yes" option
noOption
"No" option
id
string
Unique Identifier
label
string
Label e.g. "Yes" or "No"
One and only one county is associated with each election.
id
string
Unique Identifier
name
string
Name e.g. "Choctaw County"
Districts are used to define levels at which a contest takes place. For example, an election may have districts defined for the state, county, town, and ward levels. Different contests can be associated with each of those levels.
id
string
Unique Identifier
name
string
Name e.g. "State of Mississippi"
Parties are used in the data model either to associate candidates with a party, associate ballot styles with a party for a primary, associate contests with a party for a primary
id
string
Unique Identifier
name
string
Short name which will appear on the ballot besides candidates e.g. "Republican"
fullName
string
Full name which will appear in reports and in the titles of ballots e.g. "Democratic Party"
abbrev
string
Abbreviation for a party e.g. "R"
id
string
Unique Identifier
name
string
Name e.g. "Fire Station"
The ballotStrings object contains the translations for any text which may appear on the ballot. The text falls into one of two categories: instructional text or election-specific text.
Examples of instructional ballot text include:
"To vote, completely fill in the oval next to your choice."
"Vote for up to 3",
"Official Absentee Ballot"
Although the system does not use the hand marked ballot instructional text for any purpose, it must be included in the election definition for security purposes. When included, it becomes a part of the ballot hash and cannot be changed without invalidating older ballots.
The core data model already includes names and labels. For example, the Precinct entity already has a name attribute. The names within the data model are used by default in the system in reports and administrative menus. The translations for all of these names are within the ballotStrings and are important for two main reasons:
The language-specific strings are used to accommodate multi-lingual voting on VxMark
Including the translations in the election definition means they are included in the ballot hash and cannot be changed without invalidating older ballots.
The election-specific ballotStrings recognized by the system are the following:
Ballot Language
ballotLanguage
string
Ballot Style IDs
ballotStyleId
Candidate Names
candidateName
Contest Descriptions
contestDescription
Contest Option Labels
contestOptionLabel
Contest Terms
contestTerm
Contest Titles
contestTitle
County Name
countyName
string
District Names
districtName
Election Date
electionDate
string
Election Title
electionTitle
string
Party Full Names
partyFullName
Party Names
partyName
Precinct Names
precinctName
State Name
stateName
string
The language codes used are the IETF language tags for supported VxSuite languages: English, Spanish, Simplified Chinese, and Traditional Chinese.
Grid layouts describe where the bubbles and write-in areas exist on each ballot style. They must correspond exactly to the ballots used for the election in order for interpretation to succeed. For more information on the acceptable ballot format and its relationship to grid coordinates, see Hand Marked Ballots.
gridLayouts is an array which contains entities with the following attributes:
ballotStyleId
Identifies the ballot style
optionBoundsFromTargetMark
Describes where the entire contest option area sits relative to the bubble
gridPositions
Describes bubble and write-in positions on the ballot
The optionBoundsFromTargetMark field specifies an Outset entity. The purpose is to give the distance from the bubble to edges of the entire contest option e.g. the area that includes the bubble, the corresponding candidate's name, and some padding. The system uses this area during write-in-adjudication to highlight specific contest options for review.
top
number
Distance from center of bubble to top of option bounds
right
number
Distance from center of bubble to right of option bounds
bottom
number
Distance from center of bubble to bottom of option bounds
left
number
Distance between center of bubble to left of option bounds
Grid positions are defined positions on the ballot corresponding to bubbles that can be marked by a voter. The row and column coordinates of each grid position denote where the bubble is printed within the abstract "grid" created by the timing marks on the outer edges of the ballot. There are two types of positions - a standard option position corresponding to a candidate or option in the election definition or a write-in position corresponding to a write-in bubble and area on the ballot.
type
string - "option"
Indicates this is a standard option position
sheetNumber
number
1-indexed sheet number within the ballot style
side
string - "front" or "back"
Indicates side of the sheet
column
number
Column position of the bubble in the timing mark grid
row
number
Row position of the bubble in the timing mark grid
contestId
Contest identifier
optionId
Option identifier
type
string - "write-in"
Indicates this is a write-in option position
sheetNumber
number
1-indexed sheet number within the ballot style
side
string - "front" or "back"
Indicates side of the sheet
column
number
Column position of the bubble in the timing mark grid
row
number
Row position of the bubble in the timing mark grid
contestId
Contest identifier
writeInIndex
number
An index of the write-in position within the list of write-in positions for a contest (zero-indexed)
writeInArea
Area of the ballot to scan for a write-in
In some jurisdictions, a write-in can only be counted if the associated bubble is filled in as for any other option. In other jurisdictions, a write-in must be counted even if the bubble is not filled. In order to detect these write-ins, a writeInArea is defined for each write-in grid position. The Rectangle specifies the area.
x
number
Column start of the rectangle
y
number
Row start of the rectangle
width
number
Width of the rectangle
height
number
Height of the rectangle
Election definition examples are located in the vxsuite repository, such as here.
array -
array -
array -
array -
array -
array -
array -
array - IDs for
array - IDs for
string - ID for
string - ID for
array -
string - ID for
array - ID for
key-value pairs, IDs mapped to names
key-value pairs, IDs mapped to names
key-value pairs, IDs mapped to descriptions
key-value pairs, IDs mapped to labels
key-value pairs, IDs mapped to term descriptions
key-value pairs, IDs mapped to titles
key-value pairs, IDs mapped to names
key-value pairs, IDs mapped to their full names
key-value pairs, IDs mapped to their short names
key-value pairs, IDs mapped to names
string, ID for
string - ID of
string - ID of or
string - ID of
