Any tags you like

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.

Contents 1 Documenting tags not in Map Features 2 When to create a proposal 3 What not to map 4 Syntactic conventions for new tags 5 Characters 6 Style Guide?

Documenting tags not in Map Features

So you've followed good practice and searched the 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. (See New Features.)

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'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:

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

(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. So adding WLAN hotspots in the form of the location of the base station is viewed acceptable but tagging (every) node around it with the perceived signal level at those points is viewed unwanted by some and information better stored in your own service; but nothing's stopping you, though.

Syntactic conventions for 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.
• The value part 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, but in general those keys whose potential values are mostly drawn from a documented set of underscore_separated_lowercase_strings are more likely to permit this kind of interpretation.
• The strings chosen for the key part have some conventional forms too:
  • Ideally, a key is one word, in lowercase. It can be either a category (like highway) or a property (like width). Properties take value keys (e.g. width=2), categories often take keys which further refine the categorisation (e.g. highway=motorway).
  • 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 guys also tend to be programmers and like the syntax.
  • Some more complex keys are build 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!
       • tiger:county=*, tiger:upload_uuid=* - all to do with US TIGER data uploads
       • KSJ2:lat=*, KSJ2:curve_id=* - tags from the Japan KSJ2 import
    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.
       • name:left=*, name:right=* - streets with different names on different sides (w.r.t. way direction arrow?)
       • addr:housenumber=*, addr:street=* - all related to a place's address
    3. Qualifications by language code.
       • 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.
       • source:name=* - the source for the the name tag is ...
       • source:ref=* - the source for the the ref tag is ...
• 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:

highway=crossing

crossing=uncontrolled

Characters

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) uses any characters you can think of.

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.