Format overview

maplibre-yaml draws a MapLibre map from a YAML document. This page shows the shape every document shares, how a document is checked, and which page explains each part. To look up one key, its type and its default, use the generated YAML reference: it is built from the same schemas the validator uses, so it always matches.

Two kinds of document

Document	Starts with	Shown by
A map document	type: map	The <ml-map src="…"> element; the Astro <Map> and <FullPageMap> components
A story map	type: scrollytelling	The <ml-scrollytelling src="…"> element; the Astro <Scrollytelling> component

A story map is a map plus chapters that move it as the reader scrolls; it is explained in Writing a story file. Every page outside Advanced uses format v1, the default. Format v2 is an opt-in layout of the same map, split into what exports to a MapLibre style and what only runs on the page.

How a map document is laid out

type: map                     # which kind of document
id: earthquakes               # a short name, unique on the page
title: "Earthquakes this week"
config:                       # the camera and the basemap
  center: [-120, 37]          # longitude, latitude
  zoom: 4
  mapStyle: "https://tiles.openfreemap.org/styles/liberty"
sources:                      # where the data comes from
  quakes:
    type: geojson
    url: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson"
layers:                       # how it is drawn, bottom first
  - id: quakes
    type: circle
    source: quakes
    paint:
      circle-radius: ["interpolate", ["linear"], ["get", "mag"], 1, 3, 6, 18]
      circle-color: "#ef4444"
controls:                     # buttons around the map
  navigation: true

config: holds the camera, the basemap and MapLibre’s map options. Every other key sits beside it, at the top level: putting one inside config: is the most common mistake, and validation warns about it (Map documents › config: and the keys beside it). paint: and layout: are MapLibre’s style properties, unchanged, so the MapLibre style spec is their reference.

How a document is checked

One validator checks a document everywhere:

• npx maplibre-yaml@latest validate map.yaml (or mlym validate) checks files from the command line or in CI (The CLI).
• Your editor checks as you type, with the JSON Schema at https://docs.maplibre-yaml.org/schema/latest/map.schema.json (Editor setup).
• <ml-map> checks a document when it loads it.

It reports two kinds of problem. An error, such as a missing center:, stops the map: <ml-map> shows an error card naming the line. A warning, such as a key in the wrong place or a map with no mapStyle, leaves the map drawing; the CLI prints it, and <ml-map> shows it as an author hint while you develop. Each message names the line and, where it can, the fix:

error config.zoom: config is missing zoom: — add zoom: 12 (a number from 0 to 24).
  at line 4, column 3

To check documents from your own code, with the same messages, see Parsing & validating in your own code.

Where each part is explained

Part	Explained in	Every key in
Camera, basemap, 3D, markers, images, state	Map documents	Map reference
Sources and how layers use them	Sources & layers, Loading data	Sources reference
Layer types and styling	Layers & styling	Layers reference
Popups, hover, click actions	Popups, hover & controls	interactive
Controls	Popups › Add map controls	controls
Classes and legends	Thematic maps & legends	classify, legend
Story maps	Writing a story file	Story map reference
Format v2	Format v2	Map reference (v2)
The elements’ attributes, events and slots	HTML pages: the <ml-map> element	<ml-map> & <ml-scrollytelling> reference

TypeScript types

@maplibre-yaml/core/schemas exports the schemas the validator uses and a type for each document (MapBlock, ScrollytellingBlock) and for the config:, controls: and legend: blocks (MapConfig, ControlsConfig, LegendConfig). They describe a document after it is parsed, with defaults filled in. Every export is listed in the TypeScript API; to parse and validate a document in your own code, see Parsing & validating in your own code.

Moved

Reference resolution

How a layer can point at a source by name, or copy it with $ref, is in Sources & layers › How a layer finds its source.