Mechanical Edit Policy

From OpenStreetMap Wiki
Jump to: navigation, search
Available languages
English français

This is a draft for a policy that governs mechanical edits to the OpenStreetMap database.

Edits Covered by this Policy

Generally, this policy covers all edits where an individual change to an object is not performed by a human being. This includes:

  • all automated changes made by software ("bots");
  • all data imports (where data is created not by survey or tracing over imagery, but by converting from another data set), no matter whether the import is fully automated or whether it just generates OSM files that are then uploaded through an editor without manual review of each object;
  • search-and-replace operations using an editor (e.g. if you use your editor to select all post boxes without an operator tag and then add an operator tag to all of them) unless your changes are backed up by knowledge or survey rather than just reckoning;
  • search-and-replace operations using something like the XAPI service (e.g. you load all objects tagged highway=grade1 worldwide and use your editor to re-tag them highway=track,tracktype=grade1)

This policy places strict rules on such mechanical edits because they have the potential to cause harm, to damage the work of others, or to unilaterally override their opinion.

This policy does not apply to edits made truly by hand. If you select each post box in your city and add an operator tag to them, then we assume that you are indeed looking at the individual object and improving the data from your knowledge or a survey, and that's ok. You can even use your editor's search-and-replace function for that but only if you check each individual action caused by this, rather than just mechanically changing things. The same applies to imports - if you manually check each data object that gets imported, you are outside of the scope of this policy.

General Issues about Mechanical Edits

Mechanical edits are generally not desirable in OSM. Wherever possible we prefer real people to edit data by hand in areas they know. There are so many things that can go wrong with mechanical edits (from sloppy planning to bad execution to undesired side-effects or offended mappers) that the cost usually outweighs the benefit.

If you are reading this because you are planning to execute mechanical edits, think twice; can you perhaps switch to a system (be that a web page or an editor plugin or something else) where your algorithm points out potential problems or suggests changes, but does not perform them automatically?


If you want to perform any mechanical edits, you must meet the following requirements:


You must discuss your proposed changes with the community. You must not go ahead with your plans if there is noticeable opposition. As a rule of thumb, you should have 90% of the community behind you when you make the edit. Depending on the type of edit, the discussion must take place in:

  • Either the international, English-language list
  • or the international, English-language imports list, for fixing of previous imports
  • or if your edit affects only a small number of countries, the national-language mailing lists, forums, or other standard communication methods for the countries or areas affected by the change

If your edit will affect a large amount of data, you should expect to discuss the change thoroughly with input from at least ten or fifteen people. For worldwide edits that change existing tags you should receive input from contributors around the world, as you may miss a localised understanding and anger a lot of people. Remember, you may get general agreement from ten people after a week's discussion, but you could still run into trouble when thousands of contributors notice the change.

You must document your proposed edit at:

  • An English-language wiki page named "Mechanical Edits/username" (where username is the OSM user name of the account that you will be using to perform the edits - think about this now so that you don't have to rename the page later), and added to the category "Mechanical Edits"

(The suggested procedure is: Present your idea to the appropriate list, and forums if appropriate; if people generally agree, create wiki page with details and discuss in earnest, then proceed - or don't.)

So, for example, it is not sufficient to discuss something on the Spanish mailing list if you want to make a worldwide change, but if your change affects only Spain then that's fine.

If you run some kind of regular automatic change mechanism (a "bot"), then each configuration change (e.g. adding a new misspelled tag to correct) requires new community approval; you cannot get blanket approval for some unspecific "I am fixing misspelled tags".


You must write documentation that covers the following:

  • Who is making the change (real name and how to contact, ideally e-mail address)
  • What the change is about, with a detailed description of the algorithm used to decide which objects are changed how (i.e. it is not enough to write "fix misspelled tags" but you will have to provide a full explanation on how exactly you are fixing what)
  • Details about the discussion that was held, with links to mailing list/forum posts or Wiki discussion pages
  • When the change was made, or how frequently it is going to be repeated
  • Information on how to "opt out"

This documentation must be available on a wiki page named "Mechanical Edits/username" (where username is the OSM user name of the account used to perform the changes). It is suggested to place a link to that page on the OSM user page of the account. Look at Mechanical Edits/example for how this page should look like.

The documentation must be written either in English, or in the usual national languages for all territories covered by the change. For example, if you make a change that affects some places in France and some places in Spain, you have to provide your documentation either in English, or in French and Spanish.


We recommend setting up a special account for mechanical edits but you may use your existing account. Any account used to perform mechanical edits must have agreed to the new Contributor Terms.

When uploading changes, you must add a "comment" tag to the changeset that describes the changes made in this changeset in a human-readable way. You must also add the tag "mechanical=yes" (or "bot=yes"), and you must link to the wiki page or user page documenting your changes from the "description" tag (e.g. "description= Edits/John Doe#Tag Fixup January 2013").

You must provide a means for mappers to "opt out" of your changes, i.e. if someone contacts you and asks you to stop making mechanical edits to things that they have edited, you must comply with that wish, and you must modify your software or procedure to leave those objects untouched in the future.

Problems, Complaints

It is always possible that people will be unhappy with the edit, even after extensive discussion. So be ready for this, and handle all user complaints seriously and politely. If you have followed this policy then this means your account will not be blocked right away when someone complains, but you might still have to change or stop what you're doing if people dislike your actions and / or their side-effects.

Your edit may be reverted even if you have followed this policy; this doesn't guarantee your edit will be accepted.

Data working group will, on suspicion of mechanical edits not following this policy, either block the account immediately or send out a warning message (depending on how intense the editing activity is). All mechanical edits not following this policy are liable to being quickly reverted when they are discovered.