Use `Contest` to describe a contest and link the contest to the associated
candidates and parties.

This document discusses `Contest` and its sub-entities:

- `Contest`
  - `CandidateContest`
  - `PartyContest`
  - `BallotMeasureContest`
  - `RetentionContest`

> [!NOTE]
> **Note:** This entity is the same for pre-election data and election results feed types. It isn't used with officeholder feeds.

### Types

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

- [`CandidateContest`](https://developers.google.com/civics-data/reference/contest#candidate-contest): Use this type when a `Contest` involves one or more candidates for an office.
- [`PartyContest`](https://developers.google.com/civics-data/reference/contest#party-contest): Use this type when a `Contest` has a party list selection on the ballot. This can also be used as a virtual contest that is a summary of a larger set of smaller contests.
- [`BallotMeasureContest`](https://developers.google.com/civics-data/reference/contest#ballot-measure-contest): Use this type when a `Contest` involves one or more ballot measures.
- [`RetentionContest`](https://developers.google.com/civics-data/reference/contest#retention-contest): Use this type when a `Contest` involves a referendum to decide if an elected official should stay in office or be removed from it.

As the results of an election are reported, you can update your feed to show
different stages of the results, such as exit polls or estimates. Google
provides guidance on which election stages and result types we expect. Google
can ask for one or multiple stages. These stage-type values might change during
election night. Set the initial feed value to the stage to start with. For more
details, see `CurrentResultsReportingStage` and
`ResultsReportingStageCollection` in the [Elements](https://developers.google.com/civics-data/reference/contest#contest-elements) section.

### Attributes

The following table describes the attributes for `Contest`:

| 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 `Contest`:

| Element | Multiplicity | Type | Description |
|---|---|---|---|
| `Abbreviation` | 0 or 1 | [`string`](https://developers.google.com/civics-data/reference/simple-data-types#xs-string) | Short name for the contest. |
| `AggregateBallotSelection` | 0 or 1 | [`SpecialBallotSelection`](https://developers.google.com/civics-data/reference/ballot-selection#special-ballot-selection) | Ballot selection for vote count aggregations, such as aggregating multiple candidates into "Others". |
| `BallotSelection` | 0 or more | [`BallotSelection`](https://developers.google.com/civics-data/reference/ballot-selection) | Associates the selections on the ballot with the contest. The order of candidates or parties in `Contest` must be the same as they are in [`BallotSelection`](https://developers.google.com/civics-data/reference/ballot-selection). If [`BallotSelection.SequenceOrder`](https://developers.google.com/civics-data/reference/ballot-selection#ballot-selection-elements) is present for every item, it's used as the default order for the selections. |
| `BallotSubTitle` | 0 or 1 | [`InternationalizedText`](https://developers.google.com/civics-data/reference/internationalized-text) | Subtitle of the contest, which must match how it appears on the voters' ballots. |
| `BallotTitle` | 0 or 1 | [`InternationalizedText`](https://developers.google.com/civics-data/reference/internationalized-text) | Title of the contest. The title text should correspond to the [syntax guide](https://developers.google.com/civics-data/reference/title-syntax). For Ballot Measure contests, the title should match the wording on the ballot. |
| `BlankBallotSelection` | 0 or 1 | [`SpecialBallotSelection`](https://developers.google.com/civics-data/reference/ballot-selection#special-ballot-selection) | Ballot selection for blank ballots. |
| `ComposingContestIds` | 0 or more | `IDREFS` | Used to define a rollup contest. For example, in the US presidential general election, there's a national-level contest with composing contest IDs for each of the state-level elections. A `ComposingContest` needs to be on a smaller scope than its parent contest and must take place in the same round of an election. |
| `ContestDateStatus` | 0 or 1 | [`DateStatus`](https://developers.google.com/civics-data/reference/date-status) | This element indicates scheduling updates for an election. The default value is `confirmed`. In most cases, it's best for the `ContestDateStatus` values to match the `ElectionDateStatus` of the `Election` that contains it. |
| `ContestDateType` | 0 or 1 | [`ElectionDateType`](https://developers.google.com/civics-data/reference/election-date-type) | This element indicates the way the contest is added to the calendar. If omitted, the default value is the `ElectionDateType` of the enclosing [`Election`](https://developers.google.com/civics-data/reference/election). Contests that have an on-or-before deadline and don't have a date set yet have a value of `bounded`. In most cases, it's best for the `ContestDateType` values to match the `ElectionDateType` of the [`Election`](https://developers.google.com/civics-data/reference/election) that contains it. |
| `CountingDate` | 0 or 1 | `PartialDate` | The post-voting date when counting happens for the election contest. This should only be included if the counting day is different from the last day of voting, for example the India Lok Sabha election. The common case is that counting happens on the same day as the last day of voting, that is the `EndDate` of the election. > [!NOTE] > **Note:** If this attribute is set, the date must be after the `EndDate`. |
| `CurrentResultsReportingStage` | 1 | [`ResultsReportingStageType`](https://developers.google.com/civics-data/reference/results-reporting-stage-type) | The current stage of results reporting for the contest. |
| `EarliestPollsClose` | 0 or 1 | [`dateTime`](https://developers.google.com/civics-data/reference/simple-data-types#xs-datetime) | When the first polls close. |
| `ElectoralDistrictId` | 1 | `IDREF` | Unique identifier for a [`GpUnit`](https://developers.google.com/civics-data/reference/gp-unit) element. Associates the contest with a reporting unit that represents the geographical scope of the contest, such as a district. For example, for a specific contest, `ElectoralDistrictId` might reference a `ReportingUnit` that's defined for the district associated with the contest. [`Office`](https://developers.google.com/civics-data/reference/office) also includes an optional reference that serves the same purpose. For example, for a national contest, you can reuse the same `GpUnit` that's defined for the country. |
| `ExternalIdentifiers` | 1 | [`ExternalIdentifiers`](https://developers.google.com/civics-data/reference/external-identifier) | Associates an ID with the contest. A [stable identifier](https://developers.google.com/civics-data/guides/stable-identifiers) is required. |
| `EndDate` | 0 or 1 | `PartialDate` | The calendar end date of the contest. Use the date for when polling ends, such as 2022-11-08. The end date should only be set if the start and end date of the `Contest` differ from the start and end date of the `Election`. > [!NOTE] > **Note:** If this attribute is set, the `StartDate` must also be set. Every `EndDate` must have a corresponding `StartDate`. |
| `EstimatedExpectedVotePercentage` | 0 or 1 | `float` | Often abbreviated as EEVP, this is the estimated percentage of the expected total vote that has been reported for this contest, as a number between 0 and 100. For example, report 24.2% as `24.2` and not `0.242`. |
| `FilingDeadline` | 0 or 1 | `PartialDate` | The date by which a candidate must file for the contest. |
| `HasRotation` | 0 or 1 | [`boolean`](https://developers.google.com/civics-data/reference/simple-data-types#xs-boolean) | Indicates whether the selections in the contest are rotated. If this element isn't present, the default value is `false`. |
| `IsNotable` | 0 or 1 | [`boolean`](https://developers.google.com/civics-data/reference/simple-data-types#xs-boolean) | Whether the entity is considered noteworthy. Assumed `false` if unspecified. > [!NOTE] > **Note:** This is an editorial decision left up to data providers to determine what is considered notable in a given election. |
| `LatestPollsClose` | 0 or 1 | [`dateTime`](https://developers.google.com/civics-data/reference/simple-data-types#xs-datetime) | When the last polls close. |
| `Name` | 1 | [`string`](https://developers.google.com/civics-data/reference/simple-data-types#xs-string) | This should match the `BallotTitle` in English and correspond to the [title syntax](https://developers.google.com/civics-data/reference/title-syntax). |
| `NoneOfTheAboveBallotSelection` | 0 or 1 | [`SpecialBallotSelection`](https://developers.google.com/civics-data/reference/ballot-selection#special-ballot-selection) | Ballot selection for the option on a ballot to vote for "None of the above" or some equivalent selection, such as "None", "None of these", or "Uncommitted". |
| `NullBallotSelection` | 0 or 1 | [`SpecialBallotSelection`](https://developers.google.com/civics-data/reference/ballot-selection#special-ballot-selection) | Ballot selection for null or spoiled ballots. These are ballots that have been marked in such a way that the vote cannot be counted properly. Examples of null ballots are ballots that have been torn, soiled, overmarked or undermarked, or marked in a way that would identify the voter. |
| `OutcomeDetermined` | 0 or 1 | [`boolean`](https://developers.google.com/civics-data/reference/simple-data-types#xs-boolean) | Whether the outcome of the election has been determined. - For contests with composing subcontests, this means that the outcome of all composing subcontests has been determined. - For candidate contests, this means that all candidates that won or advanced to the runoff have been called (whether projected or not) or the contest was canceled. - For party contests, this means that all seats have been called and marked as a seat won or the contests for the remaining seats were canceled. |
| `Seat` | 0 or 1 | [`string`](https://developers.google.com/civics-data/reference/simple-data-types#xs-string) | The specific seat the contest is for. |
| `SequenceOrder` | 0 or 1 | `integer` | The default ordering of `Contest` elements for the purpose of displaying results. The contests are displayed according to the following rules: - If two contests have identical values, they might be presented in an undefined order. - All contests with a `SequenceOrder` are presented in that order, followed by all contests without a `SequenceOrder` value in an undefined order. `SequenceOrder` is used to order the displayed results. For example, `100` could indicate a regional contest, `200` could indicate a local contest, and so on. `SequenceOrder` isn't appropriate to use as the contest order on the ballot; contest order on each ballot can be preserved, however, using the `BallotStyle` entity, which associates ballot styles with their corresponding geopolitical units. |
| `StartDate` | 0 or 1 | `PartialDate` | The calendar start date of the contest. Use the date for when polling begins, such as 2022-11-08. The start date should only be set if the start and end date of the `Contest` differ from the start and end date of the `Election`. > [!NOTE] > **Note:** If this attribute is set, the `EndDate` must also be set. Every `StartDate` must have a corresponding `EndDate`. |
| `SubsequentContestId` | 0 or 1 | `IDREF` | Used to point to a later contest in the same related set. In US elections for example, it usually points from a primary to its related general election. It can also point from a general election to a runoff election. A `SubsequentContest` usually has the same scope as its preceding contest. |
| `SubUnitsReported` | 0 or 1 | `integer` | The number of subunits that have completed reporting votes for this contest. > [!NOTE] > **Note:** This should be the most granular reporting unit available, e.g. polling stations or precincts. |
| `SummaryCounts` | 0 or more | [`SummaryCounts`](https://developers.google.com/civics-data/reference/counts#summary-counts) | Provides a summary of miscellaneous counts associated with the contest. This includes the total number of ballots cast that contain the contest, and the total number of abstentions, overvotes, undervotes, or write-ins. The summary counts can be associated with the contest as a whole or with other lower-level reporting units through use of multiple occurrences of `SummaryCounts`. |
| `TotalSeats` | 0 or 1 | `integer` | The total number of seats the electoral district for this contest can hold for the office. This is equivalent to seats up for election + seats carried over + vacant seats. |
| `TotalSubUnits` | 0 or 1 | `integer` | The total number of subunits that have this contest on the ballot. > [!NOTE] > **Note:** This should be the most granular reporting unit available, e.g. polling stations or precincts. |
| `VoteVariation` | 0 or 1 | [`VoteVariation`](https://developers.google.com/civics-data/reference/vote-variation) | The type of vote variation that's associated with the contest, such as `n-of-m`. |
| `OtherVoteVariation` | 0 or 1 | [`string`](https://developers.google.com/civics-data/reference/simple-data-types#xs-string) | Used to provide a custom value when `VoteVariation` is `other`. |
| `ResultsEmbargoEnd` | 0 or 1 | [`dateTime`](https://developers.google.com/civics-data/reference/simple-data-types#xs-datetime) | When an embargo on publishing election results ends. |
| `ResultsExpected` | 0 or 1 | [`dateTime`](https://developers.google.com/civics-data/reference/simple-data-types#xs-datetime) | When the first vote count results are expected to show up in the feed. |
| `ResultsLastUpdated` | 0 or 1 | [`dateTime`](https://developers.google.com/civics-data/reference/simple-data-types#xs-datetime) | When the results for the contest were last updated. |
| `ResultsReportingStageCollection` | 0 or 1 | N/A | Wrapper element for [`ResultsReportingStage`](https://developers.google.com/civics-data/reference/results-reporting-stage) definitions. For more details, read [Collection entities](https://developers.google.com/civics-data/reference/collections). For a composing contest (referenced by a parent contest's `ComposingContestIds`), you can set the optional [`boolean`](https://developers.google.com/civics-data/reference/simple-data-types#xs-boolean) child element `InheritFromComposedContest` to `true` to inherit the reporting stages from the composed contest. When `InheritFromComposedContest` is `true`, don't include any `ResultsReportingStage` elements in the collection. The contest must be listed in the `ComposingContestIds` of another contest. Otherwise, `ResultsReportingStage` must be present, and the collection should contain at least two `ResultsReportingStage` elements: one with `StageType` set to `no-results`, and at least one with `StageType` set to `preliminary` or `official`. > [!NOTE] > **Note:** When specifying stages directly, this collection should contain the full set of expected stages with their attribution, not just the current stage. Specify the current stage in `CurrentResultsReportingStage` instead. |

## CandidateContest

Use `CandidateContest` to describe a contest that involves the selection of one
or more candidates.

> [!NOTE]
> **Note:** This entity is the same for pre-election data and election results feed types. It isn't used with officeholder feeds.

This entity can optionally reference [`Office`](https://developers.google.com/civics-data/reference/office)
or [`Party`](https://developers.google.com/civics-data/reference/party) by ID. We don't support the
representation of a ticket of candidates into the same contest; you can only
reference one [`Office`](https://developers.google.com/civics-data/reference/office). So, as an example, for
a President and Vice President ticket, you would need two
[`Candidate`](https://developers.google.com/civics-data/reference/candidate?feed=election) contests. Each one
would reference a different office.

### Elements

The following table describes the elements for `CandidateContest`:

| Element | Multiplicity | Type | Description |
|---|---|---|---|
| `NumberElected` | 0 or 1 | `integer` | The number of candidates that are elected in the contest, which is the *n* of an `n-of-m` contest. If `NumberElected` isn't present in the feed, a default value of `1` is used. |
| `OfficeIds` | 1 | `IDREFS` | Unique identifier for one or more [`Office`](https://developers.google.com/civics-data/reference/office) elements. Associates an office description with the contest. |
| `PrimaryPartyIds` | 0 or more | `IDREFS` | Unique identifier for one or more [`Party`](https://developers.google.com/civics-data/reference/party) elements, which indicate that the `Contest` is part of a partisan primary. `PrimaryPartyId` is only meaningful in a primary election. |
| `VotesAllowed` | 1 | `integer` | The maximum number of votes or write-ins allowed per voter in this contest. If `VotesAllowed` isn't present in the feed, a default value of `1` is used. |
| `Type` | 0 or more | [`ElectionType`](https://developers.google.com/civics-data/reference/election-type) | The enumerated type of a contest, such as primary or general. The type of the `Contest` should only be set if it differs from the type of the `Election`. |

### Examples

### XML

```xml
    <Contest xsi:type="CandidateContest" objectId="c-1-001">
      <Abbreviation>KENYAPRES</Abbreviation>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs-1-001-kenyatta">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs-1-001-odinga">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs-1-001-mudavadi">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs-1-001-kenneth">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs-1-001-dida">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs-1-001-karua">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs-1-001-kiyiapi">...</BallotSelection>
      <BallotSelection xsi:type="CandidateSelection" objectId="cs-1-001-muite">...</BallotSelection>
      <BallotTitle>
        <Text language="en">2022 Kenya Presidential election</Text>
        <Text language="es">2022 Elecciones presidenciales de Kenia</Text>
        <Text language="fr">2022 Élection présidentielle au Kenya</Text>
      </BallotTitle>
      <CountStatus>...</CountStatus>
      <CountingDate>2022-08-11</CountingDate>
      <ElectoralDistrictId>...</ElectoralDistrictId>
      <EndDate>2022-08-09</EndDate>
      <Name>2022 Kenya Presidential election</Name>
      <StartDate>2022-08-09</StartDate>
      <SubUnitsReported>48</SubUnitsReported>
      <SummaryCounts>...</SummaryCounts>
      <TotalSubUnits>48</TotalSubUnits>
      <VoteVariation>1-of-m</VoteVariation>
      <NumberElected>1</NumberElected>
      <OfficeIds>off-9999a</OfficeIds>
      <VotesAllowed>1</VotesAllowed>
      <Type>general</Type>
    </Contest>
```

## PartyContest

Use `PartyContest` for a contest that where voters choose a party on the ballot.
This can also be used in an election results feed as a virtual summary contest
to communicate aggregated data (e.g. a State level Party contest that
aggregates constituency contest results.)

> [!NOTE]
> **Note:** This entity is the same for pre-election data and election results feed types. It isn't used with officeholder feeds.

### Elements

The following table describes the elements for `PartyContest`:

| Element | Multiplicity | Type | Description |
|---|---|---|---|
| `NumberElected` | 0 or 1 | `integer` | The number of candidates that are elected in the contest, which is the *n* of a `n-of-m` contest. If `NumberElected` isn't present in the feed, a default value of `1` is used. |
| `VotesAllowed` | 0 or 1 | `integer` | The maximum number of votes or write-ins allowed per voter in this contest. If `VotesAllowed` isn't present in the feed, a default value of `1` is used. |
| `OfficeIds` | 1 | `IDREFS` | Unique identifier for one or more [`Office`](https://developers.google.com/civics- data/reference/office?feed=election) elements. Associates an office description with the contest. |
| `Type` | 0 or more | [`ElectionType`](https://developers.google.com/civics-data/reference/election-type) | The enumerated type of a contest, such as primary or general. The type of the `Contest` should only be set if it differs from the type of the `Election`. |

### Examples

### XML

```xml
    <Contest xsi:type="PartyContest" objectId="c-20001">
      <BallotSelection objectId="ps-101321" xsi:type="PartySelection">
        <PartyIds>par-10132</PartyIds>
      </BallotSelection>
      <BallotSelection objectId="ps-101322" xsi:type="PartySelection">
        <PartyIds>par-10133</PartyIds>
      </BallotSelection>
      <BallotTitle>
        <Text language="en">Ballot title example</Text>
      </BallotTitle>
      <ContestDateStatus>confirmed</ContestDateStatus>
      <CountingDate>2022-08-11</CountingDate>
      <ElectoralDistrictId>...</ElectoralDistrictId>
      <EndDate>2022-08-09</EndDate>
      <ExternalIdentifiers>...</ExternalIdentifiers>
      <Name>Contest name example</Name>
      <StartDate>2022-08-09</StartDate>
      <VoteVariation>1-of-m</VoteVariation>
      <OfficeIds>off-9999a</OfficeIds>
      <Type>general</Type>
      <VotesAllowed>1</VotesAllowed>
    </Contest>
```

## BallotMeasureContest

Use `BallotMeasureContest` for a contest that involves ballot measures.

> [!NOTE]
> **Note:** This entity is the same for pre-election data and election results feed types. It isn't used with officeholder feeds.

### Elements

The following table describes the elements for `BallotMeasureContest`:

| Element | Multiplicity | Type | Description |
|---|---|---|---|
| `BallotTitle` | 1 | [`InternationalizedText`](https://developers.google.com/civics-data/reference/internationalized-text) | The ballot's official title, such as `Nevada Renewable Energy Standards Initiative`. Make sure the `BallotTitle` is unique. Some referendums have a single collective title with multiple numbered questions. In these cases, the title can include the question number to distinguish between the `BallotMeasureContest` entities created for each question. |
| `BallotSubTitle` | 0 or 1 | [`InternationalizedText`](https://developers.google.com/civics-data/reference/internationalized-text) | The ballot's subtitle, if one exists. |
| `BallotText` | 1 | [`InternationalizedText`](https://developers.google.com/civics-data/reference/internationalized-text) | The text that appears on the ballot itself. For example: `Shall Article 4 of the Nevada Constitution be amended to require, beginning in calendar year 2022, that all providers of electric utility services who sell electricity... in Nevada comes from renewable energy resources?` |
| `FullText` | 0 or 1 | [`InternationalizedText`](https://developers.google.com/civics-data/reference/internationalized-text) | A copy of the full text of the ballot measure. Provide this element if there's additional text not included on the ballot itself. Limited to 30,000 characters. If the full text of the ballot measure is shorter than 30,000 characters and does not include any formatting that would be invalid in a feed file, include it in `FullText`. Also include `InfoUri` with an annotated URI of `fulltext`. Otherwise, only include the URI with a `fulltext` annotation. |
| `InfoUri` | 0 or 1 | [`AnnotatedUri`](https://developers.google.com/civics-data/reference/uri-annotation) | An annotated URI that accepts the following annotations, rather than the annotations listed elsewhere: - `wikipedia`: A Wikipedia page about the ballot measure - `ballotpedia`: A Ballotpedia page about the ballot measure. For example, `https://ballotpedia.org/Nevada_Renewable_Energy_Standards_Initiative_(2020)` - `official-website`: The official website for the ballot measure - `fulltext`: If there's more text than what's included on the ballot, such as a copy of the proposed law, this is a URI for the full additional text. The following is an example: `https://www.nvsos.gov/sos/home/showdocument?id=5330` - `logo-uri`: The image of the logo |
| `SummaryText` | 0 or 1 | [`InternationalizedText`](https://developers.google.com/civics-data/reference/internationalized-text) | A summary of the ballot measure. Consists of one to two short paragraphs and can be generated by the partner to summarize the full text of the ballot, like the following example: `Requires utilities to acquire 50 percent of their electricity from renewable resources by 2030` `Official Summary:` `EXPLANATION---This ballot measure proposes to amend Article 4 of the Nevada Constitution to require all providers of electric utility services that sell electricity to retail customers for consumption in Nevada to meet a Renewable Portfolio Standard (RPS) that would go into effect beginning in calendar year 2022 and increase gradually until the RPS reaches 50 percent in calendar year 2030. According to the Public Utilities Commission of Nevada, an RPS establishes the percentage of electricity sold by an electric utility to retail customers that must come from renewable sources.` |
| `ProStatement` | 0 or 1 | [`InternationalizedText`](https://developers.google.com/civics-data/reference/internationalized-text) | A statement that explains what a *Yes* vote on this ballot measure means. It isn't an argument in favor of the measure. For example: `A "yes" vote supports this initiative to require electric utilities to acquire 50 percent of their electricity from renewable resources by 2030.` |
| `ConStatement` | 0 or 1 | [`InternationalizedText`](https://developers.google.com/civics-data/reference/internationalized-text) | A statement that explains what a *No* vote on this ballot measure means. It isn't an argument against the measure. For example: `A "no" vote opposes this initiative, thus keeping the existing requirement that electric utilities acquire 25 percent of their electricity from renewable resources by 2025.` |
| `Type` | 0 or 1 | [`BallotMeasureType`](https://developers.google.com/civics-data/reference/ballot-measure-type) | An enumerated type of a ballot measure. Select the value that best describes the ballot measure in its jurisdiction. |
| `PassageThreshold` | 0 or 1 | [`string`](https://developers.google.com/civics-data/reference/simple-data-types#xs-string) | The minimum share of votes required for a motion to pass. |

### Examples

### XML

```xml
     <Contest objectId="c-0" xsi:type="BallotMeasureContest">
        <BallotSelection objectId="bms-00" xsi:type="BallotMeasureSelection">
          <ExternalIdentifiers>
            <ExternalIdentifier>
              <Type>other</Type>
              <OtherType>stable</OtherType>
              <Value>bms-00-yes</Value>
            </ExternalIdentifier>
          </ExternalIdentifiers>
          <Selection>
            <Text language="en">Yes</Text>
          </Selection>
        </BallotSelection>
        <BallotSelection objectId="bms-01" xsi:type="BallotMeasureSelection">
          <ExternalIdentifiers>
            <ExternalIdentifier>
              <Type>other</Type>
              <OtherType>stable</OtherType>
              <Value>bms-01-no</Value>
            </ExternalIdentifier>
          </ExternalIdentifiers>
          <Selection>
            <Text language="en">No</Text>
          </Selection>
        </BallotSelection>
        <BallotSubTitle>
          <Text language="en">Farm Animal Confinement Initiative</Text>
        </BallotSubTitle>
        <BallotTitle>
          <Text language="en">
            California Proposition 12, Farm Animal Confinement Initiative (2018)
          </Text>
        </BallotTitle>
        <ElectoralDistrictId>ru-ca-1</ElectoralDistrictId>
        <ExternalIdentifiers>
          <ExternalIdentifier>
            <Type>other</Type>
            <OtherType>stable</OtherType>
            <Value>c-0</Value>
          </ExternalIdentifier>
        </ExternalIdentifiers>
        <Name>
          California Proposition 12, Farm Animal Confinement Initiative (2018)
        </Name>
        <BallotText>
          <Text language="en">
            Establishes minimum requirements for confining certain farm animals. Prohibits sales of meat and egg products from animals confined in noncomplying manner. Fiscal Impact: Potential decrease in state income tax revenues from farm businesses, likely not more than several million dollars annually. State costs up to $10 million annually to enforce the measure.
          </Text>
        </BallotText>
        <ConStatement>
          <Text language="en">No means the measure will not be enacted
          </Text>
        </ConStatement>
        <InfoUri Annotation="fulltext">
          https://example-government.gov/ballot-measures/California_Proposition_12_2018
        </InfoUri>
        <InfoUri Annotation="wikipedia">
          https://en.wikipedia.org/wiki/2018_California_Proposition_12
        </InfoUri>
        <PassageThreshold>
          <Text language="en">50.01%</Text>
        </PassageThreshold>
        <ProStatement>
          <Text language="en">Yes means the measure will be enacted
          </Text>
        </ProStatement>
        <SummaryText>
          <Text language="en">
            The proposition establishes new minimum requirements on farmers to provide more space for egg-laying hens, breeding pigs, and calves raised for veal. California businesses will be banned from selling eggs or uncooked pork or veal that came from animals housed in ways that did not meet these requirements.
          </Text>
        </SummaryText>
        <Type>ballot-measure</Type>
      </Contest>
```

## RetentionContest

Use this type when a `Contest` involves a referendum to decide if an elected
official should stay in office or be removed from it.

This includes cases such as judicial retention contests in some US states which
decide if a judge should continue for another term. It also applies for recall
elections which decide if an officeholder should be removed before that
official's term of office has ended.

### Elements

All elements from [`BallotMeasureContest`](https://developers.google.com/civics-data/reference/contest#ballot-measure-contest) also apply
to `RetentionContest`.

| Element | Multiplicity | Type | Description |
|---|---|---|---|
| `CandidateId` | 1 | IDREF | The ID of the candidate representing the officeholder who currently holds the office |
| `OfficeId` | 0 or 1 | IDREF | The ID of the office the officeholder currently holds |

### Examples

### XML

```xml
        <Contest objectId="c-40001" xsi:type="RetentionContest">
        <!-- Retention contest selections are actually BallotMeasureSelection
          objects, and should use the 'bms-' objectId prefix.-->
          <BallotSelection objectId="bms-40001a" xsi:type="BallotMeasureSelection">
            <ExternalIdentifiers>
              <ExternalIdentifier>
                <Type>other</Type>
                <OtherType>stable</OtherType>
                <Value>bms-40001a</Value>
              </ExternalIdentifier>
            </ExternalIdentifiers>
          <Selection label="bms-40001at">
            <Text language="en">Yes</Text>
          </Selection>
          </BallotSelection>
          <BallotSelection objectId="bms-40001b" xsi:type="BallotMeasureSelection">
            <ExternalIdentifiers>
              <ExternalIdentifier>
                <Type>other</Type>
                <OtherType>stable</OtherType>
                <Value>bms-40001b</Value>
              </ExternalIdentifier>
            </ExternalIdentifiers>
          <Selection label="bms-40001bt">
            <Text language="en">No</Text>
          </Selection>
          </BallotSelection>
          <BallotTitle>
            <Text language="en">Retention of Supreme Court Justice</Text>
          </BallotTitle>
          <ElectoralDistrictId>ru-0002</ElectoralDistrictId>
          <ExternalIdentifiers>
            <ExternalIdentifier>
              <Type>other</Type>
              <OtherType>stable</OtherType>
              <Value>c-vageneral-2013-va16-country-us</Value>
            </ExternalIdentifier>
          </ExternalIdentifiers>
          <Name>Judicial Retention, Supreme Court</Name>
          <CandidateId>can-12345</CandidateId>
          <OfficeId>off-20006</OfficeId>
        </Contest>
      
      
```