VxSuite TDP - v4
  • System Overview
    • Election Package
      • VxSuite Election Definition
      • Ballot Definition CDF
    • Hand Marked Ballots
    • Machine Marked Ballots
    • Cast Vote Records
    • VxScan Polls Reports
    • VxAdmin Results Exports
      • Tally Reports
      • Ballot Count Reports
      • CSV Exports
      • Write-In Adjudication Report
      • CDF ERR Export
    • Software Overview
    • User Roles
    • VxAdmin Function
    • VxCentralScan Function
    • VxAdmin & VxCentralScan Hardware
    • VxScan Function
    • VxScan Hardware
    • VxMark Function
    • VxMark Hardware
    • Ballot Interpretation
    • Diagnostics
    • Signed Hash Validation
  • System Performance & Specifications
    • Supported Voting Variations & Languages
    • System Limits
      • Maximum Tabulation Rate
    • Paper Ballot Specifications
    • Reliably Detectable Marks
    • Processing Capabilities
  • System Security, Auditing & Logging
    • System Security Architecture
      • Access Control
      • Artifact Authentication
        • Hashing of Continuously Exported Cast Vote Records
        • Preserving Voter Privacy
      • System Integrity
      • Networking
      • Password and Credential Policies
      • Defense-in-Depth and Least Privilege
      • Cryptography
    • Physical Security
    • Procedural and Operational Security
    • Audit Procedure
    • Logging
    • Vulnerability Management
    • Risk Assessment
    • Hardware Criticality and Supplier Analysis
  • Software Installation
    • Trusted Build
      • Build Machine Configuration
        • Installing Debian 12 on VxBuild
      • Online Phase
      • Offline Phase
      • Final Configuration
        • Secure Boot Signing
      • Hash/Checksum Verification of Dependencies
      • Virt Manager - Network Access & Troubleshooting
    • Imaging Machines
      • Preparing USB Drives for Imaging
      • Imaging
      • Basic Configuration Wizard
      • Verifying the Image Installed on a Machine
      • Software Installation Record Creation
  • System Operations & Training Manual
  • System Inspection & Logic and Accuracy Testing
  • System Maintenance Manual
  • Usability & Accessibility
  • Audio Visual & Display Screen Settings
  • Quality Assurance Manual
  • Warranty Model
  • Public Documents
Powered by GitBook
On this page
  • Core Election Attributes and Relationships
  • Election
  • Ballot Layout
  • Ballot Style
  • Contest
  • County
  • District
  • Party
  • Precinct
  • Ballot Strings
  • Instructional Text
  • Election-Specific Text
  • Example
  • Grid Layouts
  • Outset
  • Grid Position
  • Examples
Export as PDF
  1. System Overview
  2. Election Package

VxSuite Election Definition

PreviousElection PackageNextBallot Definition CDF

Last updated 5 months ago

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.

Attribute
Type
Description

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

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:

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.

Attribute
Type
Description

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

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

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

Attribute
Type
Description

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"

Candidate

Attribute
Type
Description

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

Yes-No Contest

Attribute
Type
Description

id

string

Contest description

yesOption

"Yes" option

noOption

"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"

Election-Specific Text

  1. The language-specific strings are used to accommodate multi-lingual voting on VxMark

The election-specific ballotStrings recognized by the system are the following:

Description
Key
Value

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

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",
      ...
    }
  },
  ...
}

Grid Layouts

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

Attribute
Type
Description

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

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

Contest identifier

optionId

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

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.

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

array -

array -

array -

array -

array -

array -

array -

array - IDs for

array - IDs for

string - ID for

string - ID for

In a candidate contest, the voter makes a selection between pre-defined candidates or write-in options. The following attributes extend the shared attributes:

array -

string - ID for

array - ID for

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

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 and cannot be changed without invalidating older ballots.

The core data model already includes names and labels. For example, the 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:

Including the translations in the election definition means they are included in the and cannot be changed without invalidating older ballots.

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

The language codes used are the 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 .

string, ID for

string - ID of

string - ID of or

string - ID of

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

IETF language tags
Hand Marked Ballots
here
Contest
Contest
Precinct
Ballot Layout
Ballot Strings
See Ballot Strings Section
Ballot Style
Contest
Grid Layouts
See Grid Layouts Section
County
District
Party
Precinct
Precinct
District
Party
District
Candidate
Party
Party
Yes-No Contest Option
Yes-No Contest Option
Ballot Style
Candidate
Contest
Yes-No Contest Option
Contest
Contest
District
Party
Party
Precinct
Ballot Style
Outset
Grid Position
Contest
Candidate
Yes-No Contest Option
Contest
Rectangle
ballot hash
ballot hash
Election Entity Relationship Diagram
Relationship of grid layouts to other entities in the election definition