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

CDF Class	VxSuite Attribute Requirements
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

CDF Enum	Allowed Values
ElectionType	general, primary
ReportingUnitType	county, precinct, split-precinct, state, other

Ignored Classes and Enums

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

Ignored Class Attributes

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

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

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

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.