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.
<button value="pre-election">Pre-election data feeds</button> <button value="election">Election results feeds</button>

*** ** * ** ***

> [!NOTE]
> **Note:** This entity isn't used with officeholder feeds.

## 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](https://developers.google.com/civics-data/reference/contest#contest-elements) for more
details.

> [!NOTE]
> **Note:** This entity isn't used with officeholder feeds.

### Elements

The following table describes the elements for `SpecialBallotSelection`:

| Element | Multiplicity | Type | Description |
|---|---|---|---|
| `CountedInTotal` | 0 or 1 | [`boolean`](https://developers.google.com/civics-data/reference/simple-data-types#xs-boolean) | Whether the entity selection's vote counts are counted in the total votes cast considered noteworthy. Assumed `true` if unspecified. > [!NOTE] > **Note:** This should not be set on `AggregateBallotSelection` which is an aggregation of votes for standard ballot selections that will always count in the total. |
| `ExternalIdentifiers` | 0 or 1 | [`ExternalIdentifiers`](https://developers.google.com/civics-data/reference/external-identifier) | Associates an ID with the ballot measure selection. A [stable identifier](https://developers.google.com/civics-data/guides/stable-identifiers) is required. |
| `Selection` | 1 | [`InternationalizedText`](https://developers.google.com/civics-data/reference/internationalized-text) | Provides a name for this ballot selection, such as "Others" or "None of the above". |

### Examples

### XML

```xml
    <AggregateBallotSelection objectId="sbs-3">
      <Selection>
        <Text language="en">Other Candidates</Text>
      </Selection>
      <ExternalIdentifiers>
        <ExternalIdentifier>
          <Type>other</Type>
          <OtherType>stable</OtherType>
          <Value>sbs-3</Value>
        </ExternalIdentifier>
      </ExternalIdentifiers>
    </AggregateBallotSelection>
    <!-- Counts of ballots left blank -->
    <BlankBallotSelection objectId="sbs-4">
      <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>sbs-4</Value>
        </ExternalIdentifier>
      </ExternalIdentifiers>
    </BlankBallotSelection>
    <!-- Votes for "None of the above" option on the ballot -->
    <NoneOfTheAboveBallotSelection objectId="sbs-5">
      <!--
        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>sbs-5</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="sbs-6">
      <!--
        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>sbs-6</Value>
        </ExternalIdentifier>
      </ExternalIdentifiers>
    </NullBallotSelection>
      
```