Key:layer

The layer=* tag is one of several methods used to describe vertical relationships between crossing or overlapping features. The vertical ordering established by the layer values is valid exactly only in the precise location (not marked by a node) where the ways cross or objects overlap.

Joining the ways with a shared node at the point where they cross would destroy the vertical order established by layer.

Layer is not suitable to define vertical relationships of adjoining, nearby or distant elements or areas. Applying it to long ways however will unpredictably affect (usually break) intersections far outside the visible editing area.

Numerical values between -5 and 5 are generally used; 0 should not be used explicitly.

Ways passing above other ways on a bridge will have a higher layer value, ways passing in tunnels below other ways will have lower (typically negative) values. All ways without an explicit value are assumed to have layer 0.

Usually layer=* on ways should be used in combination with one of tunnel=*, bridge=*, highway=steps, highway=elevator, covered=* or indoor=yes. For areas, it could be used in combination with tags such as man_made=bridge, special types of building=* and similar.

Ways in buildings (or similar structures like multi-level parking lots, shopping centers, airports, railway stations, some multi-level bridges and roads...) should be mostly described with level=* instead of layer. level=* is used for the physical vertical arrangement of levels (floors, walkways) inside structures. Use level:ref=* for the human readable signage used to identify physical levels (eg elevator buttons, multistory parkade levels).

Layer provides absolutely no information about relative or absolute height difference of objects which do not immediately cross or overlap. A change in layer should not be used to indicate a change in elevation. A bridge is at layer 1 even if it is only several feet above sea level while the peak of Mount Everest is at layer 0 even though it is 8848 meters above sea level.

Negative values do not imply that object is underground, use location=underground for this purpose.

ele=* can be used to indicate elevation above sea level.

Several other tags can establish or modify vertical relationships explicitly or by built-in assumptions. Some of those are level=*, location=*, covered=*, highway=steps, aerialway=*, power=line, waterway=dam

Guidelines

Here are the main guidelines:

• Features at layer 0 should not normally have a layer tag.
• Do not use layer=-1 to hide warnings about crossing or overlapping ways. Either fix them properly or leave the easily visible warning so that others can fix them.
• If a waterway is visible on the satellite image it is most likely not layer=-1.
• Tag shortest possible/practical sections of ways. Long viaducts and tunnels can be tagged with a suitable single value for their entire length for simplicity although it may sometimes be better to adjust the layer along its length to accommodate more complicated crossings.
• Use the smallest suitable layer value. Only use layer=2 for a bridge that passes over a feature that is already at level 1; similarly only use layer=-2 for a tunnel that passes below another tunnel. For convenience some higher values are often locally used/reserved for very long bridges or underground networks where it is assumed that they are above/below most other crossings/objects in the area.
• When ways are passing on different levels apply layer=* only to the way which also has the bridge/tunnel attribute. Only ways with one of the tags/attributes tunnel=*, bridge=*, highway=steps, highway=elevator, covered=* should be tagged with the layer tag, similar for railways and waterways.
• Within complex junctions it is often necessary to break ways to change the layer and thereby ensure that the vertical arrangement of intersections is accurately described.
• Rivers and streams should not be tagged with layer -1 along long sections of their length, crossings should be tagged like other crossings with bridges, tunnels and layer. Waterways that are covered may be tagged with covered=yes and are generally rendered as if they flow underneath built features. Where a highway is at the same level as a waterway, you can add ford=*.
• Power lines (power=line) do not normally need to be tagged with a layer and are assumed to float above all other features unless a layer value is used to indicate otherwise. The location=overhead can be used and layer=* may be used for example when two power lines cross.
• Some other features like man_made=pipelines can also be appropriately tagged by using location=overhead, location=overground or location=underground instead of layer=*. This simply indicates that they are in the air or buried, without providing any actual relative height information which is frequently not easily available for buried pipelines. layer=* is still needed for example when two pipelines lines cross where the information is known or where pipeline goes over/under road.
• Although some map rendering and quality assurance services assume that bridges and tunnels are at layers +1 and -1 respectively, it is better to explicitly state the layer for all bridges and tunnels.

Note that there can be some ambiguity about whether a particular crossing should be tagged as a bridge or as a tunnel, particularly where the distance under the upper way is long. In general the way through a tunnel tends to be longer and darker, whereas the way under a bridge tends to be shorter and less dark. The GDF standard uses the term 'brunnel' to cover both features.

Things to avoid

Here are some common examples of how not to use the layer tag:

• Landuses, such as parks and woods should not normally be tagged with a layer and data consumers may freely ignore such layer tags. The exception to this rule is where a landuse is indeed above another landuse.
• Roads, railways, waterways etc. should not be tagged with a layer just because they are raised up on an embankment or are in a cutting - use embankment=* and cutting=*, respective waterway=ditch for this purpose.
• Beware that the combination of layer on a way crossing areas with a different layer is not defined in many cases and likely to cause unforeseeable effects. As an example, a road or a river which is tagged with layer=-1 may not be rendered when crossing a landuse=forest with an implicit layer=0 tag - rendering will be inconsistent between different renderers. Such combinations are only defined when used with additional tags such as bridge or tunnel.
• An island (place=island) in a lake (natural=water) should not be tagged as layer=1, nor should a clearing in a wood (clearing in a wood is not hovering above trees). To ensure that the island or clearing renders properly use multipolygon.
• Floors within a building should be tagged with level=* rather than layer.
• Rivers and streams should not be tagged with layer -1 along their entire length or long sections as it makes harder to detect missing bridges for roads passing over waterways.
  • Obviously, long culverts are still fine to be marked with layer=-1 tunnel=culvert
• Positive values do not need a '+' sign. Use 'layer=1' rather than 'layer=+1'.
• Using negative values to describe something to be underground. Use location=underground for this purpose.

Examples

Layers used well for an interchange and for railways	This layers view of Washington using ITO Map shows how elements are correctly organised with elements that pass over other elements using layer 1 (red) unless it is necessary for them to to use layer 2 (orange). Some elements are using layers -1 or -2 as appropriate.
Layers used well for an interchange	This is an example of layers displayed in the editor JOSM with the additional mappaint style Layer checker.
Confusing use of layers along a canal and railway	This view of the Grand Union canal in the UK shows incorrect use of layers. The canal switches from surface (no layer) to layer -1 (dark blue) to layer 2 (orange) for no reason. Bridges and tunnels are using higher layer numbers than necessary and some don't have layers at all. A point where a stream and footpath pass under the canal in a tunnel are shown at the same layer as the canal (layer -1 as it happens). A car park and collection of tracks in the village are shown at layer=-1 - no layer tag is needed given that they are neither below nor above other mapped objects.
	Layer tags used incorrectly for woods and a golf course. The woods are on layer 2, a golf course on layer -1 and a common on layer -2. These features are all at ground level and will render correctly without layering.

Data consumers

For technical reasons renderers typically give the layer tag the least weight of all considerations when determining how to draw features.

A 2D renderer could establish a 3D model of features, filter them by relevance and visually compose the result according to 3D ordering and rendering priorities. layer=* does only affect the 3D model and should have no influence whatsoever on relevance filtering and rendering priorities (visibility).

The 3D modeling is mostly determined by the natural (common sense) vertical ordering of features in combination with layer and level tags approximately in this order:

• natural/common sense ordering: (location=underground, tunnel) under (landcover, landuse, natural) under waterways under (highway, railway) under (man_made, building) under (bridge, location=overground, location=overhead)
• layer tag value:
  • layer can only "overrule" the natural ordering of features within one particular group but not place for example a river or landuse above a bridge or an aerialway (exception: use in indoor mapping or with location tag)
  • layer tags on "natural features" are frequently completely ignored
• level tag value: considered together with layer - layer models the gross placement of man made objects while level is for features within such objects.

Examples

• this bridge (data attached to josm ticket) was drawn correctly despite having layer=-1 while the waterway and riverbanks have an implicit layer=0. The error was meanwhile fixed and JOSM validator improved to spot such situations.

See also

• location=*
• bridge=*
• tunnel=*
• covered=*
• ele=*
• Layer
• Level
• abandoned Proposed_features/layer_change (A tag to help renderers avoid artefacts when layers change, thus making it easier for them to respect the layer tag)
• rejected proposal for default layer values for bridges and tunnels: Proposed_features/default layer for bridge and tunnel
• The JOSM Mappaint style Layer checker