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.
- 1 When (not) to use multiple values
- 2 How to tag multiple values
- 3 Gotchas
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.
Use only one key, and separate values with a ;.
- Very little extra typing needed.
- Reasonably easy to read.
- Fairly well supported by consumers for some keys, like ref=*.
- 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 consumers are likely to behave badly when encountering semicolon values.
- Semicolon-aware consumers need to maintain a whitelist of keys which ought may use semicolons.
Numbered suffix in key
Currently, the iD Editor automatically suffixes tags that are entered twice in the raw tag editor. Please watch out for this when saving your edit.
Multiple keys, appending "_1", "_2", etc to the keys to encode separate values where used. There are variants of this scheme using  or %1 or :1 or simply 1 as a suffix, but they are much less common.
- Reasonably easy to read.
- No issue with literal separators in value or with a character limit
- 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).
- More verbose than other MV schemes, not as elegant-looking.
- Support by consumers might be lower than for other schemes (?).
"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.
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. Or the Seamark_Attributes which are like a numbered suffix that uses : as a separator and where an order is important.
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.
iD editor accidentally creates numbered suffix key
The iD editor currently creates numbered suffix keys in a way that can be confusing. Some foo_1=* tags in the database were created accidentally using this feature. Watch out for it if you are using iD's raw tag editor. If you suspect a foo_1=* tag in the db was created accidentally, contact the mapper first to make sure.
- This doesn't happened anymore since Feb. 2019, see here.