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

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

Ballot Layout

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

The paperSize attribute accepts the following valid options:

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

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.

Contest

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

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:

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:

Yes-No Contest Option

County

One and only one county is associated with each election.

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.

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

Precinct

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:

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.

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

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.

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

Write-In Grid Position

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

Examples

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