Defaultpresets Guidelines

This page contains rough guidelines for the defaultpresets and new icons.

New Tags and Values

Please first check that there is not already a ticket for this tag e.g. by using the search function at this page top right.

Basically we have to make sure that the preset menu isn't too cluttered, because it would get hard to find the useful every-day stuff if we had too many exotic entries. New tags and values should have:

  • a proper documentation in the OSM-wiki,
  • decent usage numbers (absolute and by number of mappers),
  • world wide usage,
  • controversial cases (like contact:phone=* vs. phone=*) need to be decided case by case,
  • if a features is only mapped by a handful of specialists, it is better suited for an external preset. Usually this includes tagging schemes restriced to one specific country, hobby, sport or profession. Instead of creating an own external preset you could also extend Presets/NewTags.


  • The goal of the internal preset is to support the tags and tagging schemas which are widly accepted and used by the community. It is not the goal to invent new tags or tagging schemas.
  • When investigating taginfo, also check where unusual values are used.
  • You can use overpass API to load these object in JOSM and check in the history who created them.
  • See also this example to search for the last editor of an specific tag.
  • A useful tool to check tags is also taghistory. If a tag is mapped e.g. 50 times per year global, then we usually don't need a preset for this tag. You can still always add tags manually via the Add tag dialog.
  • When modifying the defaultpresets also the main mappaint style and maybe also validator rules should be changed for consistency.

New Icons

  • The file format must be svg for lossless scaling. (Technically png is supported too but all preset icons are svg since August 2016.)
  • The icon must be identifiable at a size of 16 pixels. This is the default size the icons are displayed in the Map View on standard dpi (not hidpi) screens.
  • The license needs to be compatible with GPL3 (like PD or CC0). A good source for Icons is (all icons there are PD), (all icons CC0), (all icons CC0) or (a lot are CC0). You can also check if JOSM already has a fitting unused icon in one of its icon folders: used icons and unused icons.
  • If the tag applies to nodes, the icon in the MapView and the icon of the preset should be the same if possible. (It is not possible when different features use the same preset, e.g. crossing=island and crossing=traffic_signals have different icons, but are handled in only one preset "Pedestrian Crossing".)
  • Icons with transparent background must not be only black or only white. Otherwise if one uses a black or white background (no aerial imagery as background) in the Map View black or white icons would be invisible. Workaround: if you want to use a black icon add a square white background to the icon instead of a transparent background or better use a white halo.
    Example: Colored icons are preferred though.
  • The icon should hide as less as possible in the mapview, so colourful icons with transparent background are preferred over black/white icons with square background.
  • The icon should be understandable in all countries.
  • Each preset should have its own icon and not borrow an existing icon from another preset so that you can know the tag from just seeing the icon in the mapview.
  • To test your icon against these requirements within JOSM the mappaint style Icon tester helps you.

Possible problems with svg in JOSM

Please check if the svg file correctly works within JOSM.

  • The base size of svg should be 16px or larger than 64px. Images with a base size between 16 and 64 px will not be scaled down to 16px.
  • There are some svg libraries which do not work with JOSM (the images get deformed). If you have such a file try the following workaround: create a new svg document with Inkscape, copy the svg data to this new file, resize the page to the data and save.
  • Resize your icon to 16px or an integer multiple size of it (not something like 458.1534) to avoid display inaccuracies due to rounding errors within java.
  • Check the code of the file in a text editor. Search for viewBox value in the beginning of the file. If the icon is, for example, in 16x16 pixels, and if you made it in Inkscape (at least this happens in 0.91 version) and have defined in Document Properties 16,00000 by 16,00000 pixels, probably in the file code you have these values viewBox="0 0 16.000002 16.000001". Change it to viewBox="0 0 16 16" or you will have problems (see #12201 and the fix [o31865])
  • svg icons are automatically cleaned up to reduce file size in the JOSM build. So there is no need to do this step manually before uploading svg files to svn. See comment:35:ticket:10479, comment:10:ticket:10877 and ticket:12201#comment:21 Uncleaned svgs are better for further editing.
  • Due to a bug in svgcleaner however, the svg code shouldn't contain arguments starting with special characters in style codes e.g. -inkscape-font-specification:Sans;. This can lead to color changes (see #13158).
  • If the icon includes gradients, the offset needs to increase at every stop, i.e. two stops with the same offset are not allowed, see svg salamander.
  • CSS styles (<style type="text/css">) are not supported yet by svgSalamander.
  • If possible don't use text elements at all as this can lead to different display results based on e.g. os or installed fonts. To avoid this you can transform text into paths in the svg.
  • Some of the named problems can be detected by executing this script.

See also

Back to Developers Guide
Back to Main Help

Last modified 21 months ago Last modified on 2022-08-21T10:32:15+02:00

Attachments (1)

Download all attachments as: .zip

Note: See TracWiki for help on using the wiki.