Order of key parts

From OpenStreetMap Wiki
Jump to navigation Jump to search

Each key can (potentially) have various different prefixes and suffixes as well as sub-keys.

The order of these was never really documented, but Taginfo shows that there is one clear order of key parts. This page is the first attempt to provide an overview of the actually used structure of keys.

The major number of keys that are in use right now adheres to the order presented below. There are a few exceptions from these (see the section below for examples), but these are comparatively rare.

Note that this page is an attempt to provide a summary of existing trends and is not some law that must be obeyed.

Summary

[Meta] [Lifecycle] [External] [Key] [Country] [Side] [TransportMode] [Subkey] [Language] [Generic] [Lanes] [Direction] [Condition] [Along] [Date]

It is obvious that most keys are not compatible with most of these parts (e.g. "building:forward" is nonsensical) and cases with more than 3 or 4 parts in the same key are very rare.


Key parts

The different parts in detail

Name Part of key Link Description
Meta source: / note: / check_date: / ... -- a meta namespace used to describe a tag itself, e.g. source:name=* or check_date:opening_hours=*
Lifecycle was: / razed: / planned: / temporary / ... Lifecycle Prefix a prefix describing the current status of the object
External tiger: / naptan: / ... -- some imports used namespaces for their data, most notable the infamous tiger:*=* import in the US
Key key -- the actual main key
Country :GB / :FR -- the country - used e.g. for national ref=* numbers like ref:FR:FANTOIR=*
Side :left / :right / :both Left and right the side of a way the feature applies to
TransportMode :hgv / :bicycle / ... Transportation mode the transportation mode or vehicle type the tag applies to
Sub-key subkey / subkey:subsubkey -- a sub-key, e.g. describing one feature of the main key, potentially several of them in a row
Language :en / :fr / ... Multilingual names the language, e.g. for a foreign name, possibly enhanced with a script name like "sr-Latn"
Generic :url / :signed / :wikidata / :end_date / ... -- some sub-keys can be used in a generic way to add external references like a URL or a Wikidata entry
Lanes :lanes Lanes if the tag applies to one of several lanes only
Direction :forward / :backward / :both_ways Forward and backward if the tag applies to one direction of travel only
Condition :conditional Conditionals if the tag applies only under certain conditions (e.g. bad weather or a certain weight)
Along :start / :end Start and end if the value of the tag changes from the start to the end of way (e.g. the width)
Date :2021 / ... Date namespace the proposed date suffix to tag the time a tag was valid, e.g. name:1945-1990=*

Conventions

  • Some keys are generally referred to as using a namespace in their notation. These should be treated as a pair of key and subkey when reading the table above.
    Examples are sidewalk:surface=*, piste:grooming=*, seamark:light=*.

Further examples of key parts

Especially the 'Meta', 'Generic' and 'External' parts of a key are open lists that miss an overview page in the Wiki and can be extended as necessary. Here are a few more examples that didn't fit into the table:

... t.b.d. ...


Examples of usage


Known exceptions

  • destination=* on roads and signs uses an additional sub-key ':lang' instead of adding the language code directly, e.g. destination:lang:en=*. This does not apply to destination=* on waterways.
  • cycleway:protection is proposed to use two "side" suffixes in one key, e.g. cycleway:right:protection:left=* to describe that the cycleway on the right-hand side of the road is protected on its left side.
  • There are a few thousand tags that use check_date=*, source=* or note=* as suffix instead of prefix, but these are rather uncommon in terms of users actually adding them. surface:note=* used by StreetComplete is likely the most active, see also Proposed features/:note suffix
  • On boundaries there are some tags like left:country=* that use 'left' and 'right' as a prefix in front of the main key.
  • A few keys use lanes=* as a subkey (as opposed to the :lanes suffix). For example, there is piste:lanes=* to mark the number of lanes available.
  • Some of the historic railway=* keys seem to use their own order of parts, e.g. after a mass-edit in France start_date:railway=* exists more often than the conformal railway:start_date=*
  • The seamark:light=* namespace has the fairly unique feature to use number indexing to indicate properties of different parts of the same object
  • There are a few tagging schemes that were invented in the early days of OSM and predate many of the suffixes used today. These have their own keys that would look different if the scheme above had been used (a meanwhile deprecated example: parking:lane:right:capacity:free:hourly:Sa:winter=*).
  • The position of the "Date" field is not consistently used between different keys. For example old_name:-1848:etymology:wikidata=* is in use but doesn't fit the rule that the date comes last.

Words of caution

  • It might be tempting to be as specific as possible with every tag one adds. In reality, this is usually a bad idea: The simpler and shorter a key is, the higher the probability that some user, app or map is actually making use of this information and can display it when appropriate.
  • In case you're unsure about the actual key to use, please consult OSM Wiki and visit taginfo.openstreetmap.org. Enter parts of the key you intend to add into the search and see what is already in use. Documented tagging should always have priority over actual tag use and general rules as shown on this page.
  • All keys and subkeys and combinations of them should be explicitly documented. In general, an undocumented combination of two documented keys is unlikely to be understood and used by any application.
  • Very few keys allow for adding arbitrary subkeys, most noteably ref:XYZ=* to tag reference numbers given by different entities