Ballot Definition CDF
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 CDF Implementation
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.
Required Class Attributes
BallotDefinition
BallotFormat, Election, GpUnit, and Party are required
BallotFormat and Election must have a length of 1
GpUnit must have a minimum of length 1
BallotMeasureContest
BallotTitle, ContestOption, and FullText are required
ContestOption must have a length of 2
BallotStyle
ExternalIdentifier is required and must have a length of 1
Language must have a minimum length of 1
CandidateContest
BallotTitle and ContestOption are required
ContestOption must have a minimum of length 1
PrimaryPartyIds must have a length of 1 if it exists
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
At least one GpUnit must be defined with the type "state"
At least one GpUnit must be defined with the type "county"
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
Restricted Enums
ElectionType
general, primary
ReportingUnitType
county, precinct, split-precinct, state, other
Ignored Classes and Enums
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
Ignored Class 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
VxSuite CDF Conversion
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.
Attribute Mappings
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
Translations
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.
Geographies
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.
VxSuite CDF Limitations
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.
Last updated