vxsuite-election-definition.md

layout
title description tableOfContents outline pagination visible true visible visible true visible true visible true

VxSuite Election Definition

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.

Core Election Attributes and Relationships

Election Entity Relationship Diagram

Election

The Election entity is the top-level entity that contains all other entities.

Attribute	Type	Description
ballotLayout	Ballot Layout	Physical ballot metadata
ballotStrings	array - Ballot Strings	See Ballot Strings Section
ballotStyles	array - Ballot Style	All ballot styles
contests	array - Contest	All contests
gridLayouts	array - Grid Layouts	See Grid Layouts Section
county	County	County metadata
date	string - YYYY-MM-DD	Date of the election
districts	array - District	All districts
id	string	Unique identifier
parties	array - Party	All parties
precincts	array - Precinct	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

Ballot Layout

The ballot layout entity includes basic information about the physical ballots used for the election.

Attribute	Type	Description
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:

{% code fullWidth="false" %}

letter, legal, custom-8.5x17, custom-8.5x18, custom-8.5x21, custom-8.5x22

{% endcode %}

The metadataEncoding attribute must be "qr-code".

Ballot Style

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.

Attribute	Type	Description
id	string	Unique identifier
precincts	array - IDs for Precinct	The IDs of all precincts which use the ballot style
districts	array - IDs for District	The IDs of all districts whose contests are included in the ballot style
partyId	string - ID for Party	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

Contest

There are two types of contests - candidate contests and yes-no contests. Both types share core attributes:

Attribute	Type	Description
id	string	Unique identifier
districtId	string - ID for District	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

Candidate 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:

Attribute	Type	Description
seats	number	The number of selections a voter can make
candidates	array - Candidate	Candidate options for the contest
allowWriteIns	boolean	Whether the contest allows write-ins
partyId	string - ID for Party	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"

Candidate

Attribute	Type	Description
id	string	Unique identifier
name	string	Name as it appears on the ballot
partyIds	array - ID for Party	Optional. The IDs of the parties associated with the candidate. The party name will appear next to the candidate

Yes-No Contest

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:

Attribute	Type	Description
id	string	Contest description
yesOption	Yes-No Contest Option	"Yes" option
noOption	Yes-No Contest Option	"No" option

Yes-No Contest Option

Attribute	Type	Description
id	string	Unique Identifier
label	string	Label e.g. "Yes" or "No"

County

One and only one county is associated with each election.

Attribute	Type	Description
id	string	Unique Identifier
name	string	Name e.g. "Choctaw County"

District

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.

Attribute	Type	Description
id	string	Unique Identifier
name	string	Name e.g. "State of Mississippi"

Party

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

Attribute	Type	Description
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"

Precinct

Attribute	Type	Description
id	string	Unique Identifier
name	string	Name e.g. "Fire Station"

Ballot Strings

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.

Instructional 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.

Election-Specific Text

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:

1. The language-specific strings are used to accommodate multi-lingual voting on VxMark
2. 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:

Description	Key	Value
Ballot Language	ballotLanguage	string
Ballot Style IDs	ballotStyleId	key-value pairs, Ballot Style IDs mapped to names
Candidate Names	candidateName	key-value pairs, Candidate IDs mapped to names
Contest Descriptions	contestDescription	key-value pairs, Contest IDs mapped to descriptions
Contest Option Labels	contestOptionLabel	key-value pairs, Yes-No Contest Option IDs mapped to labels
Contest Terms	contestTerm	key-value pairs, Contest IDs mapped to term descriptions
Contest Titles	contestTitle	key-value pairs, Contest IDs mapped to titles
County Name	countyName	string
District Names	districtName	key-value pairs, District IDs mapped to names
Election Date	electionDate	string
Election Title	electionTitle	string
Party Full Names	partyFullName	key-value pairs, Party IDs mapped to their full names
Party Names	partyName	key-value pairs, Party IDs mapped to their short names
Precinct Names	precinctName	key-value pairs, Precinct IDs mapped to names
State Name	stateName	string

Example

{
  "ballotStrings": {
    "en": {
       ...
      "candidateNames": {
         "john-doe": "John Doe",
         "jane-doe": "Jane Doe".
         ...
      },
      "electionTitle": "General Election",
      "hmpbOfficialBallot": "Official Ballot",
      ...
    }
    "es-US": {
      ...
      "candidateNames": {
         "john-doe": "John Doe",
         "jane-doe": "Jane Doe".
         ...
      },
      "electionTitle": "Elecciones generales",
      "hmpbOfficialBallot": "Boleta oficial",
      ...
    }
  },
  ...
}

The language codes used are the IETF language tags for supported VxSuite languages: English, Spanish, Simplified Chinese, and Traditional Chinese.

Grid Layouts

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.

Relationship of grid layouts to other entities in the election definition

gridLayouts is an array which contains entities with the following attributes:

Attribute	Type	Description
ballotStyleId	string, ID for Ballot Style	Identifies the ballot style
optionBoundsFromTargetMark	Outset	Describes where the entire contest option area sits relative to the bubble
gridPositions	Grid Position	Describes bubble and write-in positions on the ballot

Outset

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.

Attribute	Type	Description
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 Position

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.

Option Grid Position

Attribute	Type	Description
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	string - ID of Contest	Contest identifier
optionId	string - ID of Candidate or Yes-No Contest Option	Option identifier

Write-In Grid Position

Attribute	Type	Description
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	string - ID of Contest	Contest identifier
writeInIndex	number	An index of the write-in position within the list of write-in positions for a contest (zero-indexed)
writeInArea	Rectangle	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.

Rectangle

Attribute	Type	Description
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

Examples

Election definition examples are located in the vxsuite repository, such as here.