Map block (v2)

A format-v2 map block (version: 2): the same capabilities as v1, split into a style: half (everything that erases to a MapLibre style.json) and a runtime: half (everything that degrades). Source and layer spec bodies are the v1 ones; their live-data and experience keys move under a nested runtime:. For the why, see Format v2.

`version`

Type: 2 · Required

Format version — v2 documents state version: 2

`type`

Type: "map" · Required

Block type

`id`

Type: string · Required

Unique block identifier

`style`

Type: object · Required

The style half — everything that erases to style.json

`basemap`

Path: style.basemap · Type: string (URL) | any

Base style URL or inline style object (v2 rename of v1 mapStyle)

`center`

Path: style.center · Type: [number, number]

Map center [longitude, latitude]

`zoom`

Path: style.zoom · Type: number · Range: 0 to 24

Zoom level (0-24)

`pitch`

Path: style.pitch · Type: number · Default: 0 · Range: 0 to 85

Camera pitch angle (0-85)

`bearing`

Path: style.bearing · Type: number · Default: 0 · Range: -180 to 180

Camera bearing (-180-180)

`metadata`

Path: style.metadata · Type: map of any

Style metadata (style-spec root metadata slot)

`state`

Path: style.state · Type: map of object

Spec-native runtime-tunable values, read via global-state

Same shape as state.

`images`

Path: style.images · Type: map of string | object

Named images for symbol layers and patterns — style half, merged into the sprite on export

Same shape as images.

`terrain`

Path: style.terrain · Type: object

3D terrain from a raster-dem source — style half, compiles to style.json terrain

Same shape as terrain.

`sky`

Path: style.sky · Type: object

Sky, fog, and globe atmosphere — style half, compiles to style.json sky

Same shape as sky.

`projection`

Path: style.projection · Type: object

Map projection (globe needs maplibre-gl >= 5) — style half, compiles to style.json projection

Same shape as projection.

`light`

Path: style.light · Type: object

The style-spec light shading fill-extrusion faces — style half, compiles to style.json light

Same shape as light.

`sources`

Path: style.sources · Type: map of object

Map sources, each with an optional nested runtime:

`<source-id>`

Path: style.sources.<source-id> · Type: object

One of 6 variants, selected by type: geojson, vector, raster, raster-dem, image, video.

`type: geojson`

`type`

Path: style.sources.<source-id>.type · Type: "geojson" · Required

Source type

`url`

Path: style.sources.<source-id>.url · Type: string · Pattern: ^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/|\.\.?\/)

URL to fetch GeoJSON data

`data`

Path: style.sources.<source-id>.data · Type: GeoJSON

Inline GeoJSON object

`cluster`

Path: style.sources.<source-id>.cluster · Type: boolean

Enable point clustering

`clusterRadius`

Path: style.sources.<source-id>.clusterRadius · Type: integer · Minimum: 0

Cluster radius in pixels (default: 50)

`clusterMaxZoom`

Path: style.sources.<source-id>.clusterMaxZoom · Type: number · Range: 0 to 24

Maximum zoom level to cluster points

`clusterMinPoints`

Path: style.sources.<source-id>.clusterMinPoints · Type: integer · Minimum: 2

Minimum points to form a cluster

`clusterProperties`

Path: style.sources.<source-id>.clusterProperties · Type: map of any

Aggregate cluster properties

`tolerance`

Path: style.sources.<source-id>.tolerance · Type: number

Douglas-Peucker simplification tolerance (higher = simpler geometry)

`buffer`

Path: style.sources.<source-id>.buffer · Type: number

Tile buffer size on each side, in pixels at tile scale

`lineMetrics`

Path: style.sources.<source-id>.lineMetrics · Type: boolean

Calculate line distance metrics (required for line-gradient)

`generateId`

Path: style.sources.<source-id>.generateId · Type: boolean

Assign feature ids from each feature’s index (enables feature-state)

`promoteId`

Path: style.sources.<source-id>.promoteId · Type: string | map of string

Feature property to use as the feature id (for feature-state), or a map of source-layer name to property name

`attribution`

Path: style.sources.<source-id>.attribution · Type: string

Attribution text

`runtime`

Path: style.sources.<source-id>.runtime · Type: object · Default: {}

Per-source live-data configuration

`refresh`

Path: style.sources.<source-id>.runtime.refresh · Type: object

Polling refresh configuration

Same shape as sources.<source-id>.refresh (type: geojson).

`stream`

Path: style.sources.<source-id>.runtime.stream · Type: object

WebSocket/SSE streaming configuration

Same shape as sources.<source-id>.stream (type: geojson).

`cache`

Path: style.sources.<source-id>.runtime.cache · Type: object

Cache configuration

Same shape as sources.<source-id>.cache (type: geojson).

`loading`

Path: style.sources.<source-id>.runtime.loading · Type: object

Loading UI configuration

Same shape as sources.<source-id>.loading (type: geojson).

`prefetchedData`

Path: style.sources.<source-id>.runtime.prefetchedData · Type: GeoJSON

Pre-fetched inline GeoJSON from build time

`fetchStrategy`

Path: style.sources.<source-id>.runtime.fetchStrategy · Type: "runtime" | "build" | "hybrid" · Default: "runtime"

When to fetch data: runtime (default), build, or hybrid

`type: vector`

`type`

Path: style.sources.<source-id>.type · Type: "vector" · Required

Source type

`url`

Path: style.sources.<source-id>.url · Type: string · Pattern: ^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/|\.\.?\/)

TileJSON URL

`tiles`

Path: style.sources.<source-id>.tiles · Type: string[]

Tile URL template array

`minzoom`

Path: style.sources.<source-id>.minzoom · Type: number · Range: 0 to 24

Minimum zoom level

`maxzoom`

Path: style.sources.<source-id>.maxzoom · Type: number · Range: 0 to 24

Maximum zoom level

`bounds`

Path: style.sources.<source-id>.bounds · Type: [number, number, number, number]

Bounding box [west, south, east, north]

`scheme`

Path: style.sources.<source-id>.scheme · Type: "xyz" | "tms"

Tile coordinate scheme

`attribution`

Path: style.sources.<source-id>.attribution · Type: string

Attribution text

`promoteId`

Path: style.sources.<source-id>.promoteId · Type: string | map of string

Feature property to use as the feature id (for feature-state), or a map of source-layer name to property name

`volatile`

Path: style.sources.<source-id>.volatile · Type: boolean

Skip the tile cache (MapLibre volatile); for frequently changing tiles

`runtime`

Path: style.sources.<source-id>.runtime · Type: object

Per-source live-data configuration

`refresh`

Path: style.sources.<source-id>.runtime.refresh · Type: object

Polling refresh configuration

Same shape as sources.<source-id>.refresh (type: geojson).

`stream`

Path: style.sources.<source-id>.runtime.stream · Type: object

WebSocket/SSE streaming configuration

Same shape as sources.<source-id>.stream (type: geojson).

`cache`

Path: style.sources.<source-id>.runtime.cache · Type: object

Cache configuration

Same shape as sources.<source-id>.cache (type: geojson).

`loading`

Path: style.sources.<source-id>.runtime.loading · Type: object

Loading UI configuration

Same shape as sources.<source-id>.loading (type: geojson).

`prefetchedData`

Path: style.sources.<source-id>.runtime.prefetchedData · Type: any

Pre-fetched data from build time

`fetchStrategy`

Path: style.sources.<source-id>.runtime.fetchStrategy · Type: "runtime" | "build" | "hybrid"

When to fetch data: runtime (default), build, or hybrid

`type: raster`

`type`

Path: style.sources.<source-id>.type · Type: "raster" · Required

Source type

`url`

Path: style.sources.<source-id>.url · Type: string · Pattern: ^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/|\.\.?\/)

TileJSON URL

`tiles`

Path: style.sources.<source-id>.tiles · Type: string[]

Tile URL template array

`tileSize`

Path: style.sources.<source-id>.tileSize · Type: integer · Default: 512 · Minimum: 1

Tile size in pixels

`minzoom`

Path: style.sources.<source-id>.minzoom · Type: number · Range: 0 to 24

Minimum zoom level

`maxzoom`

Path: style.sources.<source-id>.maxzoom · Type: number · Range: 0 to 24

Maximum zoom level

`bounds`

Path: style.sources.<source-id>.bounds · Type: [number, number, number, number]

Bounding box [west, south, east, north]

`scheme`

Path: style.sources.<source-id>.scheme · Type: "xyz" | "tms"

Tile coordinate scheme

`attribution`

Path: style.sources.<source-id>.attribution · Type: string

Attribution text

`volatile`

Path: style.sources.<source-id>.volatile · Type: boolean

Skip the tile cache (MapLibre volatile); for frequently changing tiles

`runtime`

Path: style.sources.<source-id>.runtime · Type: object

Per-source live-data configuration

Same shape as style.sources.<source-id>.runtime (type: vector).

`type: raster-dem`

`type`

Path: style.sources.<source-id>.type · Type: "raster-dem" · Required

Source type

`url`

Path: style.sources.<source-id>.url · Type: string · Pattern: ^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/|\.\.?\/)

TileJSON URL

`tiles`

Path: style.sources.<source-id>.tiles · Type: string[]

Tile URL template array

`tileSize`

Path: style.sources.<source-id>.tileSize · Type: integer · Default: 512 · Minimum: 1

Tile size in pixels

`encoding`

Path: style.sources.<source-id>.encoding · Type: "terrarium" | "mapbox" | "custom" · Default: "mapbox"

How elevation is encoded in the tile’s RGB channels

`minzoom`

Path: style.sources.<source-id>.minzoom · Type: number · Range: 0 to 24

Minimum zoom level

`maxzoom`

Same shape as style.sources.<source-id>.runtime (type: vector).

`layers`

Path: style.layers · Type: object[] · Default: []

Map layers, each with an optional nested runtime:

One of 10 variants, selected by type: circle, line, fill, symbol, raster, fill-extrusion, heatmap, hillshade, color-relief, background.

Common fields

Accepted by every variant that lists them below.

`id`

Path: style.layers[].id · Type: string · Required

Unique layer identifier

`label`

Path: style.layers[].label · Type: string

Human-readable layer label

`source`

Path: style.layers[].source · Type: string | object

Layer source: a named-source string ref, or an inline v2 source (nested runtime:, strict RFC 7946 data)

Object form: same shape as style.sources.<source-id>.

`source-layer`

Path: style.layers[].source-layer · Type: string

Source layer name (for vector sources)

`minzoom`

Path: style.layers[].minzoom · Type: number · Range: 0 to 24

Minimum zoom level to show layer

`maxzoom`

Path: style.layers[].maxzoom · Type: number · Range: 0 to 24

Maximum zoom level to show layer

`filter`

Path: style.layers[].filter · Type: array

MapLibre filter expression

`visible`

Path: style.layers[].visible · Type: boolean · Default: true

Initial visibility state

`toggleable`

Path: style.layers[].toggleable · Type: boolean · Default: true

Allow users to toggle visibility

`before`

Path: style.layers[].before · Type: string

Layer ID to insert this layer before

`interactive`

Path: style.layers[].interactive · Type: object

Interactive event configuration

Same shape as layers[].interactive.

`legend`

Path: style.layers[].legend · Type: object

Legend configuration

Same shape as layers[].legend.

`effect`

Path: style.layers[].effect · Type: object

Experimental: a registered shader effect (type + flat params) that enhances this layer; the layer itself is the static fallback

Same shape as layers[].effect.

`metadata`

Path: style.layers[].metadata · Type: map of any

Custom metadata

`runtime`

Path: style.layers[].runtime · Type: object

Per-layer experience configuration

`interactive`

Path: style.layers[].runtime.interactive · Type: object

Interactive event configuration

Same shape as layers[].interactive.

`legend`

Path: style.layers[].runtime.legend · Type: object

Legend entry for this layer

Same shape as layers[].legend.

`label`

Path: style.layers[].runtime.label · Type: string

Human-readable layer label

`toggleable`

Path: style.layers[].runtime.toggleable · Type: boolean

Allow users to toggle visibility

`effect`

Path: style.layers[].runtime.effect · Type: object

Experimental: a registered shader effect (type + flat params) that enhances this layer; the layer itself is the static fallback

Same shape as layers[].effect.

Path: style.layers[].layout · Type: object

Color-relief layout properties

Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.

`type: background`

Common fields: runtime, extends, source.

`id`

Path: style.layers[].id · Type: string · Required

Unique layer identifier

`type`

Path: style.layers[].type · Type: "background" · Required

Layer type

`paint`

Path: style.layers[].paint · Type: object

Background paint properties

Same shape as layers[].paint (type: background).

`layout`

Path: style.layers[].layout · Type: object

Background layout properties

Any other MapLibre layout property valid for this layer type is accepted as well; the MapLibre style spec is the reference for each property’s semantics.

`metadata`

Path: style.layers[].metadata · Type: map of any

Custom metadata

`runtime`

Type: object · Default: {}

The runtime half

`map`

Path: runtime.map · Type: object · Default: {}

MapLibre Map constructor options

`interactive`

Path: runtime.map.interactive · Type: boolean · Default: true

Enable map interaction

`controls`

Path: runtime.controls · Type: object

Map controls

Same shape as controls.

`legend`

Path: runtime.legend · Type: object

Legend configuration

Same shape as legend.

`parameters`

Path: runtime.parameters · Type: map of object

Presentation metadata for state keys — label, type, range

Same shape as parameters.

`markers`

Path: runtime.markers · Type: object[]

Standalone markers — DOM pins live, symbol layers + sprite on export

Same shape as markers.

`fitTo`

Path: runtime.fitTo · Type: object

Fit the initial camera to a GeoJSON source’s data (v1: config.fitTo)

Same shape as config.fitTo.

`popups`

Path: runtime.popups · Type: object[]

Standalone popups open at a coordinate — no layer, no marker

Same shape as popups.

`container`

Path: runtime.container · Type: object

Map container presentation (v2 home of v1’s style:/className:)

`style`

Path: runtime.container.style · Type: string

Inline CSS styles for the map container

`className`

Path: runtime.container.className · Type: string

CSS class name for the map container

`state`

Type: map of object

Runtime-tunable values (may live here or under style:)

Same shape as state.

`parameters`

Type: map of object

Presentation metadata for state keys (may live here or under runtime:)

Same shape as parameters.