# Title Syntax Election and Contest titles should conform to this syntax specification. This helps ensure that titles are neither too long nor too indistinct that they cause duplicates or incorrect merges. Titles should largely reflect how they are referred to in the jurisdiction in which the election or contest is occurring. They should be as detailed as necessary but as brief as possible. > [!NOTE] > **Note:** The terms 'title' and 'name' are used interchangeably for elections and their contests. Both terms correspond broadly to the wording used on the ballot to identify the election or contest. ## General guidelines - Use the election type and office name specific to the country - Example: if a country's lower house is called the 'Legislative Assembly', that term should be used and not a generic term like 'House' - Use sentence case for titles - Example: the word, 'election' shouldn't be capitalized - Proper nouns and the names of government bodies should be capitalized - The year should be at the beginning of the title - Avoid placing the year at the end separated by a comma - Bad example: Elections to the General Council of Andorra, 2027 - Instead, use '2027 Andorra General Council election' - The ordinal election count should replace the year in cases where the local convention is to count elections ordinally instead of giving the year - Example: '45th Canada federal election' - The year should be updated to reflect the new election year if the year of an election has changed due to postponement - Use cardinal numbers for round numbers and district numbers - Example: 'Round 1' versus '1st Round' - Don't use adjective forms of offices or places, like 'Costa Rican' - The exception to this rule is when the adjective form colloquially denotes the election type in that jurisdiction - Example: Use 'presidential' or 'parliamentary' election where 'president election' wouldn't make sense - This syntax applies to titles in English. - Translations of titles into other languages should follow this syntax to the extent that they comply with the grammar and syntax rules of the target language - Translations should be syntactically complete (i.e. nothing should be missing) but they should also sound natural to speakers of the target language - Translations should match what a speaker of the language would expect to see in a high quality search experience on the frontend ### When to group special elections Don't group special elections with different electoral districts. Usually those districts are part of the title of the election and this can lead to long names. The exception to this rule is where there are special elections in a large number of towns which requires a single event and contest be created for that jurisdiction or region as a whole. This can happen because there are a large number of special elections on the same day or, more naturally in many cases, like in the US- Virginia Special Elections, 2023. This was an election event with special elections throughout the state of Virginia which justified the grouping of the contests. Generally, the decision whether to group or not should ideally align with whether the region/country/state is treating them as a cohesive event during the same day or specific time period. ### How to avoid confusion between similar election or contest events If there is more than one special election in the same year for the same office, the full date of the election (as opposed to just the year) should be included in the title. The full date should also use cardinal numbers (March 16 not March 16th). With the year in the beginning, this would look like '2023 March 16 Pakistan National Assembly bye-elections'. When the same electoral district name appears in multiple jurisdictions, it is essential to specify both the jurisdiction and electoral district to avoid confusion. This combination provides the necessary context for uniquely identifying the intended electoral district. This can happen, for example, in India where many districts share their names with districts in other Indian states or neighbouring countries in South Asia. 'Aurangabad district, Bihar' shares a name with 'Aurangabad district, Maharashtra' so an election taking place there should specify the state. Example: '2024 India Lok Sabha Maharashtra constituency Aurangabad general election' It is expected that reasonable steps be taken to identify election events taking place in close regional or temporal proximity to one another and supply sufficient detail to help distinguish them. However, a common sense approach should be applied when supplying this extra detail. As an example, it's unlikely that a reasonable person would confuse elections taking place simultaneously in Dublin, California (US) and Dublin, Ireland given the wider context. *** ** * ** *** ## Election title syntax #### Show syntax flowchart ![Syntax diagram for election titles](https://developers.google.com/static/civics-data/images/election-title-syntax.png) The following components *in this order* should make up the election event name: 1. Year - Or month + year if more than one election is taking place in this jurisdiction this year 2. Jurisdiction - This can be replaced by Electoral district in the case of special elections - Or a combination of Jurisdiction and Electoral district in case of special elections where there are Electoral districts with the same name 3. Type of election - Examples: general, primary, special - In some countries, there may not be a type that is strongly associated with election names. Instead, there might be a stronger association with the body being elected or the event might be more fine-grained - In these cases use, office or body being elected, like presidential or legislative - For special elections, use the term used in that country or for that event, like 'special election' or 'by-election' - The election type element in the title does not necessarily have to consist of a valid [`ElectionType`](https://developers.google.com/civics-data/reference/election-type) value, although it may coincidentally do so - Multiple election types are permitted where required, such as in the case of special primary elections 4. 'election' or 'elections' - If the election type already includes the word 'election' or 'elections' then this element can be skipped. ### Omission of rounds and parties in election titles Round or party for primary elections are not included here since events are usually higher level. Typically, we would have one event for multiple rounds or multi-party primaries. It is good practice to borrow additional guidelines from the contest naming syntax if finer-grained election entities are being created. ### Example election titles - '2022 United States general election' - '2023 Fadden by-election' - '2024 Australian Capital Territory general election' - '2025 Costa Rica general election' - '2026 Taipei local election' - '2027 Andorra general election' *** ** * ** *** ## Contest title syntax #### Show syntax flowchart ![Syntax diagram for contest titles](https://developers.google.com/static/civics-data/images/contest-title-syntax.png) The following components *in this order* should make up the election contest name: 1. Year - Or month + year if more than one election is taking place in this jurisdiction this year 2. Jurisdiction - This can be replaced by electoral district or a combination of jurisdiction and electoral district in the case of special elections 3. Office / body being elected - This can additionally include electoral district if required for specificity - Example: '2022 US House Texas District 8 general election' - This can include the phrase 'party list' if the contest is for a party list of a body rather than the body itself 4. Political party, if primary election type 5. Type of election, when available - Example: 'January 2023 Hyderabad bye-election for Vidhan Sabha of Telangana' - The election type element in the title does not necessarily have to consist of a valid [`ElectionType`](https://developers.google.com/civics-data/reference/election-type) value, although it may coincidentally do so - This can sometimes be omitted in case of a runoff election, see item 7 for multi-round election guidance - Multiple election types are permitted where required, such as in the case of special primary elections 6. 'election' or 'elections' - If the election type already includes the word 'election' or 'elections' then this element can be skipped 7. Cardinal round or 'runoff'- if multi-round - Some countries use 'runoff' to refer to the second round of an election, and this can replace the cardinal round if that's the local convention - If using 'runoff', it can also replace the election type if that's the local convention ### Example contest titles - '2017 France National Assembly election Round 1' - '2017 France Presidential election Round 1' - '2020 US House Texas District 8 general election' - '2020 US Presidential Democratic Party primary election' - '2023 Fadden House of Representatives by-election' - '2025 Philippines House of Representatives party list general election' - '2027 Andorra General Council election'