Multiple values

From OpenStreetMap Wiki
Jump to navigation Jump to search

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

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

Multiple keys, appending "_1", "_2", etc to the key to encode separate values where used. There are variants of this scheme using [1] 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 (?).
  • The suffixed tags name_1=* and alt_name_1=* should no longer be used for tagging. They are the result of imports and were not defined very well.

"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. Or seamark attributes (such as lights) and parking lanes which use numbered subkeys such as *:2=*.

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.


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.


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.

See also