Stable identifiers

Stable identifiers are an externally stable, unique identifier for a given object. They allow data consumers to reconcile objects in a Common Data Format (CDF) feed with other data repositories. In database parlance, external identifiers are a form of foreign key that lets data consumers link objects in a CDF feed to other databases.

As an example, if "Robert Brady" is a candidate, a data consumer might not immediately link that person to "Bob Brady" in their image database. However, the CDF data and the image database could indicate that this person is legislator 01469 as identified by the Library of Congress THOMAS database. Then the data consumer can link the image with the candidate.

The following conditions must hold for all stable identifiers:

  • Stability: The stable identifier for a given unique entity, such as a Person or Party, mustn't change across different versions of the data feed. In other words, the stable ID mustn't change over time for a specific entity.
  • Uniqueness: Never reuse a stable identifier for a different entity, even if the original entity is no longer in the feed.
  • Consistency: You must use the same set of stable identifiers for candidates, parties, or districts for both simulations, if needed, and during the election cycle.

Data formatting

Provide the stable identifiers in the following format:

<ExternalIdentifier>
  <Type>other</Type>
  <OtherType>stable</OtherType>
  <Value>match the regex ^[a-zA-Z0-9_-]+$</Value>
</ExternalIdentifier>

Some good examples of Stable IDs are Universal Unique identifiers (UUIDs) and Global Unique identifiers (GUIDs). These would look like:

e55b7dd4-cc98-11ec-9d64-0242ac120002

To improve the data readability, it's better to add additional prefixes and suffixes to further break down entities. For example, add the per- prefix to persons or off- for offices as stable IDs are not expected to conform to any standard.

Recommended: per-e55b7dd4-cc98-11ec-9d64-0242ac120002

Recommended: off-7849514a-e8bc-11ec-8fea-0242ac120002

Recommended: per-123456789012345

Not recommended: per-john-doe

  • Risk: Another person with the same name may have the same ID.
  • Risk: Change in the data might affect the stable ID.

Not recommended: off-presidento-of-us

Where to use stable IDs

Stable identifiers are mandatory for the following elements: