MapTiles Doctor

Overview

A style can be valid JSON, pass every schema validator, and still ship a broken map. The failure is cross-artifact: a source-layer was renamed in the tileset, an icon left the sprite, a glyph range stopped being served, a property an expression reads is no longer in the tiles. Nothing in the style is wrong on its own — it just no longer agrees with what is deployed next to it.

Existing tools check one layer of that stack at a time: style syntax, or vector tile validity, or PMTiles metadata. MapTiles Doctor checks the join between them.

Install

Node 24.18.1 or newer in the Node 24 LTS line.

npx maptiles-doctor check style.json --source basemap=world.pmtiles

Or install it into a project:

npm install --save-dev maptiles-doctor

From a checkout

npm 11.11.0 or newer.

npm install
npm run check

npm run check runs audit, typecheck, lint, tests, build, package validation and a staleness check on the committed Action bundle. See CONTRIBUTING.md.

CLI

maptiles-doctor check <style> [options]   # check a style against its artifacts
maptiles-doctor schema [--output <path>]  # print the report JSON Schema
maptiles-doctor --help
maptiles-doctor --version

<style> is a path or a URL. Everything the style declares relatively — sources, sprites, glyphs — resolves against it.

Output formats

maptiles-doctor check style.json --source basemap=world.pmtiles --format json
maptiles-doctor check style.json --source basemap=tiles.mbtiles --format sarif
maptiles-doctor check style.json --source basemap=tilejson.json --format github
maptiles-doctor check style.json --format html --output report.html

Flags

Exit codes

An incomplete run never exits non-zero on its own. It reports what could not be verified rather than claiming a pass.

Evidence ranking

Every finding carries a severity that reflects how strong the evidence behind it is. This is the part of the design worth understanding, because it is what keeps the tool usable on a real style.

Overzoom is not a defect

Zoom is judged against the source minzoom only. MapLibre overzooms: above a source's maxzoom it keeps rendering by scaling the deepest tiles it has, which is how a maxzoom-14 basemap draws buildings at z18. A layer drawing above the source maxzoom is normal construction and is never reported. MapLibre does not underzoom, so a layer whose maxzoom falls below the source minzoom can never draw and is broken; one that merely starts below it is risky.

Check reference

Icons built from feature data

An icon-image written as ["concat", "icon-", ["get", "class"]], or with the legacy "icon-{class}" token syntax, has no name until a feature supplies one. Both spellings are reduced to the same shape — a sequence of literals and property lookups — then completed from the sampled tiles, so each name the tiles really produce is checked against the sprite.

Property combinations are recorded per feature. Taking the distinct values of two properties and crossing them would invent pairs that never occur together, which is a false-positive generator. A template no sampled feature can complete is an incomplete check, not a finding.

Multiple sprites

The array form of sprite declares several sprites and namespaces every icon reference as <sprite-id>:<icon-name>. Every declared sprite is read, the prefix selects which index to look in, and a prefix naming no declared sprite is reported as its own finding rather than as a missing icon — they are different mistakes with different fixes. Suggestions come back re-namespaced, ready to paste into the style.

Tile sampling

Sampling is on by default. The checker reads a few real tiles per source and treats the layers and feature properties it observes as evidence, because declared metadata is what drifts.

Tiles are sampled one populated anchor per zoom — London, New York, Tokyo and onwards — rather than at the centre of the source's bounds. The centre of a world tileset is open ocean, and a tile there has no roads, no POIs and no labels, which leaves every check that needs a feature unable to conclude anything. A source whose bounds contain none of the anchors falls back to its own centre, which keeps regional extracts working.

maptiles-doctor check style.json --sample-at 13.405,52.52   # sample over Berlin
maptiles-doctor check style.json --max-sample-tiles 5
maptiles-doctor check style.json --no-sample-tiles          # metadata only
maptiles-doctor check style.json --offline                  # remote reads become incomplete

A source that declares tiles inline is read from the style object rather than fetched: the only URL it offers is a {z}/{x}/{y} template, and requesting that verbatim asks a tile server for a tile named {z}. Raster sources are recognised and not parsed as vector tiles.

Report schema

Schema v1 is a published consumer contract. The checker validates its own output against it before returning, and the equivalent JSON Schema is printable:

maptiles-doctor schema --output maptiles-doctor-report.schema.json

Severities are broken, risky, warning, info. A check that never ran produces no entry at all rather than one that passed.

GitHub Action

- uses: schmidi000/maptiles-doctor/packages/action@v0.1.1
  with:
    style: style.json
    sources: |
      basemap=world.pmtiles
    fail-threshold: broken
    report: maptiles-doctor-report.json

The Action runs a committed self-contained bundle, so a runner needs no install step. Findings become workflow annotations — broken as errors, risky and warning as warnings, info and every incomplete check as notices — and the report path is exposed as a step output. Regenerate the bundle with npm run bundle:action after changing Action or core sources; npm run check fails when it is stale.

@v0 tracks the latest 0.x release. Pin the exact vX.Y.Z tag to avoid picking up a pre-1.0 breaking change.

MBTiles depends on the native better-sqlite3 module, which cannot be bundled. Inside the Action an MBTiles source reports an incomplete check rather than passing silently — use PMTiles or TileJSON in CI, or run the CLI from an installed package. Playwright is external to the bundle for the same reason, so a configured visual canary also reports an incomplete check.

VS Code extension

The extension runs the same engine against the buffer in the editor, so an unsaved edit is checked as typed. Styles are checked on open and on save, and diagnostics land on the offending node — the layer's source-layer, a zoom bound, an icon-image, or the sources entry that could not be read.

broken maps to Error, risky and warning to Warning, and info plus every incomplete check to Information, so a network failure can never read as a pass. Two commands are contributed: Run MapTiles Doctor and Open Report.

npm run package:vsix

Visual canaries

Deterministic checks read metadata and tiles. A canary renders the style with MapLibre GL in headless Chromium and reports what the map actually drew: rendered feature counts, requests that failed, MapLibre errors, and baseline pixel diffs.

maptiles-doctor check style.json \
  --canary 13.405,52.52,14,berlin \
  --screenshot-dir canaries \
  --baseline-dir canaries/baseline

Rendered evidence is ranked the same way sampled evidence is. An HTTP error status is an artifact answering "no" and is broken. A request that never completed proves nothing, so it is incomplete and suppresses every finding that reads what was drawn, because a blocked canary renders an empty map too. A MapLibre error event or an empty render is risky, and a layer named in expectLayers that drew nothing is broken.

A missing baseline is info; drift above --max-diff-ratio is risky and writes a diff PNG. Determinism comes from a fixed device pixel ratio, fadeDuration: 0, a non-interactive map, and waiting for the map's idle event.

Canaries are off unless one is configured, and need two optional peers. Without them the run reports an incomplete check rather than a pass:

npm install playwright maplibre-gl
npx playwright install chromium

Validation

Fixtures prove the checker does what it was written to do. They cannot prove that a broken finding corresponds to a map that renders wrong, because the same process authored the check and the thing it checks. Two harnesses close that gap. Neither is part of npm run check: both depend on third-party uptime, and a gate that is red for reasons outside the repo teaches everyone to ignore it.

Real-world corpus

npm run validate:real

Runs the built CLI against production styles from four independent providers across three tile schemas. Every finding is either a real contract break shipping in production or a false positive in the checker, and separating those is the point — the false-positive rate is what decides whether the tool is usable.

Seeded failures

npm run validate:seed

Seeds ten known contract breaks into a real style, one per check, and counts what the checker notices. Detection is measured as a diff against the unmutated baseline, so a style that already has findings cannot score full marks for noticing nothing. A mutation that cannot be expressed against a style is excluded from the denominator and named in the output rather than silently padding the rate.

Packages

The Action and the extension are wrappers around the same engine. Native modules stay out of the Action bundle and are loaded lazily in core, so a missing binding degrades to an incomplete check rather than a crash.

Dependency policy

• Use the newest stable patched versions available at the time of work.
• Pin exact versions.
• Run npm audit after dependency changes.
• Do not introduce unresolved high or critical CVEs without explicit approval.
• Prefer upgrading a parent package over adding an override for a transitive finding.

"CVE-free" means "no known current audit findings", not a guarantee against undisclosed vulnerabilities.

Roadmap

The hosted tier is deliberately gated on evidence of repeat CLI and CI usage. The free CLI is the product until there is reason to believe someone will pay for history of it.