> [!NOTE]
> **Note:** This entity is only used in metadata feeds. It isn't used with pre-election, election, or officeholder feeds.

`OfficeScope` entities are used to specify which offices an `ElectionEvent` and
`OfficeholderSubFeed` entity correspond to.

## Elements

| Element | Multiplicity | Type | Description |
|---|---|---|---|
| `DebugName` | 0 or 1 | [`string`](https://developers.google.com/civics-data/reference/simple-data-types#xs-string) | Descriptive name used for the office. |
| `OfficeLevel` | 1 | [`OfficeLevel`](https://developers.google.com/civics-data/reference/office-level) | Specifies the level of the offices within this scope: `Country` for national, `Administrative Area 1` for a state or province, etc. |
| `JurisdictionOcdId` | 0 or 1 | [`string`](https://developers.google.com/civics-data/reference/simple-data-types#xs-string) | The [OCD ID](https://github.com/opencivicdata/ocd-division-ids) of the jurisdiction of the offices. > [!NOTE] > **Note:** Optional if `OfficeLevel` is `Country`, otherwise required, e.g. if the offices hold jurisdiction over a state. |
| `OfficeRoles` | 1 or more | [`OfficeRole`](https://developers.google.com/civics-data/reference/office-role) | A list of the roles contained in the dataset, specifically limited to those being elected for this office level, jurisdiction OCD ID, etc. |
| `ElectoralDistrictCollection` | 0 or 1 | N/A | Wrapper element for the list of [OCD IDs](https://github.com/opencivicdata/ocd-division-ids) of the electoral districts voting for the listed office roles. An empty list implies that the scope includes all possible districts for the specified election location or officeholder. |

## Examples

The following example is a `Feed` that contains an `ElectionEvent` with
`OfficeScope`. It indicates that the `Feed` contains (or is expected to contain)
data about a set of one or more elections to elect the national-level President,
one or more Lower House seats, and one or more Upper House seats:

### XML

```xml
<OfficeScope>
  <DebugName>Scope of US general election</DebugName>
  <OfficeLevel>Country</OfficeLevel>
  <JurisdictionOcdId>ocd-division/country:us</JurisdictionOcdId>
  <OfficeRoles>president</OfficeRoles>
  <OfficeRoles>lower house</OfficeRoles>
  <OfficeRoles>upper house</OfficeRoles>
</OfficeScope>
```

The same `ElectionEvent` can contain additional `OfficeScope` entities that
indicate several state-level elections within Virginia and Pennsylvania for
different state-level roles:

### XML

```xml
<OfficeScope>
  <DebugName>Virginia election scope</DebugName>
  <OfficeLevel>Administrative Area 1</OfficeLevel>
  <JurisdictionOcdId>ocd-division/country:us/state:va</JurisdictionOcdId>
  <OfficeRoles>attorney general</OfficeRoles>
  <OfficeRoles>state executive</OfficeRoles>
</OfficeScope>
<OfficeScope>
  <DebugName>Pennsylvania election scope</DebugName>
  <OfficeLevel>Administrative Area 1</OfficeLevel>
  <JurisdictionOcdId>ocd-division/country:us/state:pa</JurisdictionOcdId>
  <OfficeRoles>state lower house</OfficeRoles>
  <OfficeRoles>state upper house</OfficeRoles>
  <OfficeRoles>state executive</OfficeRoles>
</OfficeScope>
```

The `ElectionEvent` can, if needed, contain `OfficeScope` entities that specify
the electoral districts voting for the listed office role:

### XML

```xml
<OfficeScope>
  <DebugName>US general election scope</DebugName>
  <OfficeLevel>Country</OfficeLevel>
  <JurisdictionOcdId>ocd-division/country:us</JurisdictionOcdId>
  <OfficeRoles>upper house</OfficeRoles>
  <ElectoralDistrictCollection>
    <OcdId>ocd-division/country:us/state:ar</OcdId>
    <OcdId>ocd-division/country:us/state:ca</OcdId>
    <OcdId>ocd-division/country:us/state:ct</OcdId>
    <OcdId>ocd-division/country:us/state:de</OcdId>
    <OcdId>ocd-division/country:us/state:fl</OcdId>
  </ElectoralDistrictCollection>
</OfficeScope>
```