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
- 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.
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!
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
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 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.
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).
- 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.
- Sometimes the semicolon ";" is interpreted as multi-value separator - see Semi-colon value separator.
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:
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 ASCII 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. Avoid whitespace at the beginning and end of values.
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.