YAML reference

Every key the maplibre-yaml validator accepts, with its type, default, allowed values, and description. The guides under YAML Schema explain how to use these keys; this reference lists all of them.

Generated reference

This page is generated from the Zod schemas in packages/core/src/schemas/ on every docs build — descriptions are the schemas’ own .describe() text, so it always matches the installed validator. Edit the schema, not this page.

Document shapes

Page	Covers
Map block (v1)	Every key of a type: map block in format v1, generated from the schemas.
Sources	Every data-source type and key, generated from the schemas.
Layers	Every layer type and key, including interactivity, generated from the schemas.
Map block (v2)	Every key of a format-v2 (style:/runtime:) map block, generated from the schemas.
Scrollytelling block	Every key of a type: scrollytelling block, generated from the schemas.
Root document (pages)	Every key of a multi-page pages: root document, generated from the schemas.

Reading this reference

• Type uses TypeScript-like notation: string[] is a list of strings, map of X is a YAML mapping whose keys you choose, and a | b means either.
• Required keys must be present; everything else is optional.
• A key whose structure is shared (the popup DSL, controls, legend items, …) is documented once; other places link to it.
• paint and layout properties are MapLibre’s own; each links to the MapLibre style spec.
• Keys starting with x- are accepted anywhere as extensions and never validated.

Machine-readable schemas

The same schemas are published as JSON Schema for editors and agents (format v1):

• map.schema.json
• scrollytelling.schema.json
• root.schema.json
• any.schema.json

See Editor Setup to wire them into VS Code.