Multiple values
An OSM Tag is normally made of one key and its corresponding value. This enables mappers to describe most real-world objects, but sometimes making multiple values (MV) correspond to one key is very useful, or at least very tempting. This page explains the why and how of MV tagging.
When (not) to use multiple values
For better or worse, a mapper's first reaction to MV tags should be to avoid them. This is largely because many data consumers do not handle MV tags well, either because they didn't expect them or because handling them is complicated. As the OSM data model doesn't directly support multiple values, they have been tacked-on with various degrees of awkwardness.
Avoid MV tagging if...
- A key cannot logically have multiple values, such as highway=primary;secondary. This is usually caused by editor software merging two objects together and not knowing a better way to fix discrepancies. Figure out which road classification is more correct and use that.
- There is another tagging scheme which expresses things better, for example using recycling=glass;paper
with recycling:glass=yes + recycling:paper=yes. These schemes are easier to parse and more versatile. - Always try to use semantic tags instead of chaining values together. Use for example old_name=*, loc_name=*, short_name=* instead of a MV in name=*
- You can map things as separate objects, for example, map the amenity=toilets separately from the other amenity it is found in.
- The second value is only for a very minor characteristic that might as well not be mapped, such as a big houseware shop that happens to also sell a handful of sweets.
Use MV tagging if...
- None of the above applies but you still need multiple values.
- You do not have enough information to use one of the more nuanced tagging scheme (for example if you have no way to tell if a name variant is old or local).
How to tag multiple values
As OSM doesn't natively support multiple values for keys (yet), mappers have come up with various MV tagging schemes, each with their pros and cons. The ones listed here in no particular order all have significant community support and usage numbers. In many cases, the choice is a matter of personal preference. They are sometimes even mixed together in a single object or tag, but this isn't recommended.
Semi-colon value separator
Separate values with a ;. For example,
Pros:
- Very little extra typing needed.
- Reasonably easy to read.
- Fairly well supported by consumers for some keys, like ref=*.
Cons:
- Cannot be used for keys whose value may contain a literal
;(the proposed workarounds for this is unlikely to be well supported). - Makes it easier to reach the 255 characters limit imposed by the API.
- Non semicolon-aware data consumers are likely to behave badly when encountering semicolon values.
- Semicolon-aware consumers need to maintain a whitelist of keys which may use semicolons.
Numbered suffix in key
Superfluous values are put in a new tag where the key gets a suffix consisting of a colon and a number. For example, multiple images can be added by putting the first in image=*, the second in image:1=*, the third in image:2=*, and so on. OpenHistoricalMap has standardized on this syntax for multiple source or image tags.
Note: some editing software uses :0 instead of :1, notably OpenPoiMap and MapComplete. There isn't a standard yet, and both options co-exist.
Seamark attributes (such as lights) have been using :1 tags for a long time. Parking lanes with multiple restrictions used to also use indexed subkeys until a 2022 tagging reform.
An approach like numbered suffixes is the only way to exceed the 255 character limit for values, which matters especially for tags that are prone to needing long values such as inscription=* or for destination signs.
Pros:
- Reasonably easy to read.
- No issue with literal separators in value.
- No issues with the 255 character limit. (A tag's value cannot be longer than 255 Unicode characters.)
- Non suffix-aware consumers just ignore the extra values.
- Suffix-aware consumers can use a simple straightforward implementation for all keys.
- Supports namespaced keys by specifying which namespace(s) of the key has multiple values, instead of just the key as a whole (for example source:1:name=* would be the second source for the name, while source:name:1=* would be the source of the second name).
- Like any multi-value scheme, on top-level keys like amenity=*, leisure=*, tourism=* and highway=*, this scheme is rarely supported, so these extra values will be ignored. However, unlike the semicolon scheme, this does not interfere with at least the first value being recognized.
Cons:
- More verbose than other MV schemes, some mappers find it not as elegant-looking.
- Support by consumers might be lower than for other schemes (?).
Non-standard variants
There are a few variants of this scheme using _1, [1], %1 or simply 1 as a suffix, but they are much less common.
There are still many objects that have tags like name_1=* and alt_name_1=*, that should no longer be used for tagging. They are the result of imports.
"alt" prefix in key
Use two keys, one prepended with "alt_" to give one "alternate value".
- Simple to use and to understand.
- Very common and well supported by consumers for name=*.
- Non prefix-aware consumers just ignore the extra value.
- Much rarer for other tags, likely not supported by consumers.
- Can only encode one extra value.
Ad-hoc schemes
Other MV schemes have been created and documented for specific keys, usually because there are particular requirements. For example, the Lanes scheme is like a two-level semicolon, with well-documented empty-field semantics and used as a namespace.
The well-established Karlsruhe schema predates the widespread use of semicolon value separators; it specifies that multiple addr:housenumber=* values should be delimited by commas rather than semicolons. Other numeric keys like addr:unit=* and grades=* have come to be used this way as well, but semicolons are also commonly used with all three keys.
Relations
While not strictly an MV scheme, the fact that osm objects can belong to multiple relations can effectively give multiple similar attributes to them. For example, a highway=* can belong to multiple Routes.
History
Multiple values in OSM XML
OSM API v0.5 allowed an element to contain multiple <tag> elements with identical k attributes (keys) but different v attributes (values). Few tools supported this capability and it was removed from API v0.6. [1]
iD editor did create numbered suffix key in the past
Prior to Feb 2019, the iD editor used to create numbered suffix keys in a way that can be confusing. Some foo_1=* tags in the database were created accidentally using this feature. If you suspect such a tag in the database was created accidentally, contact the mapper first to make sure.