Revision history

  • Recent updates include guidelines for ElectoralCommission Names and example XML.

  • Documentation and Validator support have been updated for the voter-information FeedType.

  • Additional values have been added to VoterInformationWebsiteType.

  • RetentionContest has been added to the available Contest types.

Changes to the CDF documentation are listed here.

Nov 19, 2026

  • Updated MissingFieldsWarning validator rule to warn when a PartyContest is missing NumberElected or TotalSeats.
  • Updated the virtual contest sample feed to set NumberElected and TotalSeats on its PartyContest.
  • Updated the schema to require FullName in Person, PersonId in Candidate, PartyScopeGpUnitIds in Party and Coalition, and PartyIds in Coalition. Removed the MissingFieldsError and CoalitionParties validator rules, which used to report these as errors. The Schema rule now reports them as fatal.
  • Updated the schema to enforce Gender in Person as an enumeration of the documented values (lowercase, title case, and uppercase). Removed the PersonsHaveValidGender validator rule, which used to check this.
  • Removed the DuplicateID validator rule (the Schema rule already reports repeated objectId values) and the unused MissingFieldsInfo rule.
  • Removed the ElectionContainsStartAndEndDates validator rule. The Schema rule already reports an Election without a StartDate or EndDate.
  • Updated the schema to require exactly one of PartyId or PersonId in Affiliation. Removed the AffiliationHasEitherPartyOrPerson validator rule, which used to check this.

Nov 18, 2026

  • Added the RequiredContestResultsFieldsSet validator rule for election results feeds. It reports an error when a Contest is missing CurrentResultsReportingStage or ResultsReportingStageCollection.
  • Updated RequiredContestResultsFieldsSet validator rule to also report an error when a Contest is missing ResultsExpected.
  • Added the DataSourcesRequired validator rule for election results feeds. It reports an error when the ElectionReport is missing DataSourceCollection.
  • Added the ValidatePercentReporting validator rule for election results feeds. It reports an error when a Contest sets neither EstimatedExpectedVotePercentage nor both SubUnitsReported and TotalSubUnits.
  • Fixed validator rules that only checked a base element type, such as Contest, BallotSelection or Party, so they also check its subtypes, such as CandidateContest, RetentionContest, PartySelection or Coalition. Before this, these rules never ran on feeds that set xsi:type on those elements.
  • Updated PercentSum validator rule to also count the total-percent vote counts of a Contest's AggregateBallotSelection, BlankBallotSelection, NoneOfTheAboveBallotSelection, and NullBallotSelection, instead of only the ones in its BallotSelection elements.
  • Fixed more validator rules so they also check element subtypes: GpUnitsHaveInternationalizedName now checks every GpUnit, GpUnitOcdId checks every GpUnit subtype except ReportingDevice, BallotTitle checks RetentionContests, MissingStableIds and AllCaps check RetentionContests, AllCaps checks BallotMeasureContests, and MissingFieldsError checks Coalitions. VoteCountTypesCoherency now reads the contest type from xsi:type, so it actually runs.
  • Fixed ValidPartyLeadershipDates validator rule to check Leadership elements. Before this, it looked for a PartyLeadership element, which feeds never contain, so it never ran.
  • Updated the sample feeds to give every GpUnit an InternationalizedName and every RetentionContest a BallotText.
  • Added InternationalizedAbbreviation to Contest and deprecated Abbreviation in favor of it.

Nov 17, 2026

Nov 13, 2026

  • Updated the validator CLI to fetch OCD IDs for all countries when -c is omitted or empty, instead of defaulting to us.
  • Fixed DateOfBirthIsInPast validator rule to check each Person on its own and report every Person with a date of birth in the future, instead of only the first one.
  • Updated UniqueDataSourceLanguages validator rule to check each DataSource on its own and to point errors about repeated Uri languages at the repeated Uri, instead of at the whole DataSourceCollection.
  • Updated validator rule warnings, errors, and fatal messages to point at the feed elements they are about, so they include line numbers. Messages that don't belong to one element point at the closest one, such as the root ElectionReport for file encoding problems.

Nov 12, 2026

  • Fixed RulesRegistry.get_all_exceptions() in the validator library to return the recorded exceptions instead of None.
  • Updated the validator command line to exit with code 4 when it finds fatal messages, instead of 0.
  • Updated the Schema validator rule to report schema validation failures as fatal instead of errors.
  • Updated MissingPartyAbbreviationTranslation validator rule to apply to all feed types except metadata feeds, instead of only election and election dates feeds.
  • Updated MissingPartyNameTranslation validator rule to apply to all feed types except metadata feeds, instead of only election and election dates feeds.
  • Updated DateOfBirthIsInPast validator rule to apply to all feed types except metadata feeds, instead of only officeholder feeds.
  • Updated GpUnitsHaveSingleRoot validator rule to apply to all feed types except metadata feeds, instead of only election and election dates feeds.
  • Fixed ElectionDatesSpanContestDates validator rule to report every Contest with dates outside of its Election, instead of only the last one.
  • Fixed the error message of the ComposingContestIdsAreValidRelatedContests validator rule when a composing contest can't be found.
  • Fixed SubsequentContestIdIsValidRelatedContest validator rule crashing when neither a contest nor its election has an end date, and reusing a previous contest's end date for an election without one.

Nov 11, 2026

  • Updated CoalitionParties validator rule to apply to all feed types except metadata feeds, instead of only election and election dates feeds.
  • Updated DuplicatedPartyAbbreviation validator rule to apply to all feed types except metadata feeds, instead of only election and election dates feeds.
  • Updated DuplicatedPartyName validator rule to apply to all feed types except metadata feeds, instead of only election and election dates feeds.

Nov 10, 2026

  • Updated MultipleInternationalizedTextWithSameLanguageCode validator rule to apply to all feed types except metadata feeds, instead of only election and election dates feeds.

Nov 2, 2026

  • Added disqualified and sub-judice to CandidatePreElectionStatus.
  • Added defeated, did-not-participate, disqualified, projected-advanced-to-runoff, and sub-judice to CandidatePostElectionStatus.
  • Deprecated withdrawn in CandidatePostElectionStatus.
  • Updated Candidate to clarify that PreElectionStatus and PostElectionStatus are the candidate's overall final status across related contests, and that per-contest statuses belong on CandidateSelection.
  • Updated Contest to clarify the granularity of SubUnitsReported and TotalSubUnits.
  • Added InheritFromComposedContest to ResultsReportingStageCollection in Contest.
  • Added ValidateResultReportingStages validator rule to ensure that ResultsReportingStageCollection contains no ResultsReportingStage elements and that its Contest is listed in the ComposingContestIds of another Contest when InheritFromComposedContest is true, that it contains at least one ResultsReportingStage otherwise, and to warn if it doesn't contain at least two ResultsReportingStage elements (one of type no-results and at least one of type preliminary or official).
  • Added InheritFromComposedContest to ResultsReportingStageCollection in Contest.
  • Added ValidateResultReportingStages validator rule to ensure that ResultsReportingStageCollection contains no ResultsReportingStage elements when InheritFromComposedContest is true and at least one otherwise, and to warn if it doesn't contain at least two ResultsReportingStage elements (one of type no-results and at least one of type preliminary or official).
  • Updated CandidatesReferencedInRelatedContests validator rule and Candidate reference documentation to once again treat subsequent contests as related contests, so a Person must be referenced by the same Candidate across subsequent contests.

Oct 28, 2026

  • Updated Contest to remove composing contest inheritance from EarliestPollsClose, LatestPollsClose, ResultsEmbargoEnd, and ResultsExpected.

Oct 23, 2026

  • Updated GpUnitOcdId validator rule to check ReportingUnit elements.

Oct 22, 2026

  • Added OutcomeDetermined to Contest.

Oct 21, 2026

  • Updated Contest to clarify that ResultsReportingStageCollection should contain the full set of expected stages with their attribution rather than only the current stage, which goes in CurrentResultsReportingStage.

Oct 16, 2026

Oct 15, 2026

Oct 13, 2026

  • Added PreElectionStatus and PostElectionStatus to CandidateSelection.
  • Added diplomat to OfficeRole.
  • Added DiplomatSendingStateId and DiplomatReceivingStateId to Office.
  • Updated ValidIDREF validator rule to recognize DiplomatSendingStateId and DiplomatReceivingStateId as referencing GpUnit elements
  • Added DiplomaticOfficesHaveCorrespondingGpUnitsSet validator rule to ensure offices with role diplomat have at least one of those fields set.

Oct 12, 2026

  • Added EstimatedExpectedVotePercentage to Contest.

Oct 8, 2026

Oct 6, 2026

  • Added ResultsLastUpdated to Contest.

Sep 24, 2026

  • Added CandidateImageInContactInformation validator rule to warn when candidate-image is set in ContactInformation.Uri and recommend using Person.ImageUri instead.

Sep 14, 2026

Sep 2, 2026

  • Added SqsQueueNameIsFullyQualifiedArn validator rule to ensure that if SqsQueueName is set in a metadata feed, it is a valid fully qualified SQS ARN.

Aug 28, 2026

  • Added TotalSeats to Contest.
  • Updated VoteCountValidSeatsDeltaTypes rule to error on legacy seats-delta in SpecialBallotSelection elements and also to support seats-delta-institutional without needing to set seats-delta-mandate.

Aug 27, 2026

  • Deprecated legacy JSON feed formats and removed all JSON schema examples across developer guides and reference documentation in favor of CDF XML.

Aug 26, 2026

  • Updated examples of stable IDs and object IDs across reference documentation to use Hungarian notation with hyphens.
  • Updated the Stable identifiers guide to list prefix recommendations across entity types.

Aug 25, 2026

  • Removed HungarianStyleNotation rule.
  • Updated the Stable identifiers guide to clarify that Hungarian notation is a best practice but not required, and added prefix examples.

Aug 24, 2026

  • Updated the International considerations guide to clarify requirements for English translations of candidate and party names from official sources, reputable press, or partner publications.

Aug 22, 2026

Aug 5, 2026

  • Updated schema for CountedInTotal to allow for minOccurs=0 in accordance with the documentation.

Jul 29, 2026

  • Updated FeedInactiveDateIsLatestDate to skip checking test feeds.
  • Added new DuplicateBallotTitleSeatPair rule to check for duplicate (BallotTitle, Seat) pairs in Contests.
  • Added new FeedInactiveDateNotOlderThanOneYear rule.

Jul 17, 2026

  • Check that all Uri elements have a valid language code (when specified).

Jul 9, 2026

  • Removed deprecated GovernmentBodyExternalId rule.

Jun 16, 2026

  • Updated legacy government body schema to an error.

Jun 16, 2026

  • Added the Named Entity Changes guide.

Jun 2, 2026

  • Added tse-candidate-number as an external identifier to Candidate.

May 19, 2026

  • Added ResultsReportingStagesMustHaveUniqueType validator rule to ensure that each ResultsReportingStage in a ResultsReportingStageCollection has a unique StageType.

May 18, 2026

  • Added SqsQueueNameRequiresS3SourceDirPath validator rule to ensure that if SqsQueueName is set in a metadata feed, SourceDirPath must also be set and must be an s3 path.

May 7, 2026

  • Added AttributionDepthLimit rule to ensure <Attribution> trees under <ResultsReportingStage> have at most 3 levels of recursion/depth.
  • Added AttributionCyclesValidation rule to ensure <Attribution> elements don't contain directed cycles (loops) between nodes.

May 6, 2026

  • Added ValidateIncludeInAggregationBallotSelections rule to check that the sum of vote counts for selections marked as IncludedInAggregation does not exceed the AggregateBallotSelection vote count.
  • Added rule to enforce CountedInTotal constraints on SpecialBallotSelections.
  • Added ValidateResultsEmbargoEnd rule to check that ResultsEmbargoEnd is not after the start of the official ResultsReportingStage.
  • Added ValidateResultsExpected rule to check that ResultsExpected is not before the first ResultsReportingStage (excluding the no-results stage).
  • Added NotEmptyUniqueDataSourceUris, UniqueDataSourceLanguages, and UniqueDataSourceDisplayNames rules to verify DataSourceCollection elements. Also, added DisplayName to the MultipleInternationalizedTextWithSameLanguageCode.

May 5, 2026

  • Added ValidatePollsCloseDatetimes rule to check that LatestPollsClose is not before EarliestPollsClose.
  • Deleted PartiesHaveValidColors rule. These values are also validated by the schema for HtmlColorString.
  • Updated ValidateDuplicateColors rule to support DarkThemeColor and LightThemeColor.

April 30, 2026

  • Added WinnerCountLimit validator rule to check that the number of winners or projected winners in a contest does not exceed the number of elected seats.
  • Removed support for candidate-image annotation in ContactInformation.
  • Add rules to restrict ImageUri with annotation candidate-image to at most one per Person and also to ensure candidate image URIs are unique across persons.

April 29, 2026

  • Added EmptyString and EmptyText rules to METADATA_RULES.

April 16, 2026

  • Added more examples to metadata_sample_feed.xml.
  • Fixed multiple sample feed files to ensure they pass validation.

April 14, 2026

  • Updated yearly feed longevity to only be allowed for pre-election feeds. Feeds of type election-results must always be limited.

March 25, 2026

  • Updating Metadata sample feed SourceDirPath value to match regular expression expectation.

March 19, 2026

  • Added IsTest and SqsQueueName to Feed.

March 18, 2026

  • Added SpecialBallotSelection subtype of BallotSelection.
  • Added AggregateBallotSelection, BlankBallotSelection, NoneOfTheAboveBallotSelection, and NullBallotSelection to Contest.
  • Added IncludedInAggregation to CandidateSelection and PartySelection.
  • Added Attribution and DataSource element definitions and DataSourceCollection to ElectionReport.
  • Added ResultsReportingStage and ResultsReportingStageType definitions and ResultsReportingStageCollection and CurrentResultsReportingStage to Contest.
  • Added PartyColors definition and Colors to Party.

March 17, 2026

  • Added IsNotable to Candidate, Contest, and Party.
  • Added PartyLabel to Candidate.
  • Added ImageUri to Person.
  • Added ResultsExpected, ResultsEmbargoEnd, EarliestPollsClose, and LatestPollsClose to Contest.

March 11, 2026

  • Removed special handling of IssuerAbbreviation from EmptyString rule.

February 26, 2026

  • Restricted VoteCountsCollection to one per BallotSelection. (This still allows for multiple VoteCounts within that collection.)

February 24, 2026

  • Fixed references to OfficeholderSubFeed that were were incorrectly written as OfficeHolderSubFeed.
  • Restricted SourceDirPath in the metadata feed to supported filepath types.

February 23, 2026

  • Updated VoteCounts enumerations to support both seats-delta-mandate and seats-delta-institutional.

February 18, 2026

  • Made ElectionEventCollection and OfficeholderSubFeed mutually exclusive in the Feed element in metadata feeds.

February 12, 2026

  • Added guidance to Simple data types for PartialDate being interpreted as the latest possible date in the range.

February 11, 2026

  • Added OfficeHolderTenure to MissingStableIds CDF Validator rule to ensure all officeholder tenures have stable IDs.

January 28, 2026

  • Added FeedElementsShouldHaveSubElementsBasedOnType CDF Validator rule to ensure Feed entries in the Metadata Feed have appropriate sub-elements.

January 15, 2026

  • Delete ElectoralDistrictOcdId rule now that it is fully replaced by the broader GpUnitOcdId rule.

  • Added mayor as an Executive Office Role in the CDF Validator.

January 13, 2026

  • Added EmptyString validator rule to check that string fields are not empty or only contain whitespace (temporarily a warning for IssuerAbbreviation).

December 10, 2025

  • Updated the CDF XSD to make IssuerAbbreviation optional.

November 18, 2025

  • Updated GpUnitOcdId rule to check all GpUnits expected to have OCD IDs have valid OCD IDs, and replaced ElectoralDistrictOcdId rule with a placeholder until safe to remove.

November 12, 2025

  • Added guidance to Simple data types highlighting the need to use the Gregorian calendar for dates.

October 22, 2025

September 29, 2025

  • Updated guidelines for ElectoralCommission Names including example XML.

August 5, 2025

  • Update Feed documentation and Validator support for FeedType of voter-information.

July 23, 2025

  • Add additional values to VoterInformationWebsiteType.

July 11, 2025

  • Added RetentionContest to the available Contest types.

July 7, 2025

  • Updated Metadata Feed documentation and validator to clarify canceled election events don't need to be considered when determining a Feed inactive date.

June 25, 2025

  • Added whatsapp as a platform for AnnotatedUri.

June 16, 2025

  • Updated Voter Information documentation for VoterInformationWebsite and ElectoralCommissionWebsite to reflect definitions in the CDF schema.

May 29, 2025

  • Replaced NoSourceDirPathBeforeInitialDeliveryDate validator rule with SourceDirPathMustBeSetAfterInitialDeliveryDate.

May 27, 2025

  • Added Validator support and basic checks for Voter information feeds.

May 22, 2025

  • Published a guide to aid in determining officeholder term dates.

May 13, 2025

May 7, 2025

May 6, 2025

  • Update PersonHasOffice rule to check new OfficeHolderTenure schema.

April 18, 2025

  • Added clarification that FullName elements of People shouldn't contain the person's title.

April 10, 2025

  • Added new schema for office / officeholder tenure split.

March 12, 2025

  • Added judge, cabinet member, general purpose officer, and special purpose officer to office roles and added logic in validator to allow two combinations of roles: head of government & head of state and cabinet member & general purpose officer.

March 4, 2025

  • Updated ElectionDateType with details on how StartDate and EndDate will be interpreted for bounded elections.

February 26, 2025

  • Updated Metadata feed to add note about waiting 60 days after FeedInactiveDate to remove a feed from metadata feed.

January 29, 2025

January 27, 2025

  • Updated Contest guidelines to add PassageThreshold definition to BallotMeasureContest

January 15, 2025

  • Updated guidelines for the FeedInactiveDate property of the metadata Feed entity.

November 19, 2024

November 11, 2024

November 1, 2024

  • Update EmptyText validator rule to raise an error instead of a warning.

August 26, 2024

  • Update the OfficeLevel enum to add detailed descriptions.

July 17, 2024

July 10, 2024

  • Adding recommendations for the 'FeedInactiveDate' and SourceDirPath

June 24, 2024

  • Update PartyId to allow for multiple PartyIds for Candidate and Person entities.

June 21, 2024

May 14, 2024

  • Clean the PartyContest entity to only include the relevant elements PartyContest.
  • Added updated definitions for ElectionDateStatus enum values, particularly, tentative and changing.

May 1, 2024

  • Clarified the definition for the IsIndependent element for Party.

April 29, 2024

  • Update FeedType enum and FeedLongevity enum to use lower case values in their respective reference pages.

April 17, 2024

  • Added an IsIndependent element to the reference page for Party.

February 12, 2024

  • Added documentation throughout the site for the new Metadata feed.

January 9, 2024

January 3, 2024

July 24, 2023

  • Added Committee type for Political Committees and a corresponding feed type

January 20, 2023

  • Added a Slogan element to the reference page for Party.
  • Added a CampaignSlogan element to the reference page for Candidate.

November 17, 2022

December 30, 2021

  • Added a PartialDate section to the Simple Data Types page, as well as updating some of the table fields.

December 27, 2021

  • Modified content within the CandidateContest section of the Contest page to support only one office per contest, as well as updating some of the XML examples.

October 15, 2021

  • Added ExternalIdentifier section to the reference page for Candidate.

August 20, 2021

February 26, 2021

  • Added an example to the Term reference page on how to represent the tenure of reelected officeholders in an Officeholder feed.

February 24, 2021

  • Added information about party-chair-id to the Party reference material.

February 18, 2021

  • Added a diagram to the CandidatePreElectionStatus reference material that illustrates the timing of statuses.

December 14, 2020

  • Added Guides pages that describe the available feed types. Updated the Reference pages to provide best practices to follow for most entities.