Any tags you like

From OpenStreetMap Wiki
Jump to navigation Jump to search

Feel free to invent new tags! If you want to mark something that is verifiable and mappable in OpenStreetMap but there is no existing tagging scheme for that, you can invent and use new tags. Even tags that are nowadays popular were at some point used for the first time, very often without going through proposal process.

However, this does not mean "feel free to ignore existing tagging schemes and start marking pharmacies with unicorn=parking_lot". Also, it is not OK to use wrong tagging for the renderer – do not misuse well-established tags just to force some behaviour in some data consumer. And of course, unilaterally changing the definition of existing tags or keys is not OK, so be careful when inventing a new value for an existing key.

Note that most general-interest features are already established map features and it is recommended to use the tagging given there. Otherwise, other users might eventually convert your contributions to fit that scheme.

Documenting tags not in Map Features

Main article: Creating a page describing key or value

So you have followed good practice and searched the Wiki, map features, proposed features, rejected features, proposed relations and mailing lists' archives and still can't find a tag for what you'd like to map? Taginfo is probably the most useful repository of tagging suggestions. It lists tags actually used in the database, and how often they have been used. It also lists other tags which have been used in combination with any particular tag on a single object.

Remember that OpenStreetMap does not have any content restrictions on tags that can be assigned to nodes, ways or areas. You can use any tags you like, but please document them here on the OpenStreetMap wiki, even if self-explanatory. Documenting allows others to find your features or even to correct mapping errors they encounter near you.

Documenting is especially useful later on, if someone proposes a tagging for the superset of the feature you've been adding. Then your experiences and features can be incorporated into that proposal process, and in the far out case even be converted to the new scheme, if accepted.

Choosing tags to use

For example, if you wanted to map all nests of the endangered  Siberian flying squirrel you'd just create a page endangered_nest=Siberian_flying_squirrel and document on that page what it is used for. Just be prepared that someone else might later propose a different and more structured scheme for documenting other aspects of endangered species lives, a tagging that allows to document findings of their droppings, too – a case used to protect areas from any construction – and you would end up converting your old entries.

You can consult, for example, the IOF standards for classification standards used in orienteering maps, to see if those are of any help and if your new tag could be compatible with (those) users' needs. Other similar documents are likely to exist.

When to create a proposal

You should create a proposal for your feature, if:

  1. Your feature is of general interest, or
  2. You are unsure how to model it, or
  3. The latest proposed form for tagging it has been rejected, or
  4. You want to change the meaning of a tag already in use
  5. You want to gather feedback from fellow mappers, including people from different regions

(Note that creating a proposal is neither a requirement for your feature to appear on the main map, nor is a successful proposal process a guaranteed way to get your feature onto the main map. However, if your feature has been through the proposal process and was accepted by a majority, you will of course have many more people asking for the feature to be shown, thus enhancing the chances of the feature being rendered on the main maps.)

What not to map

Entities in the OpenStreetMap database should relate to some geographical property or object with geographical qualities. For example, adding the location of a WLAN hotspot base station is considered acceptable, but tagging many nodes around it with the perceived signal levels is unwanted. Such information is better stored in a separate service.

Please consider community consensus documented on the good practices page regarding verifiability. Do not map historic, temporary or hypothetical features, opinionated data like ratings, or legislation.

Note limitations on mapping private information.

How to name new tags

This is an attempt to document the existing conventions used by people inventing new tags, based on current map features tags and recent proposals. Corrections and extra forms people have seen in widespread use will be happily accepted!

A tag is a software-mandated (key, value) pair of Unicode strings, often written down as key=value in discussion.

Depending if what you want fits into some already defined category you may define a new main key, a new value for an existing key, a new property modifying one or more key/value combinations or a new method of refinement.

If in doubt whether to define something entirely new or use some existing combination with new properties or refinements consider:

  • new properties should not modify established features in ways that would contradict common sense expectation of them
  • unless this is a very specific definition, with cultural and geographical bounds that would not make sense in another country, try to have an eye towards a world-wide view (not Europe-centric, not Britain-centric, not US-centric...) to prevent the tag from becoming skunked.

Syntactic conventions for new tags

The strings chosen for the key part have some conventional forms:

  • Ideally, a key is one word, in lowercase, using British English if possible.
  • When that can't be the case, a key should be one concept, whose words are underscore_separated. This avoids some whitespace issues, and has generally come about because OSM people also tend to be programmers and like the syntax.
  • Some characters have special meaning in various context and using these characters in keys will likely cause all sorts of issues. The following characters are among ones discouraged to be used in keys: =, +, /, &, <, > ;, ', ", ?, %, #, @, \, . and ,.
  • It is preferable to avoid also whitespace as character in the key (spaces, enters, tabs and so on), and other weird characters like non printable characters
  • Some more complex keys are built from multiple words or concepts separated by colons. These should be readable naturally from left to right; a handful of patterns are in widespread use already:
    1. Simple namespace prefixing, in a style similar to some programming languages. Bundles loosely-related information together in a way that doesn't clash with other OSM tags. Ideal for data imports from other sources!
    2. Bundles of tightly-related information, which together express a single fact consisting of several fields. Almost property-like. Great for addresses and unusual naming patterns.
    3. Qualifications by language code. See Names#Localization
      • name:en=*, name:cy=* - the English and Welsh names for a feature
      • note:ja=* - a note specifically in Japanese
    4. Relatively uncommon. Pattern 2, but done in a generative manner where sub-parts refer to other defined keys. This is almost meta-tagging. Almost.

Syntactic conventions for new values

The format and conventions depend on whether the tag represents a feature or a property.

  • A tag can represent either a separate feature (like highway) or a property of a feature (like width).
  • Properties can have a large number of possible values, or can be numeric (e.g. width=2) or can have short list of valid values.
    • Names are an example of a property value (e.g. the name=* tag), and these values are unstructured and flexible, commonly containing mixed case, spaces, and other special characters.
  • Features often take values which further refine the category of map feature (e.g. highway=motorway).
    • For feature tags, the value follows formatting conventions similar those used for keys:
    • Ideally, the value of a feature tag is one word, in lowercase, using British English if possible.
    • When that can't be the case, the value of a feature tag should be one concept, whose words are underscore_separated.

Refinement and namespaces

There's a common pattern of iterative refinement in use in many tagging schemes, which has the advantage that the scheme can grow over time to be more and more descriptive whilst still being backwards-compatible:

office=government
government=emergency

Beware of conflicts with other tagging schemes when following this pattern. Refinement can be also done by the means using namespaces.

Characters

The database will accept any Unicode characters (UTF-8) for keys and values. However, the best practice is for keys (such as highway) and classification values (such as trunk_link) to use lowercase ASCII chars, underscores and colons. It's a good idea to avoid characters that will cause trouble in various software for these strings:

  • Whitespace  : Use underscores '_' instead of whitespace, avoid whitespace at the beginning and end of keys;
  • <>&/+?#%'"\ : Special characters in XML, HTML and/or URLs or used for quoting should be avoided;
  • =  : Since it is used in many places as the separation character between tag key and tag value, avoid the equal sign;
  • ;  : The usage of semicolons is under discussion.

Free form values (e.g. as used for the name key) use any characters you can think of. Avoid whitespace at the beginning and end of values.

Style Guide?

You can treat this as a style guide if you like, but really it isn't. Ultimately the interpretation is up to the user, and the only principle really applies is  KISS ("Keep It Simple, Silly"), or alternatively, "Do the Simplest Thing that could Possibly Work". The cleaner and the simpler the better if you want more people to adopt your tag/proposal.

See also