Creating a page describing key or value

From OpenStreetMap Wiki
Jump to navigation Jump to search

This wiki has many pages documenting specific keys or values, such as Key:surface or Tag:leisure=hackerspace.

But there are many popular or useful tags that are not yet documented. It is useful to create also new pages for them. This page is intended to help with that process.

To start: feel free to create documentation for tags that are used already and there is no wiki page for them!

For example see this highly used tags without a wiki page:

The general idea of wiki pages is to tell and explain the current database situation in regard of different taggings.

Documenting tag is not a tool to redefine their meanings or to introduce new tags replacing ones that are well established. This can be done using the proposal process or after discussing it with other OSM mappers in way that gives voice to all effected (via tagging mailing list or some local forum if issue is more localized).

Proposing new tag

Main article: Proposal process

Note that if you want to create new tag it may be very useful to follow proposal process or at least consult with other mappers. Maybe such tag exists already? Maybe something can be modified to make it more useful and avoid problems while used on another continent?

Page creation

TODO: what should be recommend as place to ask for technical help? Talk:Wiki? Tagging mailing list?

If you follow any red link (TODO: while logged in?) you will get proposal to create a page.

One of the best strategies for dealing with technical site of page creation is to visit existing simple page describing key/value, click edit button, copy content and paste it at a new one.

For example Tag:building=church may be a good fit for a based for tag page and Key:house may be a good base for key page.

Template:KeyDescription and Template:ValueDescription have documentation about infobox templates.

Gathering info

But often a tag is in a wide use and not documented at all. Remember that point of Wiki in such case is to document actual usage rather than describing how you want this tag to be used or guess based solely on the tag name. Following resources are useful in gathering info

  • Taginfo can help by showing usage patters
    • For popular tags there is map tab - it allows to distinguish widely used tag from one appearing in a single town
    • Chronology tab is allowing to distinguish tags added by import and mass edits (vertical jumps) from ones added by individual edits (slope without vertical jumps)
      • Chronology can also be retrieved in the OHSOME dashboard from a more featureful interface
    • Key pages also have info how many different users have last edit on objects with this tag. Note that it is not the same as "how many user accounts used this tag", but may reveal recent mass edits and imports.
    • Values and Combinations tab can help revealing common tagging patterns
  • Is it present in presets of editors? Is it tag that was discussed on issue tracker of JOSM, Vespucci, StreetComplete or iD? (TODO: link issue trackers)
  • Is it something that was discussed on tagging mailing list or somewhere else?
  • Is it clearly duplicating other tags? For example if shop=fresh_vegetables_and_fruits is used 1200 times it is worth documenting only as duplicate of shop=greengrocer
  • Overpass Turbo
    • TODO: give more info
  • Own knowledge - but remember to check how it is used elsewhere!
  • Documentation on this wiki and elsewhere
  • You can ask directly people who used tag using changeset discussion, useful especially for tags that were imported
  • If tag was imported - it should be documented on import documentation page
  • Use "What links here" on side panel (in "Tools" section). It works also on not-yet existing pages. It is possible that other pages already mention this tag and may contain some information or reveal related tags.

This strategy above is also useful for improving wiki pages, not only creating new ones.

Sometimes during gathering info you may discover vandalism, copyright violation or undisscussed import that should be reverted. Please, do this or contact people capable of handling this.

It is normal to spot invalid or highly suspicious data during such research - if you are unable to fix them remember to create notes about any spotted issues!

What is useful

  • Description of feature, even if it obvious (meaning of shop=convenience is not obvious for people with limited English)
  • Useful information about tag - it highly depends on specific tag (TODO: be more specific)
  • For key: valid values
  • Related tags, especially in cases where there is an alternative tagging or something often combined together
  • Tagging example such as this one are often useful.
  • how to map guide section
  • Infobox with filled summary


Main article: WikiProject Cleanup#Images
  • Image in infobox serving as a good illustration. Ideal image would be
    • Uploaded to or optionally this wiki (it must be uploaded to one of this sites)
    • Illustrating given tag/key
    • Not misleading
    • Well looking even if displayed as a tiny thumbnail
    • For bonus points: interesting and a good photo on its own
  • Filled tag status

Finding a good image

example of an image considered to be within scope of Wikimedia Commons: "Reasonable quality photographs of identified places are very unlikely to be considered not in scope [...] scope is very broadly defined. Reasonable quality photos of public places are generally considered to be in scope. So, please go ahead and upload those photos."[1]
One of photos taken and uploaded to Wikimedia Commons as illustration for OSM Wiki. Used on Key:turn:bus:lanes. It was taken solely for purposes of improving OSM Wiki, but is one of types of images welcome at Wikimedia Commons, and anyone else also may use it.

You can try searching on Commons, visiting relevant Wikipedia articles and using that to locate image or using categories on Commons to locate fitting image.

If you are unable to find a good image on Wikimedia Commons you can upload new one there. Or directly to OSM Wiki.

Note that uploaded image must be either on open license (author released it under license allowing such use). There are some rare exceptions such as "fair use", but none applies to images used on tag pages.

You can simply take own photo and upload it to Wikimedia Commons and make your own decision to release it under open license. With some exceptions you can almost always do this with photos you have made.

If you understand licenses you can also upload images made by other to Wikimedia Commons. They have nice guide about this. There are also some special tool for example tools for transferring eligible Flickr images.

Note that it is perfectly fine to modify image from Wikimedia Commons and upload modified (for example cropped), see Commons documentation page (you need to specify source and license correctly)

Translating pages

Main article: Wiki Translation

See also

External links


  1. "Realistically useful for an educational purpose". Discussion archived on Wikimedia Commons.