Elections and results profile

How elections, candidates, and results are described so outcomes can be reported consistently.

Schemas: 4

Code lists: 5

Standards: schema.org, NIST SP 1500-100, VIP

Candidacy candidacy link

One person standing in one contest, and how they fared. A candidacy rather than a candidate: the same person may stand in several contests, and their party affiliation and result belong to the standing, not to them.

FieldTypeDefinitionRequired
@id string This candidacy's own dereferenceable identifier. No
@type "Candidacy" Yes
candidate Reference The Person standing. A reference, so a candidate who later takes office is the same entity as the officeholder in the org profile. Yes
party Reference The PoliticalParty they stood for, where they stood for one. schema:PoliticalParty is a real type. Absent means independent. No
ballotName string The name as printed on the ballot, which is often not the person's full legal name. No
ballotOrder integer No
voteCount integer No
candidacyResult string termCode from the CandidacyResult code list. No
incumbent boolean Whether they held the post going into the contest. No
identifier Identifier[] Any scheme-qualified identifiers for this candidacy beyond its @id. No 
{
  "@type": "Candidacy",
  "@id": "https://example-city.gov/id/candidacy/2022-mayor-smith",
  "candidate": {
    "@id": "https://example-city.gov/id/person/jane-smith",
    "name": "Jane Smith"
  },
  "party": {
    "@id": "https://example-city.gov/id/party/civic-alliance",
    "name": "Civic Alliance"
  },
  "ballotName": "Jane Smith",
  "ballotOrder": 1,
  "voteCount": 13402,
  "candidacyResult": "elected",
  "incumbent": false
}
Download JSON

Contest contest link

One race or question on the ballot: an office to fill, or a measure to decide. The unit at which results are actually reported. electoralSystem is required because a result cannot be interpreted without it - 40% of the vote wins outright under first-past-the-post, triggers a runoff under a two-round system, and means something different again under a party list. A profile that assumed one system would not travel outside the country it was written in.

FieldTypeDefinitionRequired
@id string This contest's own dereferenceable identifier. Yes
@type "Contest" Yes
name string The contest's title as it appears on the ballot, e.g. 'Mayor' or 'Measure A'. Yes
description string A plain-language summary of what's being decided, when the name alone isn't enough. No
identifier Identifier[] Any scheme-qualified identifiers for this contest beyond its @id. No
election Reference The Election this contest is part of. Yes
contestType string termCode from the ContestType code list. Yes
electoralSystem string How votes translate into outcomes. termCode from the ElectoralSystem code list. Yes
post Reference The Post being filled, from the org profile. This is the join that closes the loop: an election fills an office, and the winner's Role in that office begins. No
representsJurisdiction Reference The district or ward the contest covers, where it is not the whole area. No
seatsToFill integer More than one under block vote, party list and STV. No
candidacy Candidacy[] The candidacies standing in this contest, where it fills an office rather than deciding a measure. No
ballotOption object[] For a ballot measure: the options put to voters. Kept separate from candidacy because a proposition is not a person. No
validVotes integer Ballots counted toward the result. With invalidVotes, sums to totalVotes. No
invalidVotes integer Spoiled and blank ballots. Reported separately because they are a real signal, and folding them into the total makes every share slightly wrong. No
totalVotes integer All ballots cast in this contest, valid and invalid. No
sourceDataset string The Dataset this record was published as part of. No
registeredVoters integer The electorate for this contest. Held at contest level as well as election level because the register is drawn per constituency, and turnout is only meaningful against the electorate that could actually vote in that race. No 
{
  "@id": "https://example-city.gov/id/contest/2022-mayor",
  "@type": "Contest",
  "name": "Mayor",
  "election": {
    "@id": "https://example-city.gov/id/election/2022-general",
    "name": "Example City general election, 2022"
  },
  "contestType": "office",
  "electoralSystem": "fptp",
  "seatsToFill": 1,
  "post": {
    "@id": "https://example-city.gov/id/post/mayor",
    "name": "Mayor"
  },
  "validVotes": 23880,
  "invalidVotes": 430,
  "totalVotes": 24310,
  "candidacy": [
    {
      "@type": "Candidacy",
      "@id": "https://example-city.gov/id/candidacy/2022-mayor-smith",
      "candidate": {
        "@id": "https://example-city.gov/id/person/jane-smith",
        "name": "Jane Smith"
      },
      "party": {
        "@id": "https://example-city.gov/id/party/civic-alliance",
        "name": "Civic Alliance"
      },
      "ballotName": "Jane Smith",
      "ballotOrder": 1,
      "voteCount": 13402,
      "candidacyResult": "elected",
      "incumbent": false
    },
    {
      "@type": "Candidacy",
      "@id": "https://example-city.gov/id/candidacy/2022-mayor-reyes",
      "candidate": {
        "@id": "https://example-city.gov/id/person/alan-reyes",
        "name": "Alan Reyes"
      },
      "party": {
        "@id": "https://example-city.gov/id/party/riverside-independents",
        "name": "Riverside Independents"
      },
      "ballotName": "Alan Reyes",
      "ballotOrder": 2,
      "voteCount": 10478,
      "candidacyResult": "notElected",
      "incumbent": true
    }
  ]
}
Download JSON

Election election link

An electoral event on a given date, containing one or more contests. schema.org has no Election, Candidate, Ballot or constituency of any kind - only PoliticalParty, which is used - so this profile is minted over NIST SP 1500-100 and VIP. Closes a loop left open by the org profile: org records that a Post is filled by election and how long a term runs, but nothing about the election that produced the officeholder.

Standards: NIST SP 1500-100

FieldTypeDefinitionRequired
@id string This election's own dereferenceable identifier. Yes
@type "Election" Yes
name string The election's title, e.g. 'Example City general election, 2022'. Yes
description string A plain-language summary of the election, when the name alone isn't enough. No
url string Where this election's canonical human-readable page lives. No
identifier Identifier[] Any scheme-qualified identifiers for this election beyond its @id. No
electionDate string Polling day. Where voting spans several days, the final day. Yes
electionType string termCode from the ElectionType code list. Yes
electionStatus string termCode from the ElectionStatus code list. No
administeredBy Reference The GovernmentOrganization running the election, which is frequently not the body being elected. No
jurisdiction Reference The Jurisdiction this election is held in. Yes
contest Reference[] The Contests decided at this election. No
registeredVoters integer The electorate for the election as a whole. See Contest.registeredVoters for the per-contest figure, which is what turnout should actually be measured against. No
ballotsCast integer Ballots cast across the election. With registeredVoters this yields turnout; publishing turnout as a derived percentage instead loses the ability to recompute it on a corrected register. No
sourceDataset string The Dataset this record was published as part of. No 
{
  "@id": "https://example-city.gov/id/election/2022-general",
  "@type": "Election",
  "name": "Example City general election, 2022",
  "electionDate": "2022-11-08",
  "electionType": "general",
  "electionStatus": "completed",
  "administeredBy": {
    "@id": "https://example-city.gov/id/organization/city-government",
    "name": "Example City Government"
  },
  "jurisdiction": {
    "@id": "https://example-city.gov/id/jurisdiction/example-city",
    "name": "Example City"
  },
  "registeredVoters": 41200,
  "ballotsCast": 24310,
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "gs:local",
      "value": "2022-general"
    }
  ],
  "contest": [
    {
      "@id": "https://example-city.gov/id/contest/2022-mayor"
    },
    {
      "@id": "https://example-city.gov/id/contest/2022-council-d2"
    },
    {
      "@id": "https://example-city.gov/id/contest/2022-measure-a"
    }
  ]
}
Download JSON

PoliticalParty political party link

A political party. schema:PoliticalParty is a real type and is used unchanged. Kept out of _core because a party is not a government body: it has no jurisdiction it governs and no place in the organizational hierarchy, so the _core Organization requirements do not apply to it.

FieldTypeDefinitionRequired
@id string This party's own dereferenceable identifier. Yes
@type "PoliticalParty" Yes
name string The party's official name. Yes
alternateName string[] Other names or abbreviations this party is known by. No
description string A plain-language description of the party. No
url string The party's official page, when one exists. No
identifier Identifier[] Any scheme-qualified identifiers for this party beyond its @id. No
areaServed Reference The Jurisdiction this party contests elections in, where it's specific to one. No
foundingDate string When this party was founded. No
dissolutionDate string Present means the party no longer exists. No 
{
  "@id": "https://example-city.gov/id/party/civic-alliance",
  "@type": "PoliticalParty",
  "name": "Civic Alliance",
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "gs:local",
      "value": "civic-alliance"
    }
  ]
}
Download JSON