OpenStreetMap is a free project done by volunteers. Anybody can enter anything he or she wishes. That said, a map works best when participants agree on a code of conduct. These "Good Practices" are guidelines that will increase the quality and value of our map data without any additional effort. Nobody is forced to obey them, nor will OSM ever force any of its mappers to do anything. There might be cases where these guidelines don't apply, or even contradict each other.
- 1 Do correct errors
- 2 Map what's on the ground
- 3 Verifiability
- 4 Don't map historic events and historic features
- 5 Don't map temporary events and temporary features
- 6 Don't map your local legislation, if not bound to objects in reality
- 7 Don't map for the renderer
- 8 Good changeset comments
- 9 Don't use name tag to describe things
- 10 Keep the history
- 11 Check the history of important objects
- 12 One feature, one OSM element
- 13 Keep straight ways straight
- 14 Map bends with an appropriate number of nodes
- 15 Average out GPS-traces
- 16 Align aerial imagery before tracing
- 17 Do not trace from outdated imagery
- 18 Mark estimations with FIXME
- 19 Don't remove tags that you don't understand
- 20 Document your custom-tags
- 21 Don't over-use semi-colon separated values
- 22 See also
Do correct errors
If you find elements with tags that you think are wrong then do correct them. It's a wiki, your corrections can always be reverted, so be bold.
Map what's on the ground
Sometimes there's conflicting information about, say, the name of a place. An old map might call it one thing, current maps another, and the place name sign something else. People using our maps (for navigation) won't care about the spelling in other maps, they need to find the names from local signs in the map and vice versa. The only exception to this could be obvious misspellings on signs like John-F.-Kennwdy Square. Assuming that people would intuitively look for the correct spelling it makes sense to correct these.
- Main article: Verifiability
OSM data should, as far as is reasonably possible, be verifiable. The principle applies to tags and other aspects of data representation, and essentially means another mapper should be able to come to the same place and collect the same data ("verify" the data you have entered). This principle excludes hypothetical or opinionated data like personal ratings (it is strongly encouraged that you use ratings from tourist boards or associations instead).
Don't map historic events and historic features
This is a consequence of the verifiability requirement. Do not map historic events. Also, do not map objects if they are not there anymore because such features cannot be verified. Historic events have been discussed here. If ruins are left (and thus verifiable), then map the ruins (for example using historic=ruins). There seems to be agreement that abandoned and dismantled railways may be mapped if at least some traces are left (use for example railway=abandoned). Abandoned and dismantled railways were discussed here. Objects that no longer exist can be mapped on OpenHistoricalMap (see Open Historical Map).
Don't map temporary events and temporary features
Our map data gets downloaded a lot, and then used offline on various devices for several weeks or months. So for offline data to be useful, it should at least be expected to remain unchanged in the next few weeks when you map it. Certain events that happen in a regular pattern (like a weekly market) can be mapped by using different time tags.
This guideline also means not to map insignificant seasonal or perishable small plants or objects without a fixed location that are easily or regularly moved, as they are not readily verifiable on ground. Also, please do not map unstationary living beings (like dogs or people).
Don't map your local legislation, if not bound to objects in reality
Things such as local traffic rules should only be mapped through the objects which represent these rules on the ground, e.g. a traffic sign, road surface marking. Other rules that can not be seen in some way should not be mapped, as they are not universally verifiable.
Don't map for the renderer
- Main article: Tagging for the renderer
Draw things the way they are on the ground - do not enter incorrect data just because it will help renderer, navigation or some other data consumer has problem with correct data. They are continually improving, don't bend the data to make it look prettier, just be patient.
Good changeset comments
- Main article: Good changeset comments
A good changeset comment should concisely and adequately describe an edit. You should do this out of courtesy to your fellow mappers, to avoid misunderstandings, and get mistakes fixed quickly. It makes your edits more valuable. It may even help you when you look back at your edits in future.
Don't use name tag to describe things
- Main article: Names
The name tag is to be used for the name of a feature. It is not a place where you should describe or classify the feature. We use other tags for that. For example it is wrong to have a tag '"name=track" on track leading through a forest. Instead it should have the tag highway=track. If the track has a name (like a street name), it would have a name tag too. If not, then there should be no name tag.
You can find appropriate tags in the editors using their presets. In iD just start typing after you added an object, in JOSM you can search the presets after pressing F3. If you don't find what you need search this wiki or Taginfo - or just ask the community. If you cannot find matching tags, add a note=* or description=*.
Keep the history
When things change in the real world, be bold, and edit the map to reflect the current situation. But be aware that OpenStreetMap can store the editing history of an element, and you can help preserve this history by making sure you re-use one element when it becomes something different. Example: If a café closes down, don't delete the node. Just remove the cafe tag, and leave other tags (like the address) in place.
When updating buildings or landuse you may wish to delete and redraw anew, but to retain an editing history it may be better to edit existing objects. For JOSM there is a tool "replace geometry" in the plugin utilsplugin2. With this you can draw a new outline of an object and then move the history of the old outline to the new outline (simply select both objects, then press CTRL+SHIFT+G).
When you find a single node for an object, and want to draw the outline of the building or the campus, it is good practice to keep the node (without its tags) prominently in the outline (e.g. as a corner of the building or the campus entrance). This preserves the history of the information in the "old" node, which is easy to find when somebody inspect such an object.
Example (school node to campus outline):
- move the school node to a corner of the aerial image
- draw the campus with this node as one of the corners
- copy the tags from the node and delete all its tags
- paste the tags on the campus outline
- remove old object source tags
- when uploading, add your source to the changeset (not to the campus object)
Check the history of important objects
Before making significant changes to important objects (in particular settlements, administrative boundaries, major buildings, tourist attractions,long route relations etc), check their history. Who did this and why? Was this an experienced contributor or a newbie? Previous editors may have valuable insights to offer on why things are currently tagged the way they are.
One feature, one OSM element
- Main article: One feature, one OSM element
Don't place nodes in identically tagged areas just to see some icon appear on the map. The renderers will display icons on areas as well and there's no need to have every parking-lot, soccer-ground, etc., duplicated in the database.
Keep straight ways straight
- Main article: Editing Standards and Conventions
When there's a road that's dead-straight, draw it as such. That's done by just one line between two nodes without any nodes in between. Many roads are actually perfectly straight even though your GPS-track may not reflect this (Accuracy of GPS data).
Note however that real driving restrictions may force you to follow a zigzag path along a street that is generally straight: there may be parking lots or obstacles alternating from one side to the other, or a central lane whose direction alternates regularly from one side to the other: follow the central separation line between lanes in opposite directions and add the relevant number of lanes in each forward/backward direction for each section where the number of lanes changes (in some cities some residential streets may even include sections with alternating directions for driving on a shared single lane, and a priority for one direction, with wait lanes just before a parking lot or barrier). Overall the street is still straight if we include all its surface (including parking lots, bus/taxi service lanes, cycling lanes, obstacles and sidewalks).
JOSM, iD and Potlatch all have tools to straighten streets with intersections. That keeps our data slick and makes the maps look better. Having said that, if you have multiple GPS traces for a particular road and they all show a bend in the road, or you see the road's shape in an aerial photograph – then depict this shape in OSM.
Map bends with an appropriate number of nodes
Ensure you use a reasonable number of nodes to record bends and other features. There's no hard or fast rule about how many nodes should be used to map a bend in a road - you need to use your own judgment - but there should be enough so that the angle between successive parts of a way should not be too large (e.g. shouldn't be close to 90°). This means that on sharper corners - the nodes will need to be closer together to map a smooth curve in the road than on relatively shallow corners.
Average out GPS-traces
- Main article: Accuracy of GPS data
The accuracy of the points in a single GPS trace may be out by several meters. This depends on lots of factors such as the positions of the satellites when the trace was taken, tree cover, proximity to nearby buildings, position of the GPS unit relative to the center of the road etc. If many traces are taken for the same road, then the effect of errors in any one trace will have a much smaller impact on the average position of these traces.
To help with this, it's useful if you upload all traces to the server - even if they cover roads already in the database. This allows others to use your traces to average out the errors and should eventually result in lower position errors. If you have many tracks covering the same way, you may also try the "average tracks" script to make one "average" trace.
Align aerial imagery before tracing
- Main article: Using Imagery
Aerial imagery will, regardless of source, have offsets to the real positions of objects on the ground. While this can be small enough to be ignored, it can be substantially more than typical GPS errors (>> 10 meters) and change over small areas (requiring re-adjustment). It is mandatory that you check this before moving existing OSM data, or adding more.
Potential ways to align and check alignment:
- existing GPS tracks or high precision POI data
- existing OSM data
- Strava heatmaps
iD, JOSM and Potlatch have tools that support imagery alignment.
Do not trace from outdated imagery
- Main article: Armchair mapping
Just because it is available doesn't mean that aerial imagery is up to date. Be sure to check that the existing OSM data you are about to change or delete is indeed older (check its history) than the imagery you are looking at. Best is to only map areas that you visit and verify yourself.
Mark estimations with FIXME
Sometimes it makes sense to map estimated positions rather than not mapping the object at all. But always mark your estimations with a fixme=* so you or somebody else will come back to it.
Sometimes you will come across elements with tags that have no meaning to you. This doesn't automatically mean you should remove them. They may have been added for a specific purpose. If you think they might be junk then try to contact the author.
- Main article: New Features
When you use tags yourself that aren't on map features, give other mappers a chance to understand (and maybe adopt) them by documenting them in the wiki. Please do not use the map features section of the wiki for this (including all pages where the URL starts with //wiki.openstreetmap.org/wiki/Key:... or //wiki.openstreetmap.org/wiki/Tag:...), as these are the community endorsed tagging recommendations reserved for well established tags with significant usage. Instead you should set up a proposed feature page or put the documentation on your user page or a subpage of it. Or mention the tag on a "talk" page of a wikipage. Setting up a proposal is the preferred method of documenting custom tags.
Don't over-use semi-colon separated values
Semi-colon value separator characters can be introduced into values, where the same key needs to take multiple values. This can be useful for putting lists of values into certain type of minor attribute tags, however it should be avoided in more important top-level tags. In general these special characters should not be over-used, since they detract from the simplicity of the tagging system.
- Editing Standards and Conventions - Another set of recommendations on aspects of mapping
- Tagging_samples - Tagging samples with actual photos
- Category:Tagging guidelines by country - These country specific wiki pages usually contain better explanations than the main wiki.
- Any tags you like
- Just Map
- Mapbox QA guide