Semi-colon value separator
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.
- 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.
- Complex values that cannot be evidently represented using subkeys (notably when they are unordered lists of items) may use semicolons: opening_hours=Tu-Fr 08:00-18:00;Mo 09:00-18:00;Sa 09:00-12:00;closed Aug
When NOT to use
In general avoid ';' separated values whenever possible. Don't use them in your mapping, and don't propose them on the wiki if there are better ways of representing things. This is because use of semi-colons as value separators is contrary to the aim of keeping it simple both for data contributors (mappers) and data users. For the sake of new contributors and anyone trying to use the data (people building software for rendering, searching, "find my nearest cafe" mobile apps, etc) we should minimise use of values with special characters.
It is particularly important to (wherever reasonably possible) avoid ';' separated values in more important "top-level" tags. That is, tags which define what an element is. In situations where you have multiple values, there are normally a couple of 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 ';' in the amenity value, then that isn't going to show up in a "find my nearest cafe" mobile app any time soon. Even though it is entirely possible for systems to parse the value, and split it by the ';' character, most existing systems don't.
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. As this situation pretty much never occurs, it's really only mentioned here as a curiosity. Very few tools that use OpenStreetMap data will understand this.
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.
- iD, Potlatch 1, and Potlatch 2 all join tag values with semicolons when merging ways which have tag with the same keys. In most cases this creates invalid tagging and needs to be replaced by a single, valid value. However, when adding a tag with a key which exists in another preexisting tag of the same feature, iD adds another tag with a different key which is created by appending
_2, and so on to the original key.
- JOSM does that only if the user explicitly selects to keep "all" tag values in the prompt.
- Mapbox Streets replaces
;with a spaced em dash (
—) in any name=* or name:*=* tag. For primary keys such as amenity=* or shop=*, it considers only the portion up to the first semicolon and drops the rest.
- MapQuest Open interprets ref=* by placing each semicolon-delimited value on a separate shield.
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.