BallotSelection

  • BallotSelection is used to identify ballot selections in a contest.

  • BallotSelection includes CandidateSelection, PartySelection, and BallotMeasureSelection.

  • BallotSelection can be used with pre-election data and election results feeds.

  • BallotSelection is not used with officeholder feeds.

Use BallotSelection to identify the ballot selections in a contest, such as when you link candidates and parties to their vote counts.

This document discusses BallotSelection and its sub-entities:

  • BallotSelection
    • CandidateSelection
    • PartySelection
    • BallotMeasureSelection

Select one of the following feed types to learn more about how to use BallotSelection and its inherent elements with that type of feed.

BallotSelection

BallotSelection is an abstract element with three types that get used based on the type of contest:

Attributes

The following table describes the attributes for BallotSelection:

Attribute Required? Type Description
objectId Required ID Unique internal identifier that's used by other elements to reference this element.

Elements

The following table describes the elements for BallotSelection:

Element Multiplicity Type Description
SequenceOrder 0 or 1 integer

Specifies a default order for the ballot selection for display purposes.

If SequenceOrder isn't present in the feed, no order is assumed.

CandidateSelection

Use CandidateSelection to identify the ballot selections in a candidate contest, write-ins included.

CandidateSelection inherits the attributes and elements of BallotSelection. References to multiple Candidate elements can be included if necessary, for example, when the ballot selection is for a ticket of multiple candidates.

When multiple candidates are referenced for a ticket, it's sometimes important to preserve the ordering of the candidates. In these cases, we expect the generating application to list the references to Candidate elements within CandidateIds according to the ordering scheme that's in place. For example, the order of the candidates needs to match the same ordering of the Office element references within OfficeIds in the Contest of type CandidateContest.

If more than one Candidate object is referenced, they're presented to the user in the following order:

  • All candidates with IsTopTicket set to true are ordered ahead of all candidates without an IsTopTicket value. They, in turn, are ordered ahead of all candidates with IsTopTicket set to false. Ideally, the selection is set with either one candidate without an IsTopTicket value, or there are a pair of candidates, and one of them has IsTopTicket set to true. If these conditions aren't met, the following occurs:
    • All candidates with IsTopTicket set to true are presented in an undefined order.
    • All candidates with IsTopTicket not present are presented in an undefined order.
    • All candidates with IsTopTicket set to false are presented in an undefined order.

The XML syntax for CandidateSelection is the following: <BallotSelection xsi:type="CandidateSelection">.

Elements

The following table describes the elements for CandidateSelection:

Element Multiplicity Type Description
CandidateIds 1 IDREFS Unique identifiers for one or more Candidate elements. Use to associate a candidate with the candidate selection on the ballot. Also useful when the ballot selection is for multiple candidates, such as a ticket with President and Vice President selected together.
EndorsementPartyIds 0 or more IDREFS Unique identifier for two or more Party entities. This represents an arrangement where the political parties list the same candidate on a ballot.
IsWriteIn 0 or 1 boolean Indicates whether the candidate is a write-in. The default value is false.

Examples

XML

    <BallotSelection objectId="cs10861" xsi:type="CandidateSelection">
      <CandidateIds>can10861a can10861b</CandidateIds>
    </BallotSelection>

JSON

    "BallotSelection": [
      {
        "@type": "CandidateSelection",
        "objectId": "cs10861",
        "CandidateIds": [
          "can10861a",
          "can10861b"
        ]
      }
    ]

PartySelection

Use PartySelection to identify ballot selections that involve a party, such as a party list selection on the ballot.

PartySelection inherits the attributes and elements of BallotSelection. The XML syntax for PartySelection is the following: <BallotSelection xsi:type="PartySelection" ... />.

Elements

The following table describes the elements for PartySelection:

Element Multiplicity Type Description
PartyIds 1 IDREFS Unique identifier for one or more Party elements. Use to associate one or more parties with the party selection.

Examples

XML

    <BallotSelection objectId="ps150" xsi:type="PartySelection">
      <PartyIds>par100</PartyIds>
    </BallotSelection>

JSON

    "BallotSelection": [
      {
        "@type": "PartySelection",
        "objectId": "ps150",
        "PartyIds": [
          "par100"
        ]
      }
    ]

BallotMeasureSelection

Use BallotMeasureSelection to identify ballot selections that involve a ballot measure, such as referendums.

BallotMeasureSelection inherits the attributes and elements of BallotSelection. The XML syntax for BallotMeasureSelection is the following: <BallotSelection xsi:type="BallotMeasureSelection" ... />.

Elements

The following table describes the elements for BallotMeasureSelection:

Element Multiplicity Type Description
ExternalIdentifiers 1 ExternalIdentifiers Associates an ID with the ballot measure selection. A stable identifier is required.
Selection 1 InternationalizedText Provides an available choice for the ballot, such as Yes or No.

Examples

XML

    <BallotSelection objectId="bms00" xsi:type="BallotMeasureSelection">
      <ExternalIdentifiers>
        <ExternalIdentifier>
          <Type>other</Type>
          <OtherType>stable</OtherType>
          <Value>bmc0_yes</Value>
        </ExternalIdentifier>
      </ExternalIdentifiers>
      <Selection>
        <Text language="en">Yes</Text>
      </Selection>
    </BallotSelection>

JSON

    "BallotSelection": [
      {
        "@type": "BallotMeasureSelection",
        "objectId": "bms00",
        "ExternalIdentifiers": {
          "ExternalIdentifier" : [
            {
              "Type": "other",
              "OtherType": "stable",
              "Value": "bmc0_yes"
            }
          ]
        }
        "Text": [
          {
            "value": "Yes",
            "language": "en"
          },
        ]
      }
    ]

XML

    <BallotSelection objectId="bms00" xsi:type="BallotMeasureSelection">
      <ExternalIdentifiers>
        <ExternalIdentifier>
          <Type>other</Type>
          <OtherType>stable</OtherType>
          <Value>bmc0_yes</Value>
        </ExternalIdentifier>
      </ExternalIdentifiers>
      <Selection>
        <Text language="en">Yes</Text>
      </Selection>
    </BallotSelection>

JSON

    "BallotSelection": [
      {
        "@type": "BallotMeasureSelection",
        "objectId": "bms00",
        "ExternalIdentifiers": {
          "ExternalIdentifier" : [
            {
              "Type": "other",
              "OtherType": "stable",
              "Value": "bmc0_yes"
            }
          ]
        }
        "Text": [
          {
            "value": "Yes",
            "language": "en"
          },
        ]
      }
    ]