The style specification

Quick answer

This tutorial explains the style specification as a JSON contract: the mandatory version: 8, sources, layers, and optional sprite, glyphs, center, terrain, light and sky. It lists layer types such as background, fill, line, circle, symbol, raster, fill-extrusion, heatmap and hillshade with their required geometry, and shows a minimal inline style object. You will be able to validate a style and know why a map stays blank.

Last verified 2026-11-03 · MapLibre GL JS 4.x · Cite this page

Key points

Always declare version: 8, because any other value makes MapLibre reject the entire style.
Give every non-background layer a unique id, type, source, plus source-layer for vector tiles.
Deep-copy a style object before reusing it, since setStyle mutates the object in place.

Example

var style = {
  version: 8,
  sources: {
    base: {
      type: 'raster',
      tiles: ['https://tile.openstreetmap.org/{z}/{x}/{y}.png'],
      tileSize: 256,
      attribution: '&copy; OpenStreetMap contributors'
    }
  },
  layers: [
    {
      id: 'bg',
      type: 'background',
      paint: { 'background-color': '#0d1117' }
    },
    {
      id: 'base-tiles',
      type: 'raster',
      source: 'base',
      paint: { 'raster-opacity': 0.85 }
    }
  ]
};

var map = new maplibregl.Map({
  container: 'map',
  style: style,
  center: [116.391263, 39.907359],
  zoom: 4
});

{
  "id": "countries-fill",
  "type": "fill",
  "source": "base",
  "source-layer": "countries",
  "filter": ["==", ["geometry-type"], "Polygon"],
  "paint": {
    "fill-color": ["match", ["get", "continent"], "Asia", "#f2e8d5", "#e8eef4"],
    "fill-opacity": 0.9
  }
}

Notes

Writing fill-color on a line layer is rejected as an unknown property and falls back to default styling.
Pointing glyphs at fonts the service does not provide makes all text vanish without an error.

Runnable examples Chinese original All Tutorials

English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.

Cite this page

Atlaslog (2026). The style specification. https://www.jingweizhi.com/en/maplibre/tutorials/style-spec.html (accessed 2026-11-03).