The election definition within the election package can be a JSON Ballot Definition CDF Version 1.0 file. The full specification is defined by NIST and can be accessed on their website.
VxSuite accepts the Ballot Definition CDF Version 1.0 as defined by NIST without any data extensions. VxSuite requirements differ from the NIST CDF schema only in the following respects:
- Some fields not required in the NIST CDF are required in VxSuite
- Some enumeration values are more restricted in VxSuite than in the NIST CDF
- Some classes and attributes are ignored in VxSuite
The exact VxSuite schema is defined as a JSON schema in the vxsuite repository which is derived from the original NIST schema. The differences between the two are documented in the below tables.
| CDF Class | VxSuite Attribute Requirements |
|---|---|
| BallotDefinition |
|
| BallotMeasureContest |
|
| BallotStyle |
|
| CandidateContest |
|
| CandidateOption | CandidateIds must have a length of 1 |
| Election | BallotStyle, Contest, and ExternalIdentifier are required and all must have a minimum length of 1 |
| GpUnit |
|
| Office | Term is required |
| OptionPosition | Sheet is required |
| OrderedContest | Physical is required and must have a minimum length of 1 |
| Party | Abbreviation is required |
| PhysicalContest | PhysicalContestOption is required and must have a minimum length of 1 |
| PhysicalContestOption | ContestOptionId is required |
| ReportingUnit | Name is required |
| Term | Label is required |
| CDF Enum | Allowed Values |
|---|---|
| ElectionType | general, primary |
| ReportingUnitType | county, precinct, split-precinct, state, other |
| CDF Entity |
|---|
| ActivationContest |
| ActivationOption |
| AnnotatedString |
| AnnotatedUri |
| BallotMeasureType |
| CandidatePreElectionStatus |
| Coalition |
| ContactInformation |
| DayType |
| ElectionAdministration |
| GeoSpatialFormat |
| Hours |
| LatLng |
| OfficeGroup |
| OfficeTermType |
| OrderedHeader |
| PartyContest |
| PartyOption |
| PartyPreferenceContest |
| PartyRegistration |
| Person |
| RetentionContest |
| Schedule |
| ShortString |
| SpatialDimension |
| SpatialExtent |
| StraightPartyContest |
| StraightPartyRuleset |
| TimeWithZone |
| VoteVariation |
| CDF Class | Ignored Attributes |
|---|---|
| BallotDefinition | IsTest, Notes, OfficeGroup, Person, TestType |
| BallotMeasureContest | Abbreviation, BallotSubTitle, ContStatement, EffectOfAbstain, ExternalIdentifier, HasRotation, InfoUri, OtherType, OtherVoteVariation, PassageThreshold, ProStatement, SequenceOrder, SummaryText, TotalSubUnits, Type, VoteVariation |
| BallotMeasureOption | ExternalIdentifier, SequenceOrder |
| BallotStyle | ImageUri, Purpose |
| Candidate | CampaignSlogan, ContactInformation, ExternalIdentifier, FileDate, IsIncumbent, IsTopTicket, PartyId, PersonId, PreElectionStatus, ReadName |
| CandidateContest | Abbreviation, BallotSubTitle, ExternalIdentifier, HasRotation, NumberElected, NumberRunoff, OtherVoteVariation, RanksAllowed, SequenceOrder, TotalSubUnits, VoteVariation |
| CandidateOption | ExternalIdentifier, SequenceOrder |
| Election | ContactInformation, OtherType |
| Office | ContactInformation, Description, ElectionDistrictId, ExternalIdentifier, FilingDeadline, IsPartisan, OfficeHolderPersonIds |
| OrderedContest | OrderedContestOptionIds |
| Party | Color, ContactInformation, ExternalIdentifier, IsRecognizedParty, LeaderPersonIds, LogoUri, PartyScopeGpUnitIds, Slogan |
| ReportingUnit | AuthorityIds, ContactInformation, ElectionAdministration, ExternalIdentifier, IsDistricted, IsMailOnly, Number, OtherType, PartyRegistration, SpatialDimension, TotalSubUnits, VotersRegistered |
| Term | EndDate, StartDate, Type |
When importing a Ballot Definition CDF file, attributes will be mapped to the VxSuite Election Definition and used across the system in the exact same way.
| Ballot Definition CDF Attribute | VxSuite Election Definition Attribute |
|---|---|
| Election.ExternalIdentifier | Election.id |
| Election.Type | Election.type |
| Election.Name | Election.title |
| Election.StartDate | Election.date |
| GpUnit.id | County.id, Precinct.id, District.id |
| GpUnit.Name | Election.state, County.name, Precinct.name, District.name |
| Party.id | Party.id |
| Party.Name | Party.name |
| Party.Name | Party.fullName |
| Party.Abbreviation | Party.abbrev |
| Contest.id | Contest.id |
| Contest.BallotTitle | Contest.title |
| Contest.ElectionDistrictId | Contest.districtId |
| CandidateContest.VotesAllowed | CandidateContest.seats |
| CandidateContest.ContestOption.IsWriteIn | CandidateContest.allowWriteIns |
| CandidateContest.PrimaryPartyIds | CandidateContest.partyId |
| Office.Term.Label | CandidateContest.termDescription |
| Candidate.id | Candidate.id |
| Candidate.BallotName | Candidate.name |
| CandidateOption.EndorsementPartyIds | Candidate.partyIds |
| BallotMeasureContest.FullText | YesNoContest.description |
| BallotMeasureContestOption.id | YesNoContestOption.id |
| BallotMeasureContestOption.Selection | YesNoContestOption.label |
| BallotStyle.ExternalIdentifier.Value | BallotStyle.id |
| BallotStyle.GpUnitIds | BallotStyle.districts, BallotStyle.precincts |
| BallotStyle.PartyIds | BallotStyle.partyId |
| BallotStyle.Language | BallotStyle.languages |
| BallotFormat.ShortEdge | BallotLayout.width |
| BallotFormat.LongEdge | BallotLayout.height |
| OrderedContest.ContestId | GridPosition.contestId |
| PhysicalContestOption.OptionPosition.Sheet | GridPosition.sheet |
| PhysicalContestOption.OptionPosition.Side | GridPosition.side |
| PhysicalContestOption.OptionPosition.X | GridPosition.column |
| PhysicalContestOption.OptionPosition.Y | GridPosition.row |
| PhysicalContestOption.ContestOptionId | GridPositionOption.optionId |
| PhysicalContestOption.ContestOptionId | GridPositionWriteIn.writeInIndex |
| PhysicalContestOption.WriteInPosition.X | GridPositionWriteIn.writeInArea.x |
| PhysicalContestOption.WriteInPosition.Y | GridPositionWriteIn.writeInArea.y |
| PhysicalContestOption.WriteInPosition.W | GridPositionWriteIn.writeInArea.width |
| PhysicalContestOption.WriteInPosition.H | GridPositionWriteIn.writeInArea.height |
Most attributes in the Ballot Definition CDF that could require translation are defined with the CDF InternationalizedText class which allows specifying variants for each language. InternationalizedText maps directly onto VxSuite's ballot strings. When an InternationalizedText attribute is mapped to a ballot string, the English version is used as the default which will appear on reports and administrator interfaces while the translations are maintained in the election definition for multi-language experiences on voter devices.
The Ballot Definition defines all geographies as GpUnits, whereas the VxSuite Election Definition defines various geographies.
Some geographies must exist in the Ballot Definition CDF file to be used in VxSuite. There must be one GpUnit of type state and one of type county to populate the relevant metadata on the Election.
Any GpUnit of type precinct is mapped to a Precinct.
Any GpUnit with an associated contest is mapped to a District.
Because VxSuite does not utilize any data extensions to the Ballot Definition CDF, some information cannot be included when using the Ballot Definition CDF. The missing information creates some limitations when using the Ballot Definition CDF when compared to the VxSuite Election Definition format:
- Contest term descriptions (e.g. “2 years”) will always show up in English because there is no field in the CDF for internationalized term descriptions
- The full party name will be displayed for each candidate on VxMark (e.g. “Democratic Party” instead of “Democrat”) because the CDF only has one attribute for party name. In contrast, the VxSuite format supports two separate fields, one for the full name and one for showing on the ballot.
- When adjudicating write-ins, the highlighted contest option area will be set to a default because there is no field in the CDF for this parameter.
- Seal images are not supported in the CDF, so no seal will be shown in association with the election.