Any tags you like
Note: Many general interest features are already on Map Features and it is recommended to use the tagging given there. Otherwise other users might eventually convert your contributions to fit that scheme.
So you've 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 you'd just create a page endangered_nest=Siberian_flying_squirrel and document on that page what it's 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'd 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:
- Your feature is of general interest, or
- You are unsure how to model it, or
- The latest proposed form for tagging it has been rejected, or
- You want to change the meaning of a tag already in use
(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.
E.g., adding the location of a WLAN hotspots 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 practice page regarding verifiability. Do not map historic, temporary or hypothetical features, opinionated data like ratings, or legislation.
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!
The strings chosen for the key part have some conventional forms:
- Ideally, a key is one word, in lowercase.
- 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 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:
- 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!
- 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.
- Qualifications by language code. See Names#Localization
- Relatively uncommon. Pattern 2, but done in a generative manner where sub-parts refer to other defined keys. This is almost meta-tagging. Almost.
The value part of tag is a string which also follows some conventions. Obviously the value is taken together with the key and to large extent the format and conventions of a value with depend on which key it is put with.
- A tag can be either a category (like highway) or a property (like width). Properties can take any number (perhaps infinite) possible values, or can be numeric (e.g. width=2), categories often take values which further refine the categorisation (e.g. highway=motorway).
- Names are an example of a property value (The obvious example being the name=* tag), and these values are clearly very unstructured and flexible strings, commonly containing mixed case, spaces, and all manner of other special characters.
- For category tags (rather than properties), the value follows formatting conventions similar to the basic rules of keys:
- Ideally, a value on a category tag is one word, in lowercase.
- When that can't be the case, a value on a category tag should be one concept, whose words are underscore_separated.
- Values may be separated into multiple values for some but not all keys by separating the string with semicolons. Keys which permit this sort of interpretation are individually documented on the Wiki. See Semi-colon value separator.
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:
You can use any Unicode characters (UTF-8) as you like. In practice, most keys (such as highway) and classification values (such as trunk_link) uses lower case chars, underscores and colons. It's a good idea to avoid characters that will cause trouble in various software for these strings:
- Whitespace You should 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
- = Because its 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.
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("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.