User:Jgpacker/Semi-colon value separator

From OpenStreetMap Wiki
Jump to navigation Jump to search

We use a semi-colon value separator (the ';' character) in our tag values in some situations. This can be necessary when a single element needs to take multiple values for the same key.

It is important to know that only a few specialized applications will handle semi-colon separated values, and only for a few tags. Most OSM Tools, map renderers, taginfo and the XAPI do not handle these values. A few will only match the first part of the concatenation but most will consider the whole string as one value, so the entry is dropped from search results and tool output as unknown and it is never rendered on the maps.

How to use


  • ref=B500;B550 for a section of road that is designated both B500 and B550. You would only do this if the same section of road takes both ref values. Note: If there is any point on this section of road where you move from one ref to the other, then this is not the correct approach. Instead you would place a node and split the way at that point.
  • Some more minor "properties" tags lend themselves to taking multiple values. For example when mapping a car shop you can add a tag: service=dealer;tyres;repair as described on the Tag:shop=car page.

Space character padding

Often we use semi-colon separated values without any additional spacing (example: ref=B500;B550), however it is possible to add a space character after each of the ';' characters (example: ref=B500; B550). This is particularly true when tagging Opening times. This is currently an inconsistency between JOSM and Potlatch (both versions) in their approach to automatic value separating.

Escaping with ';;'

If a semi-colon exists in the actual value of the data mappers should enter it as two consecutive semicolons ';;'. This is an "escape character" approach used in computer programming and data formats. OpenStreetMap data will understand this. But an interesting follow on from this, is that we are assuming empty values are not permitted. This is probably common sense, but it means that any editor/app which allows empty values into the data (probably a bug) may cause some ';;' confusion.

Older separators

Prior to a community consensus on the use of the semi-colon ';' several other characters were suggested to separate values. These included: "/" (solidus), " " (space), "-" (hyphen), and "#" (number sign). The semicolon is now widely accepted as the character to use, and is supported by Potlatch and JOSM. Older variants can now be replaced.

When to avoid

Semi-colon value separator characters can be useful for putting lists of values into certain attribute tags (such as cuisine=* or ref=*), however it should be avoided in more important "top-level" tags. That is, tags which define what an element is. In situations where you want to add multiple values to this kind of tag, you can try these alternative approaches:

  • Choose one of the values Take the overriding "primary" value, and go with that. Example: You're mapping something which is a cafe but also a bar. It's much more helpful to just pick amenity=cafe or amenity=bar (look at the cafe/bar, and make a choice. Is it primarily a cafe, or primarily a bar?) It is not a good idea to map it as amenity=cafe;bar.
  • Split the element Separate things out into distinct features to allow them to be tagged separately with normal tags. Example: You're mapping a library which has a cafe inside it. Place a node for the cafe, and then either represent the library (a larger building) as an area instead, or just as a separate node. It is not a good idea to map it as amenity=library;cafe

In both examples, if you use a semicolon in the amenity value, then that place isn't going to show up in most maps, even if these maps were supposed to show an icon for one of the values. Even though it is entirely possible for systems to parse the value, and split it by the ';' character, most existing systems don't.


If you're proposing a new scheme which would seem to require values splitting with semicolons, consider converting it to a namespaced approach with Boolean values and using multiple tags. For example, a hypothetical scheme for describing the sorts of books and items a public library offers could be expressed as:


It's probably better to rewrite the scheme to express the concepts as:


payment=* and fuel=* are good examples of this second approach. Boolean-valued tags such as these can be extended with extra values later on if necessary, or even sub-namespaced meaningfully.

See also