Stable identifiers

  • Stable identifiers are unique external identifiers used to link objects in a Common Data Format (CDF) feed with other data repositories.

  • Stable identifiers must remain consistent for an entity over time, be unique, and be used consistently across simulations and election cycles.

  • Stable identifiers should be provided in a specific <ExternalIdentifier> XML format with Type "other" and OtherType "stable".

  • Examples of good stable identifiers include UUIDs and GUIDs, which can be improved with prefixes for readability.

  • Stable identifiers are mandatory for various elements including BallotMeasureSelection, Candidate, Contest, Election, Office, Party, Person, and ReportingUnit.

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

Using Hungarian notation to further break down entities is a best practice to improve data readability, but it is not required. The content of stable IDs is not expected to conform to any standards beyond that of uniqueness and stability as described earlier.

Examples of prefixes:

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: