Proposal process

From OpenStreetMap Wiki
Jump to navigation Jump to search
For lists of proposed features by status, see Category:Proposals by status.
For proposed icons for existing features, see Proposed Icons.

This page describes the proposal process, which is one of multiple ways to introduce and discuss new tags for features and properties. The other ways are often undocumented. The proposal process was designed as a mechanism to document that a rough consensus exists within the community on how to model and tag a feature that previously had no established tagging. The open voting process acts as supporting evidence that the proposal author has adequately reflected feedback from interested parties and meaningfully addressed objections posed. The outcome of a proposal vote is a change in documentation on the wiki.

The proposal process usually involves other mappers reviewing what has been proposed - so some issues may be caught before a tagging scheme is widely used.

As a documentation change, an approved proposal is not binding on any mapper, software developer, or data consumer. However, tagging backed by an approved proposal is usually regarded as having survived a level of community vetting and scrutiny, and thus carries more weight when compared to alternative methods of mapping a feature. OpenStreetMap does not restrict mapping to tagging schemes backed by an approved proposal -- you can still use any tags you like. Nonetheless, there is benefit to mappers and data consumers alike in agreeing on a common data model and corresponding tags by reducing conflict between mappers, edit wars, and tagging disputes.

As a non-binding documentation change, the outcome of a proposal vote does not compel a change in tools which use and generate OSM data, such as the standard tile layer renderings or editor presets. An approved proposal will not be automatically rendered or added to presets; this is at the discretion of the developers and maintainers of those tools. Also, a vote result is never permission for large-scale re-tagging of existing objects. See automated Edits code of conduct for more about this topic.

This page is designed to assist anyone considering putting forward a tag proposal, with the aim of speeding the tag proposing process. Like the proposal process itself, it attempts to describe the rough consensus that has accumulated over the years over the best ways to assess and document community consensus on mapping and tagging. It is not a set of absolute rules, but rather a helpful guide for community members.

Proposal list

All proposals are categorised by the status set in its Proposal page template:

If you are unfamiliar with proposal process - it may be a good idea to look through them, especially some currently active one or recent ones. For example - what is the reason for people opposing proposals?

Before creating a proposal

Does it already exist?

  1. Search for possible documentation on this Wiki.
    For example:
    • You want a tag for a racecourse; consider searching for "racing", "horse", etc.
    • You want a tag for a peninsula; consider searching for "headland", "point", etc.
    • You want a tag for a brewery; consider searching for "beer", "manufacturing", "alcohol", "industrial", "plant", "works", etc.


      If you come across an Abandoned proposal and are interested in reviving it, see Reviving old proposals.
      If you come across a previously Rejected proposal, being a rejected feature does not necessarily mean it should not be proposed again. Some proposals fail due to a poor definition, being ambiguous or lacking information to justify their significance, or becoming more significant over time and thus more map-worthy.
  2. Check Mapping issues to see a list of known issues relating to mapping and tagging standards.
  3. Search for the tag on Taginfo to see if there is any usage otherwise.
  4. Ask community members in one of the Contact channels if it exists.
  5. It might also be a good idea to send an email to the tagging mailing list, describe the feature you want to tag and see if there are tags in use but hard to find or not yet documented.

Significance

Is the tag you are considering for proposal, worthy of a new tag? Consider possible uses for the map, and specifically the data you want to add.

This is a difficult judgement to make: if you want to tag it, then that is generally reason enough to create a tag.

  • Is it a destination in itself?
    • People may search for some locations, for example: a national park, a bus station, a street address or a rubbish dump, because they want to visit that location.
  • How many of the item do you think there will be in the world?
    • For instance, you want to map an aero-engine factory - there are very few aero-engine factories in the world, so rather than creating a specific tag, this may be better served by using an existing man_made tag and specifying product=aero_engines.
  • How large is the item?
    • Large items can assist with navigation.
  • Is it useful for research/study?
    • A geography student may want to determine the total area of national parks in a given region.
    • A sociology student may want to map correlation between number/location of Porsche dealerships and houses greater than 600 m2 in area.
    • A history student may want to show the locations of all battles in a given war.
  • Does it assist in route-planning?
    • It is useful to know which junctions are traffic lights and which are roundabouts as this can affect journey times.
    • Truck drivers need to know the maximum height allowed under bridges, or the maximum weight allowed through population centres.
    • Traffic calming structures can affect journey times, routing software will generally not use roads with these on.
    • Walkers would want to know surfaces/conditions of walking tracks.

Compatibility with established practices

OpenStreetMap has some established good practices. Your proposal should follow those or at least explain why it does not do it. Please have a look at them.

Specifically relevant for proposals might be

Verifiability
Tags that are approved are usually features or properties that an individual mapper can confirm to be correct or false. A tag is verifiable if independent users would make the same observation.
This means that statistical properties (like peak vehicles per hour on a road) and subjective content (reviews, rankings) are not included in OpenStreetMap. Temporary, historic or speculative future developments are also excluded.
One feature, one OSM element
A single real world object should be represented with one element only.
Syntactic conventions for new tags
There are some conventions about naming keys and values. Following them will help mappers to estimate the meaning of your tags without reading the documentation. Using a semicolon should be considered especially carefully.

Skimming though Editing Standards and Conventions might be helpful as well. Please also consider the On the Ground Principle (about current versus old data), fixme=* (for estimations), and names (names versus descriptions, avoiding abbreviations) if any of them might conflict with your ideas.

Due diligence

Your proposal is more likely to be accepted by the community if you take steps to research and vet your proposal before presenting it in front of a global audience. Some tips for success include:

  • Research whether tagging for this feature (or similar) has been discussed before, by searching the mailing lists or other forums. Consider what objections or concerns were raised in those discussions, and adjust your proposal if necessary to satisfy the concerns. It may not be possible to please everyone, but you will have the best chance of success if you make the effort to address as many concerns as possible. Provide links to these discussions in the "External Discussions" section; it shows that you have done your homework and are aware of past discussions that may have occurred.
  • Consider asking a trusted colleague or two in the community to review your proposal. Private dialogue before the Request For Comments (RFC) is extremely helpful in identifying and fixing problems. If the tagging for this feature was discussed on the mailing list in the past, consider a sending private email asking for feedback from one or more of the participants in that discussion. They may have expertise in that area, and the private dialogue will not only make your proposal stronger, but will help you build rapport with the active members of the tagging community.
  • If you are not a native speaker of British English, be sure to research what the thing you are describing is called in the British vernacular. It can be helpful to find UK-based web sites that discuss the topic in order to understand how it is phrased and used.
  • Research similar tagging schemes in order to ensure that your proposed tagging is consistent with other similar features and usages, and include those comparisons in the "rationale" section of the proposal.
  • Assume that the reader is not an expert in the topic or in the associated tagging. Give a brief introduction suitable for non-experts that allows them to understand the feature being described, the state of existing (inadequate) tagging, and how your proposal fills that gap. Do not assume prior knowledge, especially when proposing additions or changes to complex tagging schemes.
  • You should weigh potential benefits of the proposal with its potential downsides. This is especially important if your proposal attempts to deprecate, rename, or change the meaning of already existing tags (as processes to do so are much more complex and time involving - so in those cases one should invest extra time to suggest specific plans on how to handle those existing tags). See also Deprecated features#Everything is more complicated than expected.

Creating a proposal

You can easily create a pre-formatted proposal here.

Read these instructions before creating the page.

  1. Create the page using the tool below. The tool does not immediately create the page, but opens the editor for the page that will be created if saved.
  2. Making no edits, immediately save to convert the substituted values to text.
    Save proposal first.png
  3. Click on Edit in the upper-right heading.
  4. Click on the Proposal page template at the top of the page and click edit. Then input the specific details of the proposal for each of the parameters.
    Edit proposal page template next.png
  5. Follow the instructions in the comments under each of the headings to draft the proposal documentation.

Create here:

If you edit using the Wikicode editor instead of the Visual Editor, what is displayed will be a bit different. Instructions still apply: (1) create page (2) save to generate text, (3) edit page to fill the template and save again.

If you have technical trouble with creating a proposal page, feel free to ask for help by sending a message to the tagging mailing list, you can ask for technical help also elsewhere.

Optionally let people know of your new proposal by subscribing to tagging mailing list and sending a mail.

Proposal page template

You may also create a proposal directly by copying and pasting into a new page

Create a new wiki page such as Proposal:your_proposition_name (MediaWiki Help:Starting a new page) and then fill in the proposal page template and page details described below. Set the status to Draft and set the draftStartDate=2024-03-19 value (YYYY-MM-DD):

Place the following wiki text at the top of the page, and fill in the brief summary content fields: (See also: {{Proposal page}})

{{Proposal page
|name           = {{subst:SUBPAGENAME}}
|status         = draft
|user           = {{subst:REVISIONUSER}} / if there are more main porposal people involved use parameter: |users= {{u|username1}}, {{u|username2}}, ... 
|key            = <!-- The key of the proposed new tag, if relevant -->
|value          = <!-- The value of the proposed new tag, if relevant -->
|tagging        = <!-- If your proposal is about multiple tags, you may link them here like: {{tag|foo|bar}}, {{tag|bar}} -->
|type           = <!-- node, way, area, relation ({{IconNode}} / {{IconWay}} / {{IconArea}} / {{IconRelation}}) -->
|definition     = <!-- A short, clear definition of the feature or property which the new tag represents -->
|taginfo        = yes <!-- yes / no: to show taginfo statistics box -->
|appearance     = <!-- A possible rendering, if relevant - optional -->
|draftStartDate = {{subst:#time: Y-m-d}}
|rfcStartDate   = <!-- Date the RFC email is sent to the Tagging list: YYYY-MM-DD -->
|voteStartDate  = <!-- Date voting will start: at least 2 weeks after RFC, YYYY-MM-DD format -->
|voteEndDate    = <!-- Date voting will end: at least 2 weeks after start of voting, YYYY-MM-DD format -->
}}

== Proposal ==
<!-- A short statement of what you propose, including a list of what tag(s) are being proposed to be added, changed, or deprecated -->

<!-- Which Database Elements (nodes, ways, areas, relations) each of the tags can be used on could be included here or under the Tagging heading, or both. -->

== Rationale ==
<!-- Explanation of why the proposal is needed, and why you chose the specific key and value of the tag. Compare with similar tags or previous proposals, if relevant. Consider significance and potential uses of the data.-->

<!-- Keep the tag short while still being logical and descriptive enough to need little explanation. Avoid tag names which might cause confusion with a  different tag. British English terms are preferred, when possible -->

== Tagging ==
<!-- 
A table, list, or set of subheadings explaining each tag:
* Definition of the meaning of the tag and how it should be used
* Elements tagged: nodes, ways, areas or relations? [if a feature is smaller than 5m by 5m it would usually be mapped only as a node]
* Comparison with current tagging schemes (if applicable)
* Additional tags used in combination (including existing tags)
* When other tags should be used instead.
-->

== Examples ==
<!-- Examples of what elements should be tagged: real-world images, openstreetmap.org screenshots, links to OpenStreetMap elements that use the proposed tagging. -->

== Rendering ==
<!-- Optional rendering suggestion, if relevant -->

== Features/Pages affected ==
<!-- List of wiki pages that would be edited if the proposal is approved -->

== External discussions ==
<!-- Links to mailing lists, other forums where this proposal has been discussed... -->

== Comments ==
<!-- There must be at least 2 weeks set aside for comment on the proposal. Do not go to a vote without addressing the comments and fixing any problems with the proposal. The wiki talk page is used for comments, it is linked from the proposal page for those unfamiliar with wikis. -->

Please comment on the [[{{TALKPAGENAME}}|discussion page]].

Propose

Once the proposal contents are fully described, you can propose it to the community.

Propose

  1. Set these parameters in the Proposal page template at the top of the page:
    1. status = proposed
    2. rfcStartDate = 2024-03-19

Mandatory announcements

You have to announce your proposal as RFC on the Tagging mailing list and the Community forum (sending on behalf of you is allowed, see below). To send emails to the mailing list, subscribe to the Tagging mailing list first.

  1. Message content:
    1. Forum location: https://community.openstreetmap.org/c/general/tagging/70
    2. Tagging mailing list email: tagging@openstreetmap.org Send (mailto link)
    3. Title: [RFC] Feature Proposal - <PROPOSAL NAME>
    4. Body: <DESCRIPTION OF PROPOSAL> <LINK TO PROPOSAL ON WIKI> Please discuss this proposal on its Wiki Talk page.
    5. Assign the tags (for the forum): wiki-proposal, rfc

If you are not subscribed to the mailing list, add the following text to the topic body:

  • Please, cross post this announcement on the tagging mailing list on my behalf by sending an email to: tagging@openstreetmap.org

If you are not active on the forum, add the following text to the email body:

Note that it is always the responsibility of the proposal author to make sure it gets cross-posted. If it didn't happen within a few days, they should ask again.

Additional announcements

Consider sending your proposal to some additional contact channels to further increase community feedback and knowledge of it (not everyone subscribes to the tagging mailing list or is active at the forum).

If the proposal affects directly any existing tags/keys, you can notify people following them by posting a new topic in their respective Talk pages (for example, Talk:Key:historic for historic=* or Talk:Tag:historic=aircraft for historic=aircraft).

Solicit responses

You may get a small or a large response from the community, depending on the proposal topic, its importance, complexity, or interest. The main benefit of the proposal process is to have your idea reviewed by a wide variety of people from different regions and experiences, whose mapping challenges may be sharply different from your own. This process increases the likelihood that an approved tag is appropriate for the variety of situations that exist in the world.

If you find that you're not getting much response from the community, it's always appropriate to make additional posts or messages soliciting feedback, as well as consulting with the community in other channels or forums. Community feedback is important! While you don't need to satisfy every single commenter, be sure that you understand the concerns posed by the community and that their concerns are addressed before moving ahead with your proposal.

Respond

Look through comments that arise from the mailing lists, chats, forums, and the proposal Wiki Talk page.

When a discussion in a section created by another user on the proposal's Talk page is considered "resolved", you can add the {{Resolved|1=message}} Template directly below the section heading with an included message.

Adjust, even if it means changing key parts or tags, and continue to build a strong proposal according to community feedback so that it has a good chance of becoming popular with the voting and last but not least the mapping community.

Note that it is not necessary to implement all suggestion and requests. While many will be useful, it is possible to receive recommendations contradictory with each other, some can be also misguided.

If there are many changes to the proposal, it may be a good idea to document them in a timeline in a separate section called Changes for reference.

Voting

You still have to be subscribed to the Tagging mailing list for these steps.

Requirements before

Make sure your proposal meets these requirements before initiating voting.

  • At least two weeks have passed since start of a RFC.
  • All discussions have been resolved on the Talk page.
  • All major and minor disagreements about the proposal have been resolved.
    Remember, the community is voting on all parts of your proposal. If someone disagrees with at least one part of your proposal, they will often vote Oppose. Others will then read why that person voted no and they will likely vote no too. This can cause an almost-perfect proposal to flop.
    If this happens even when all parts of your proposal were resolved, do not be discouraged from continuing the proposal. Usually you only have to fix a minor part of your proposal. Once fixed, the proposal is now very-likely to be approved during the second round of voting.
  • The proposal is in its final state. It cannot be changed once voting starts.

Initiate

  1. Set these parameters in the Proposal page template at the top of the page:
    1. |status = voting
    2. |voteStartDate = 2024-03-19
    3. |voteEndDate = 2024-04-02
  2. Add this to the bottom of the page:
== Voting ==
{{Proposed feature voting}}

<!-- Cheat sheet:
{{vote|yes}} OPTIONAL MESSAGE HERE --~~~~
{{vote|no}} YOUR REASONS HERE --~~~~
{{vote|abstain}} YOUR COMMENTS HERE --~~~~

Place your vote below, at the end of the list. -->

Notify

You have to announce the vote on the Tagging mailing list and the Community forum (sending on behalf of you is allowed, see below). To send emails to the mailing list,subscribe to the Tagging mailing list first.

  1. Message content:
    1. Forum location: https://community.openstreetmap.org/c/general/tagging/70
    2. Tagging mailing list email: tagging@openstreetmap.org Send (mailto link)
    3. Title: [Voting] Feature Proposal - <PROPOSAL NAME>
    4. Body: Voting has started for <PROPOSAL NAME>. <LINK TO PROPOSAL ON WIKI>
    5. Assign the tags (for the forum): wiki-proposal, vote

If you are not subscribed to the mailing list, add the following text to the topic body:

  • Please, cross post this announcement on the tagging mailing list on my behalf by sending an email to: tagging@openstreetmap.org

If you are not active on the forum, add the following text to the email body:

Note that it is always the responsibility of the proposal author to make sure it gets cross-posed. If it didn't happen within a few days, they should ask again.

  1. Consider sending your vote announcement to some additional contact channels.

Requirements during

Make sure these requirements are met during voting.

  • The proposal is never changed.
  • Monitor the validity of all votes. One person voting with multiple accounts is not allowed, asking people outside OpenStreetMap community to vote is not allowed.
  • People should not just vote Oppose, they should give a reason for their proposal, and/or (preferably) suggestions.
  • It is acceptable for author of the proposal to end the vote earlier as a rejected, so that the proposal can be re-worked.
  • A list of active votes can be found at Category:Proposals with "Voting" status.

Post-vote

  • If you have no time to do the cleanup after the voting has ended:
Mark the proposal status as status=Post-Vote.
(See Category:Proposals without post-vote cleanup for features needing clean-up. If you have a minute, pick up a broom and clean up!)
  • After the voting period, make a summary of the voting by filling out the parameters of the {{Proposed feature voting}} template:
{{Proposed feature voting
 | closed  = yes
 | yes     = 
 | no      = 
 | abstain = 
 | result  = approved/rejected
 | comment = 
}}

It is a good idea to notify people about the result by sending an update to the tagging mailing list and the community forum.

  • Tagging mailing list
    • Email address:tagging@openstreetmap.org
    • <Subject:> "Feature Proposal - Approved - (Feature Name)"
    • <Subject:> "Feature Proposal - Rejected - (Feature Name)"
  • On the Community forum it's a good idea to update the voting proposal thread:
    • Update the body of the thread or add a comment stating if its approved or rejected.

Approved

If the proposal has found enough support, the status can be set to approved (both in result parameter in {{Proposed feature voting}} and in status parameter of {{Proposal page}} at top of the page).

"Enough support" is at least 8 approval votes and at least 75 % approval. A simple way of counting is that a minimum of 3 yes votes for every no vote is sufficient.

The explicit abstentions do not count as a vote (e.g. 10 vote "yes", 1 vote "no", 10 "abstain but have comments" would be approved), but all suggestions should be taken into account before a proposal is approved or rejected in order to resolve any deficiencies in the original proposal (if they exist).
Before you decide to reject a proposal because of lack of support, it may be worthwhile to send out a new vote request to the mailing list or make a new topic on the Community forum alongside the mailing list.

See /historic notes for list of substantial changes in the past. Older proposals are still considered "approved" if they met the standard in place at the time.

Clean up the proposal:

  • Do not move the proposal page!
  • Create the permanent feature description page:
    • A new page for the feature should be created/updated and the relevant map features template (depending on whether it is a key, a value, or a relation) should be applied. Follow the standard set by the Key:highway key and its values.
    • Add a link back to the proposal by using the statuslink parameter of the feature template.
    • Add a link to the permanent feature page in the proposal page using {{Approved feature link}}.
    • Archive the proposal using {{Archived proposal}}.
  • Add the completed feature to the map feature page:
    • Add entry to Map Features page if that is useful (for example approved niche tag may be not listed there).
    • Add entry to Changelog page.
    • Do not remove entries from Map Features even if your new feature that has been voted on is intended to replace them. It is not considered good style to remove things from Map Features while they are still in use. You can remove things from Map Features if they are not in a significant use. See also Deprecated features.

Rejected

If the vote fails, do not despair. Many proposals were rejected, modified and succeeded. Sometimes proposal fail because some people noticed issues during vote.

  • The status should be set to rejected.
  • Note any reasons why rejected on the feature proposal page.
  • Rejected features may be resubmitted, modified, and new vote started. You can also move back to the RFC process, or at least send some message to give chance of feedback without voting against.

Abandoned, canceled, obsoleted, undefined

  • Proposals should be set to abandoned if they have a long time of inactivity (at least 3 months) on the wiki pages (including all languages and discussion pages) and are also not added to the OSM database. A proposal that's unchanged in the wiki for a while might just be tested in daily mapping practice and thus may be very alive.
  • The person proposing a feature can cancel it by setting the status to canceled.
  • For proposals that have been obsoleted by another proposal, set the status to obsoleted.
  • For proposals which are inactive but not abandoned, set the status to inactive. For example used for tags (keys) which has reached 'de facto'-status based on this proposal without voting process (consider to also add the template: {{No vote feature link}})
  • For proposals with unknown status, set the status to undefined.

Note that abandoned/inactive proposal may be for tag that is in active use. In such case creating a tag page, applying {{Archived proposal}} on the proposal page and hiding proposal text may be the best solution. It keeps history available but users are directed to the active documentation.

See Proposal:Street vendor=yes and traffic park one for examples where it was used.

Non proposed features

Non-proposed features are mapping features which did not undergo the proposal process.

Even if OSM has a completely free data model (that is, you don't need anyone's permission), we try to moderate the Map features list for several reasons:

  • landing page for newbies: so it has to be clear and self-explanatory in every language
  • avoid feature conflicts: during a vote all eyes can keep duplicates away
  • keep list/categories short: even a design decision, we want to avoid an uncontrolled explosion of features and keys

Generally, new keys should always be discussed before being added to Map features. To increase participation in discussion, especially for new values of major keys like highway=* it is a good idea to formally propose them. Any new tag which replaces an established tag also requires a proper discussion, proposal process is a good way to achieve this.

Reviving old proposals

There are many old proposals that never reached vote stage and where the original authors have abandoned them. What can be done by a new unrelated person interested in making identical or a similar proposal?

  • restart the old proposal - it is a good idea if you completely agree with it. Consider contacting the original author whenever it is OK for you to resurrect it - and wait some time for reply. Send it again to request for comment (RFC) stage and continue to proceed like with any other proposal.
  • make a new proposal reusing content from the old one. Simply create a new page, feel free to copy existing content (you are allowed to do this, just mention source of text in the changeset comment). Mention inspiration/source of the proposal, but feel free to make any changes to it that you want. And proceed like with any new proposal. You can also do this with your own proposals.

Examples

Proposal process wiki history

You can find the history for this page there (as usual).

Proposal status overview list

Note that it describes status of the proposal, not status of the tag. There are rejected, abandoned and inactive proposals for many tags in a wide use.

  • draft: the proposal is in the initial starting period of writing down corresponding information
  • proposed: the proposal contents is fully described and it is proposed to the community
  • voting: the proposal is currently being voted on as part of the approval process
  • post-vote: the proposal voting is done and the voting cleanup isn't finished
  • approved: the proposal has successfully (found enough support) completed the approval process
  • rejected: the proposal is rejected (found not enough support) during the approval process
  • abandoned: the proposal has a long time of inactivity (at least 3 months) on the wiki pages (including all languages and discussion pages) and is also not added to the OSM database
  • canceled: the proposal is canceled by the person how did create the proposal
  • obsoleted: the proposal is obsoleted by another proposal
  • inactive: the proposal is inactive but not abandoned
  • undefined: the proposal has unknown status

See also: Tag status values

Lists of proposals

Main article: :Category:Proposals by status

Recent proposal status changes

List of abbreviations:
D
Data item edit
N
This edit created a new page (also see list of new pages)
m
This is a minor edit
b
This edit was performed by a bot
(±123)
The page size changed by this number of bytes

18 March 2024

      15:31  Proposal:Aerodrome 3 diffhist −3 Geozeisig talk contribs (status draft) Tag: Proposal status changed

16 March 2024

      17:50  Proposal:Adopter diffhist +130 Partytax talk contribs (add voting summary) Tags: Proposal status changed Visual edit: Switched

12 March 2024

      11:01  Proposal:GTFS Tagging Standard diffhist −1 Spaanse talk contribs (Post-Vote → Approved) Tags: Proposal status changed Visual edit

See also