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
    • SpecialBallotSelection

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:

  • CandidateSelection: Use this type of BallotSelection when the contest is for one or more candidates. It links the ballot selection to the Candidate elements.
  • PartySelection: Use this type of BallotSelection when the contest type is for a Party, such as for a party proportional contest.
  • BallotMeasureSelection: Use this type of BallotSelection to represent possible selections in a BallotMeasureContest.
  • SpecialBallotSelection: This type of BallotSelection is used for vote count aggregations (e.g. aggregating multiple candidates into "Others") and different kinds of non-votes (i.e. blank ballots, null or spoiled ballots, and "none of the above" votes).

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.
IncludedInAggregation 0 or 1 boolean Whether the selection's vote counts are included in the AggregateBallotSelection for the contest. Assumed false if unspecified.
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
IncludedInAggregation 0 or 1 boolean Whether the selection's vote counts are included in the AggregateBallotSelection for the contest. Assumed false if unspecified.
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 0 or 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"
            }
          ]
        },
        "Selection": {
          "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"
            }
          ]
        },
        "Selection": {
          "Text": [
            {
              "value": "Yes",
              "language": "en"
            }
          ]
        }
      }
    ]

SpecialBallotSelection

This type of BallotSelection is used for vote count aggregations (e.g. aggregating multiple candidates into "Others") and different kinds of non-votes (i.e. blank ballots, null or spoiled ballots, and "none of the above" votes).

SpecialBallotSelection should not be used in the general BallotSelection subelement of Contest and instead has its own distinct fields on Contest, namely AggregateBallotSelection, BlankBallotSelection, NoneOfTheAboveBallotSelection, and NullBallotSelection. See Contest elements for more details.

Elements

The following table describes the elements for SpecialBallotSelection:

Element Multiplicity Type Description
CountedInTotal 0 or 1 boolean Whether the entity selection's vote counts are counted in the total votes cast considered noteworthy. Assumed true if unspecified.
ExternalIdentifiers 0 or 1 ExternalIdentifiers Associates an ID with the ballot measure selection. A stable identifier is required.
Selection 1 InternationalizedText Provides a name for this ballot selection, such as "Others" or "None of the above".

Examples

XML

    <AggregateBallotSelection objectId="selection3">
      <Selection>
        <Text language="en">Other Candidates</Text>
      </Selection>
      <ExternalIdentifiers>
        <ExternalIdentifier>
          <Type>other</Type>
          <OtherType>stable</OtherType>
          <Value>selection3</Value>
        </ExternalIdentifier>
      </ExternalIdentifiers>
    </AggregateBallotSelection>
    <!-- Counts of ballots left blank -->
    <BlankBallotSelection objectId="selection4">
      <Selection>
        <Text language="en">Blank ballots</Text>
      </Selection>
      <!-- These ballots count in the total and can affect majorities -->
      <CountedInTotal>true</CountedInTotal>
      <ExternalIdentifiers>
        <ExternalIdentifier>
          <Type>other</Type>
          <OtherType>stable</OtherType>
          <Value>selection4</Value>
        </ExternalIdentifier>
      </ExternalIdentifiers>
    </BlankBallotSelection>
    <!-- Votes for "None of the above" option on the ballot -->
    <NoneOfTheAboveBallotSelection objectId="selection5">
      <!--
        The NOTA selection optiona as it appears on the ballot, often
        "None of the above", "None", or "Uncommitted"
      -->
      <Selection>
        <Text language="en">None</Text>
      </Selection>
      <!-- These ballots count in the total and can affect majorities -->
      <CountedInTotal>true</CountedInTotal>
      <ExternalIdentifiers>
        <ExternalIdentifier>
          <Type>other</Type>
          <OtherType>stable</OtherType>
          <Value>selection5</Value>
        </ExternalIdentifier>
      </ExternalIdentifiers>
    </NoneOfTheAboveBallotSelection>
    <!--
      Counts of null or spoiled ballots, i.e. ballots that have been marked in
      a way that the vote cannot be counted
    -->
    <NullBallotSelection objectId="selection5">
      <!--
        How these ballots are often called in a given country, often
        "null" or "spoiled"
      -->
      <Selection>
        <Text language="en">Spoiled ballots</Text>
      </Selection>
      <!--
        These ballots do count in the total and are treated as the same as
        if this vote did not happen at all
      -->
      <CountedInTotal>false</CountedInTotal>
      <ExternalIdentifiers>
        <ExternalIdentifier>
          <Type>other</Type>
          <OtherType>stable</OtherType>
          <Value>selection5</Value>
        </ExternalIdentifier>
      </ExternalIdentifiers>
    </NullBallotSelection>

JSON

    "AggregateBallotSelection": {
      "objectId": "selection3",
      "Selection": {
        "Text": {
          "@language": "en",
          "#text": "Other Candidates"
        }
      },
      "ExternalIdentifiers": {
        "ExternalIdentifier": {
          "Type": "other",
          "OtherType": "stable",
          "Value": "selection3"
        }
      },
    },
    "BlankBallotSelection": {
      "objectId": "selection4",
      "Selection": {
        "Text": {
          "@language": "en",
          "#text": "Blank Ballots"
        }
      },
      "CountedInTotal": true,
      "ExternalIdentifiers": {
        "ExternalIdentifier": {
          "Type": "other",
          "OtherType": "stable",
          "Value": "selection4"
        }
      }
    },
    "NoneOfTheAboveBallotSelection": {
      "objectId": "selection5",
      "Selection": {
        "Text": {
          "@language": "en",
          "#text": "None"
        }
      },
      "CountedInTotal": true,
      "ExternalIdentifiers": {
        "ExternalIdentifier": {
          "Type": "other",
          "OtherType": "stable",
          "Value": "selection5"
        }
      }
    },
    "NullBallotSelection": {
      "objectId": "selection5",
      "Selection": {
        "Text": {
          "@language": "en",
          "#text": "Spoiled ballots"
        }
      },
      "CountedInTotal": false,
      "ExternalIdentifiers": {
        "ExternalIdentifier": {
          "Type": "other",
          "OtherType": "stable",
          "Value": "selection5"
        }
      }
    }