# Election Package Specification

VxAdmin is configured with an election package (see [Configure VxAdmin](/vxsuite-user-manual-v3.1/central-system-setup/configure-vxadmin.md)), which specifies the details of the election as well as various settings for the system. This page documents the format of the election package.

## Overview

An election package is a ZIP file containing a number of JSON files:

* **election.json** - The election definition (contests, ballot styles, etc.)
* **systemSettings.json** - Settings for the various machines
* **metadata.json** - Documents the election package version

There may also be a few other files present that are not used in v3.1:

* **appStrings.json, vxElectionStrings.json** - Translations of voter-facing content
* **audioClips.jsonl, audioIds.json** - Audio recordings of voter-facing content

## Election Definition (election.json)

The election definition utilizes a customized version of the NIST Ballot Definition Common Data Format (CDF), which is specified here: 

* PDF: <https://doi.org/10.6028/NIST.SP.1500-20>
* Web-friendly UML: <https://github.com/usnistgov/BallotDefinition/blob/master/BallotDefinition_UML_Model_Documentation.md>

The VotingWorks election definition format (vxCDF) modifies NIST CDF in a few ways:

* It uses only a subset of the objects and fields defined in NIST CDF
* It extends the format with some additional fields to support data that is not included in NIST CDF

For documentation of the fields used in vxCDF, refer to the schema: <https://github.com/votingworks/vxsuite/blob/v3.1.0-release-branch/libs/types/src/cdf/ballot-definition/vx-schema.json>.

## System Settings (systemSettings.json)

The system settings uses a custom JSON format to define additional settings for the machines.

The system settings file uses the follow schema:

```json
{
  "type": "object",
  "properties": {
    "auth": {
      "type": "object",
      "properties": {
        "arePollWorkerCardPinsEnabled": { "type": "boolean" },
        "inactiveSessionTimeLimitMinutes": {
          "type": "number",
          "enum": [10, 15, 20, 30, 360]
        },
        "numIncorrectPinAttemptsAllowedBeforeCardLockout": {
          "type": "number",
          "enum": [3, 4, 5, 6, 7, 8, 9, 10]
        },
        "overallSessionTimeLimitHours": {
          "type": "number",
          "enum": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
        },
        "startingCardLockoutDurationSeconds": {
          "type": "number",
          "enum": [15, 30, 60]
        }
```

```json
      },
      "required": [
        "arePollWorkerCardPinsEnabled",
        "inactiveSessionTimeLimitMinutes",
        "numIncorrectPinAttemptsAllowedBeforeCardLockout",
        "overallSessionTimeLimitHours",
        "startingCardLockoutDurationSeconds"
      ],
      "additionalProperties": false
      },
    "markThresholds": {
      "type": "object",
      "properties": {
        "marginal": { "type": "number", "minimum": 0, "maximum": 1 },
        "definite": { "type": "number", "minimum": 0, "maximum": 1 },
        "writeInTextArea": { "type": "number", "minimum": 0, "maximum": 1 }
      },
      "required": ["marginal", "definite"],
      "additionalProperties": false
    },
    "centralScanAdjudicationReasons": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "UninterpretableBallot",
          "MarginalMark",
          "Overvote",
          "Undervote",
          "BlankBallot",
          "UnmarkedWriteIn"
        ]
      }
    },
    "precinctScanAdjudicationReasons": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "UninterpretableBallot",
          "MarginalMark",
          "Overvote",
          "Undervote",
          "BlankBallot",
          "UnmarkedWriteIn"
        ]
      }
    },
    "precinctScanDisallowCastingOvervotes": { "type": "boolean" }
  },
  "required": [
    "auth",
    "markThresholds",
    "centralScanAdjudicationReasons",
    "precinctScanAdjudicationReasons",
    "precinctScanDisallowCastingOvervotes"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.voting.works/vxsuite-user-manual-v3.1/reference/election-package-specification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.