Stay organized with collections
Save and categorize content based on your preferences.
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:
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-08-21 UTC."],[[["\u003cp\u003eStable identifiers are unique, unchanging IDs used to consistently track entities like candidates and elections across different datasets and over time.\u003c/p\u003e\n"],["\u003cp\u003eThese identifiers help link related data from various sources, even if naming conventions differ, ensuring data accuracy and integration.\u003c/p\u003e\n"],["\u003cp\u003eStable IDs should follow a specific format, including a type, other type, and a unique alphanumeric value, ideally with prefixes for better readability.\u003c/p\u003e\n"],["\u003cp\u003eAvoid generating stable IDs from the data itself, as this can lead to inconsistencies and errors; instead, use robust, unchanging identifiers like UUIDs or GUIDs.\u003c/p\u003e\n"],["\u003cp\u003eStable identifiers are mandatory for key elements in election data, including candidates, contests, parties, and reporting units, ensuring data integrity and linkage.\u003c/p\u003e\n"]]],[],null,["# Stable identifiers are an externally stable, unique identifier for a given\nobject. They allow data consumers to reconcile objects in a Common Data Format\n(CDF) feed with other data repositories. In database parlance, external\nidentifiers are a form of foreign key that lets data consumers link\nobjects in a CDF feed to other databases.\n\nAs an example, if \"Robert Brady\" is a candidate, a data consumer might not\nimmediately link that person to \"Bob Brady\" in their image database. However,\nthe CDF data and the image database could indicate that this person is\nlegislator 01469 as identified by the Library of Congress THOMAS database. Then\nthe data consumer can link the image with the candidate.\n\nThe following conditions must hold for all stable identifiers:\n\n- **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.\n- **Uniqueness:** Never reuse a stable identifier for a different entity, even if the original entity is no longer in the feed.\n- **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.\n\nData formatting\n---------------\n\nProvide the stable identifiers in the following format: \n\n \u003cExternalIdentifier\u003e\n \u003cType\u003eother\u003c/Type\u003e\n \u003cOtherType\u003estable\u003c/OtherType\u003e\n \u003cValue\u003ematch the regex ^[a-zA-Z0-9_-]+$\u003c/Value\u003e\n \u003c/ExternalIdentifier\u003e\n\nSome good examples of Stable IDs are Universal Unique identifiers (UUIDs) and\nGlobal Unique identifiers (GUIDs). These would look like:\n\n`e55b7dd4-cc98-11ec-9d64-0242ac120002`\n\nTo improve the data readability, it's better to add additional prefixes and\nsuffixes to further break down entities. For example, add the `per-` prefix to\npersons or `off-` for offices as stable IDs are not expected to conform to any\nstandard.\n| **Important:** Avoid generating a stable ID from the data being provided. This can cause stable ID shifts which lead the data to be corrupted or become inaccurate and misused.\n\nRecommended: per-e55b7dd4-cc98-11ec-9d64-0242ac120002\n\nRecommended: off-7849514a-e8bc-11ec-8fea-0242ac120002\n\nRecommended: per-123456789012345\n\nNot recommended: per-john-doe\n\n- Risk: Another person with the same name may have the same ID.\n- Risk: Change in the data might affect the stable ID.\n\nNot recommended: off-presidento-of-us\n\nWhere to use stable IDs\n-----------------------\n\nStable identifiers are mandatory for the following elements:\n\n- [`BallotMeasureSelection`](/civics-data/reference/ballot-selection?feed=pre-election#ballot-measure-selection) of a **`BallotSelection`**\n- [`Candidate`](/civics-data/reference/candidate)\n- `Coalition` of a [`Party`](/civics-data/reference/party)\n- [`Contest`](/civics-data/reference/contest)\n- [`Election`](/civics-data/reference/election)\n- [`Office`](/civics-data/reference/office)\n- [`Party`](/civics-data/reference/party)\n- [`Person`](/civics-data/reference/person)\n- [`ReportingUnit`](/civics-data/reference/gp-unit#reporting-unit)"]]