Schema Documentation

Version: current • Date: August 02, 2026

Sourdough organizes OpenStreetMap data into vector tile layers that closely follow OSM’s own tag structure. Each layer corresponds to a top-level OSM tag (like highway, building, amenity), and the attributes on each feature are taken directly from the value of an OSM tag with the same name.

Geometries

Most feature types in OpenStreetMap can be mapped using multiple geometry types. For example, a parking lot can be mapped as an amenity=parking node, or as a closed way representing an area. A barrier=kerb can be a node (representing a point where a footpath or other highway crosses a kerb), or it can be an way representing a length of kerb (like that separating a sidewalk from a roadway).

Sourdough layers, consequently, may in most cases contain any kind of geometry: Point, LineString, or Polygon (or their Multi- equivalents). For example, the aeroways layer contains points (gates, towers, windsocks), lines (runways, taxiways, parking positions), and polygons (terminals, aprons, and the airport area as a whole).

OSM Nodes are always interpreted as Points; unclosed OSM Ways are always interpreted as LineStrings, and OSM multipolygon Relations are always interpreted as Polygons. However, closed Ways in OSM are ambiguous, and may represent either linear features (like a roundabout) or areas (like a building). Sourdough chooses how to interpret these closed ways based on their tags. When area=yes or area=no is given explicitly, closed ways will be interpreted as Polygons or LineStrings respectively. When no such tag is present (which is quite common), Sourdough chooses how to interpret the way based on its top-level tags. Each layer defines its own behavior in this case: for example, the waterways layer treats ways as lines by default, but treats ways tagged waterway=dam/dock/boatyard/fuel as polygons.

Zoom levels

Any vector tile schema must make decisions about which features to omit at lower zoom levels; otherwise the 0/0/0 tile would contain all of the data in OpenStreetMap and be many gigabytes.

In order to support a wide range of cartographic use cases, Sourdough attempts to include lots of features at each zoom level. Any given map may not actually display all of this data, but it offers flexibility for map makers to highlight different kinds of features.

For point and line features, Sourdough relies on the feature’s tags to decide what zooms to include it at. For example, highway lines appear depending on their highway class, and amenity points appear depending on how “important” they are (libraries and community centers at lower zooms than benches and wastebaskets).

For polygon features, Sourdough includes any feature that is larger than a certain visual size. This means that very large lakes, landuse areas, protected area boundaries, etc will be shown at low zooms. In the event that an area feature is small but has tags which imply that it’s important (e.g. a very small library), it will appear at a lower zoom—the same zoom that it would have appeared at if it were mapped as a node.

Primary and Detail tags

At the lowest zoom level that a feature appears at, only a small subset of tags are included on it, which Sourdough calls the primary tags. Generally, primary tags include the feature’s type, but not its name, access restrictions, physical details, etc. Omitting these details at lower zooms helps reduce tile sizes.

At some higher zoom level, additional tags are added to the feature. These are its detail tags. Sourdough includes lots of details about a feature at higher zooms, so that map makers have lots of inputs to use when styling the feature.

Much like the zoom level that a feature first appears at, the zoom level at which detail tags become available may depend on the feature’s kind, its visual size on screen, or both.

Physical ordering tags

At low zooms, most maps render features in a fixed order based on importance; for example: rendering motorways on top of minor roads, and roads above waterways. But at high zooms, many maps switch to rendering features in a way that reflects their real-world vertical order (so that bridges, tunnels, overpasses, and underpasses are depicted accurately).

To facilitate this, Sourdough defines a set of physical order tags (layer, bridge, tunnel, location, and covered). These tags are included on all features in several tile layers (highways, railways, waterways) beginning at a fixed zoom level (zoom 12), regardless of the feature’s type.

This allows map stylesheet authors to render these features in several passes, in order to show accurate vertical relationships.

Common tags

A small set of detail tags are included on features in every layer. These are: name, ref, alt_name, short_name, official_name, wikidata, wikipedia.

Attribute types

Sourdough processes OSM’s string-valued tags into appropriate data types for vector tiles. Any given OSM tag key is handled identically across all layers that tag is included in. Any given tag (like access or height) is treated consistenty across all layers that it appears in.

The following tags are parsed to integers: admin_level, building:levels, building:levels:underground, capacity, capacity:disabled, layer, level, population.

The following tags are parsed as numeric values with units, and converted to a floating point value in meters: ele, height.

All other tags that are included in Sourdough are kept as strings.

Sidenote: Why no booleans?

Many OSM tags commonly take values "yes" and "no". Sourdough keeps these tag values as strings, rather than converting them to true and false booleans. This is because many of the tags that look like booleans at first glance may actually take more than two values. Examples include seasonal=yes/no/summer/winter, takeaway=yes/no/only, and wheelchair=yes/no/limited. Other tags like fee=yes/no or intermittent=yes/no do not have any other widely accepted values today, but additional values might be created in the future.

Using the strings "yes" and "no" for these boolean-ish attributes does not significantly change the size of the output tiles, because each string in a given layer is only encoded once (even if it is used by multiple features). And in most renderers, it will not significantly affect memory footprint or frame time.

Label points

For area features, Sourdough also includes Points at the centers of those areas. These label points have the same ID and attributes as the area they correspond to, plus the zoom attributes described in the next section. They are meant to help map makers place labels (text, icons, etc) at the center of the area if they wish. Note that map rendering engines such as MapLibre can’t do this client-side, because an area may be split across several tiles and may not all be in view at once, so the client can’t necessarily know where its centroid is.

The zoom at which a label point first appears depends both on the feature’s tags and on its physical size: label points for huge area features appear in the tiles at much lower zooms than those of tiny areas of the same type. See the next section for details.

Zoom attributes: _minzoom and _reczoom

Sourdough deliberately includes many feature types at lower zooms than general purpose maps would want to display them. This supports greater cartographic flexibility. For example, international airports appear at zoom level 6. Most maps won’t want to display airports at such low zooms, but they are available for aviation-specific maps to use. General purpose maps can use a minzoom on the style layer that renders airports to delay their appearance until a higher zoom like 9 or 10.

A constant minzoom works well for some kinds of features, but not all. Consider parks, which come in a wide range of sizes. There isn’t a single fixed zoom level that it makes sense to start labeling parks at; instead the minzoom needs to depend on the size of a given park. Sourdough emits label points for areas when the area reaches a threshold size on screen, which partly addresses this issue (small parks’ label points won’t be present in the tiles until higher zooms). But this alone doesn’t allow map makers to customize the zoom levels that park labels appear at; they are forced to accept Sourdough’s choices as implicit rules.

To solve this, Sourdough includes two attributes on Point features:

• _minzoom which is the actual minimum zoom that the label point appears in the tiles
• _reczoom which is the zoom that Sourdough recommends the label be displayed at for general purpose maps

The underscore prefix indicates that these values are computed by Sourdough and do not correspond to OSM tags. Line and polygon features do not carry these attributes. Both values are computed independently for each feature (a large park will have a lower _reczoom than a tiny one).

Stylesheets can opt into the recommendations with a MapLibre filter expression like this:

[">=", ["zoom"], ["get", "_reczoom"]]

which displays each label starting at its recommended zoom (even though it may be present in lower zoom tiles too). Each style layer can have its own filter expression, and the _reczoom filter above can be combined with other filters using boolean operators to restrict its effect to specific features within a tile layer. Applying a shift to the recommended value, e.g. [">=", ["zoom"], ["+", ["get", "_reczoom"], -1]], makes labels appear earlier or later, thus increasing or decreasing the importance that the map places on these features.

Most feature types have a few zoom levels of headroom for such shifts (the gap between _minzoom and _reczoom). It’s safe to shift by any amount: if the shift is greater than the available headroom, then the effect is clamped (labels will simply appear at the zoom level that the points first appear in the tile). You can combine a _reczoom-based filter with a fixed minzoom (or maxzoom) for the entire layer, in order to define stops above/below which no labels will render.

Note that this filter is only appropriate on style layers that render Point geometries. On a layer that places labels along lines (river names, street names), ["get", "_reczoom"] evaluates to null and the filter rejects every feature.

_reczoom may exceed the tileset’s maximum zoom. MapLibre continues to increase the ["zoom"] expression value past the tileset maxzoom when overzooming, so the filter continues to work. This allows stylesheets to defer labeling tiny features until a very high zoom level, instead of forcing all labels to appear once the tileset max zoom is reached.

The values themselves are editorial judgments and will be tuned over time. In particular, _minzoom may be lowered in future versions to accomodate specal-purpose maps that wish to display specific feature types at unusually low zooms. Using either a _reczoom filter or a fixed minzoom for a style layer whenever possible in your stylesheets will make them more robust against such changes.

Layers

Advertising

The advertising layer contains features from OSM which are tagged advertising=*, including billboards, posters, and other advertising structures.

Attributes:

• Primary: advertising
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, support, lit, operator, visibility, message, sides, animated, luminous, direction

Aerialways

The aerialways layer contains features from OSM which are tagged aerialway=*, including cable cars, gondolas, and chairlifts.

Attributes:

• Primary: aerialway
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, access, aerialway:access, aerialway:capacity, aerialway:duration, aerialway:occupancy, ele, fee, oneway, operator, wheelchair,

Aeroways

The aeroways layer contains features from OSM which are tagged aeroway=*, including airports, runways, taxiways, helipads, and other aviation facilities.

Attributes:

• Primary: aeroway
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, iata, icao, faa, aerodrome:type, military, operator, surface, access, ele, width, direction, navigationaid, holding_position:type

Amenities

The amenities layer contains features from OSM which are tagged amenity=*. This tag covers a broad range of businesses, institutions, and facilities.

Attributes:

• Primary: amenity
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, access, air_conditioning, atm, bicycle_parking, bicycle_rental, booth, branch, brand, capacity, capacity:disabled, changing_table, community_centre, covered, cuisine, denomination, diet:gluten_free, diet:halal, diet:kosher, diet:vegan, diet:vegetarian, dispensing, drive_through, fair_trade, fee, female, fountain, gender_segregated, indoor, indoor_seating, internet_access, layer, level, location, male, organic, outdoor_seating, parking, parking_space, private, recycling:cans, recycling:clothes, recycling:glass, recycling:glass_bottles, recycling:paper, recycling:plastic, recycling:plastic_bottles, recycling:plastic_packaging, recycling_type, religion, reservation, self_service, smoking, social_facility, social_facility:for, surface, takeaway, toilets, toilets:disposal, townhall:type, unisex, vending, waste, wheelchair

Barriers

The barriers layer contains features from OSM which are tagged barrier=*, including fences, walls, gates, and kerbs.

Attributes:

• Primary: barrier, fence_type, wall, kerb
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, material, height, access, wheelchair, tactile_paving

Boundaries

The boundaries layer contains administrative boundaries from OSM relations tagged boundary=administrative, as well as protected areas and other boundary features tagged boundary=*.

Attributes:

• Primary: boundary, admin_level, maritime
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, protected_area, leisure, protection_title, protect_class, operator, ownership, start_date, border_type, place, locality, claimed_by, disputed_by, recognized_by

Buildings

The buildings layer contains features from OSM which are tagged building=*, which represent permanent enclosed structures.

This layer also contains features tagged building:part=* (representing parts of buildings), and features tagged entrance=* (building entrances).

Attributes:

• Primary: building, building:part, entrance
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, height, building:levels, building:levels:underground, building:material, building:colour, roof:shape, roof:material, roof:colour, layer, level

Notes

• Heights are quantized at lower zooms to reduce tile sizes

Clubs

The clubs layer contains features from OSM which are tagged club=*, which is used for places where organized clubs meet.

Attributes:

• Primary: club, sport
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, access, website, phone, operator, wheelchair

Craft

The craft layer contains features from OSM which are tagged craft=*, including workshops, artisan businesses, and manufacturing facilities.

Attributes:

• Primary: craft
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, website, phone, product, operator, level, wheelchair

Education

The education layer contains features from OSM which are tagged education=*, including schools, colleges, and universities.

Attributes:

• Primary: education
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, operator, website, phone, wheelchair, isced:level, education_profile:general, education_level:primary, education_level:secondary, education_level:preschool

Emergency

The emergency layer contains features from OSM which are tagged emergency=*, including fire hydrants, defibrilator stations, emergency phones, etc.

Attributes:

• Primary: emergency
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, operator, access, fire_hydrant:type, fire_hydrant:position, fire_hydrant:diameter, fire_hydrant:pressure, water_source, couplings, colour, description

Geological

The geological layer contains features from OSM which are tagged geological=*, which includes various kinds of geological formations.

Attributes:

• Primary: geological
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, website, height, ele, rock, outcrop:type, start_date

Healthcare

The healthcare layer contains features from OSM which are tagged healthcare=*, including hospitals, clinics, pharmacies, and other medical facilities.

Attributes:

• Primary: healthcare
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, healthcare:speciality, operator, phone, website, wheelchair, emergency

Highways

The highways layer contains features from OSM which are tagged highway=*, including roads, pedestrian paths, and other transportation routes.

This layer also contains features tagged junction=*, which is used to map certain kinds of intersections.

This layer excludes features tagged highway=construction or highway=proposed.

Attributes:

• Primary: highway, expressway, toll, junction, informal
• Detail: name, ref, surface, service, junction, dual_carriageway, motorroad, oneway, operator, website, footway, crossing, crossing:markings, crossing:signals, crossing:signed, crossing:island, tactile_paving, button_operated, segregated, sidewalk, sidewalk:left, sidewalk:right, access, motor_vehicle, bicycle, foot, wheelchair, dog, supervised, lit, smoothness, sac_scale, trail_visibility, mtb, mtb:scale, mtb:scale:imba, layer, bridge, tunnel, location, covered, indoor

Notes

• Connected highway segments with the same attributes are merged
• Surface tags are categorized into paved and unpaved

Historic

The historic layer contains features from OSM which are tagged historic=*, including archaeological sites, monuments, castles, ruins, and other historically significant features.

Attributes:

• Primary: historic
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, access, aircraft:type, amenity, archaeological_site, building, heritage, inscription, material, memorial:type, memorial, model, operator, religion, ruins, start_date, tourism, website

Landcover

The landcover layer contains features from OSM which are tagged landcover=*, representing ground cover and vegetation areas.

Attributes:

• Primary: landcover
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, leaf_type, leaf_cycle, surface, height, wetland

Landuse

The landuse layer contains features from OSM which are tagged landuse=*, representing how land is used for residential, commercial, industrial, agricultural, and other purposes.

Attributes:

• Primary: landuse
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, operator, website, access, residential, industrial, crop, produce, farmland, religion, denomination

Leisure

The leisure layer contains features from OSM which are tagged leisure=*, including parks, sports facilities, recreation areas, and entertainment venues.

This layer also contains features tagged playground=*, which is used to map parts of playgrounds, and golf=*, which is used to map parts of golf courses.

Attributes:

• Primary: leisure, playground, golf
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, sport, access, surface, operator, website, wheelchair, lit, covered, garden:type, swimming_pool

Man Made

The man_made layer contains features from OSM which are tagged man_made=*, including towers, bridges, storage tanks, and other artificial structures.

Attributes:

• Primary: man_made
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, operator, tower:type, tower:construction, surveillance:type, camera:type, height, content, substance, material, utility, location, usage, diameter

Military

The military layer contains features from OSM which are tagged military=*, including military bases, barracks, bunkers, etc.

Attributes:

• Primary: military
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, building, bunker_type, landuse, historic, barrier, ruins, disused, access, operator, military_service, website, location

Natural

The natural layer contains features from OSM which are tagged natural=*, including forests, peaks, cliffs, beaches, etc.

This layer excludes natural=water areas and natural=coastline ways, which are instead handled by the Water layer.

Attributes:

• Primary: natural
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, leaf_type, leaf_cycle, wetland, species, genus, ele, height, circumference, diameter, denotation, protected_area, intermittent, seasonal, tidal, salt, surface, access, operator

Offices

The offices layer contains features from OSM which are tagged office=*, including corporate offices, government offices, NGOs, and other business facilities.

Attributes:

• Primary: office
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, operator, brand, phone, website, email, wheelchair, internet_access, government

Pistes

The pistes layer contains features from OSM which are tagged piste:type=*, including ski runs, cross-country tracks, and other winter sports routes.

Attributes:

• Primary: piste:type
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, piste:difficulty, piste:grooming, piste:name, operator, access, informal, website

Places

The places layer contains features from OSM which are tagged place=*, including countries, states, cities, towns, villages, neighborhoods, and other settlement labels.

Attributes:

• Primary: place, name
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, admin_level, ISO3166-1, capital, population, ele

Notes

• Labels are gridded to ensure a reasonably uniform distribution of labels (preventing too many labels from appearing very close together).
• Labels are also sorted in order of importance, so that client-side label placement can favor more significant places when label text would overlap

Power

The power layer contains features from OSM which are tagged power=*, including power lines, substations, and other electrical infrastructure.

Attributes:

• Primary: power, voltage
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, operator, frequency, cables, circuits, material, design, structure, location, generator:source, generator:method, generator:type, generator:output:electricity, plant:source, plant:method, plant:output:electricity

Public Transport

The public_transport layer contains features from OSM which are tagged public_transport=*, including stations, platforms, and other public transportation infrastructure.

Attributes:

• Primary: public_transport
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, bus, train, tram, trolleybus, light_rail, subway, station, highway, railway, network, operator, shelter, bench, bin, covered, lit, tactile_paving, wheelchair, departures_board, passenger_information_display, surface, network:wikidata

Railways

The railways layer contains features from OSM which are tagged railway=*, including train, tram, and subway tracks, and other rail infrastructure.

Attributes:

• Primary: railway, service, usage
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, operator, gauge, electrified, frequency, voltage, maxspeed, railway:track_ref, public_transport, station, train, subway, tram, bridge, tunnel, layer

Routes

The routes layer contains route relations from OSM, which are used to represent named regular lines of travel. This includes highways (i.e. long distance major roads), train, subway, bus, and ferry routes, and named hiking, biking, and ski routes.

Attributes:

• Primary: route, type
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, network, operator, colour, distance, ascent, descent, roundtrip, symbol, osmc:symbol, from, to, via

Shops

The shops layer contains features from OSM which are tagged shop=*, representing places that sell retail goods.

Attributes:

• Primary: shop
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, access, wheelchair, toilets, brand, operator, beauty, clothes, male, female, unisex, level, indoor, cuisine, diet:vegetarian, diet:vegan, diet:halal, diet:kosher, diet:gluten_free, fair_trade, organic, second_hand, self_service, service:bicycle:pump, service:bicycle:repair, service:bicycle:retail, service:vehicle:car_repair, service:vehicle:tyres, trade, sport, pet

Tourism

The tourism layer contains features from OSM which are tagged tourism=*, including hotels, museums, theme parks, campgrounds, viewpoints, and other tourist-oriented facilities.

This layer also contains features tagged attraction=*, which is used to map attractions at theme parks, water parks, and zoos.

Attributes:

• Primary: tourism, attraction
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, attraction, museum, artwork_type, artist_name, information, board_type, board:title, access, wheelchair, level, toilets, fee, brand, operator, website, zoo

Water

The water layer contains areas in OSM tagged natural=water, as well as ocean polygons derived from preprocessed coastline data.

In OSM, the oceans are not modeled as polygons, because they would be too huge for editing software to work with. Instead, the coastlines are mapped short segments tagged natural=coastline. The OSMCoastline tool can be used to postprocess OSM data and reconstruct the oceans by joining all of these coastlines together.

In Sourdough, this reconstructed ocean polygon is represented in the tiles as if it were a huge multipolygon in OSM tagged natural=water + water=ocean + salt=yes.

Attributes:

• Primary: water, intermittent, seasonal
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, layer, salt, tidal, basin, boat, motorboat, canoe, swimming, fishing

Waterways

The waterways layer contains features from OSM which are tagged waterway=*, including rivers, streams, and canals, as well as waterfalls and water-related infrastructure like dams and locks.

Attributes:

• Primary: waterway
• Detail: name, ref, alt_name, short_name, official_name, wikidata, wikipedia, usage, layer, bridge, tunnel, location, intermittent, seasonal, tidal, material, height, boat, motorboat, canoe, swimming, fishing