Style Diff

Overview

The diff command compares two Mapbox GL style JSONs at the property level. Instead of just showing which layers were added or removed, it tells you exactly which paint, layout, filter, and zoom properties differ between matched layers.

Usage

python -m map_style diff style/streets.json style/streets_classic.json

Output is organized into sections:

• REMOVED — layers only in the left file
• ADDED — layers only in the right file
• CHANGED — layers in both files with property differences
• REORDERED — layers that moved position

Each changed layer shows the property path and old → new values:

CHANGED  road.highway.motorway
  paint.line-color: "#fc8" → "#ffd700"
  paint.line-width: 4 → 6
  minzoom: 5 → 4

Options

--ignore-order

Suppress the REORDERED section. Useful when you only care about property changes, not layer ordering.

python -m map_style diff a.json b.json --ignore-order

--normalize-expressions

Convert legacy Mapbox GL filter syntax to the expression form before comparing. This prevents false diffs when one file uses ["==", "class", "motorway"] and the other uses the equivalent expression syntax.

python -m map_style diff a.json b.json --normalize-expressions

--sort-predicates

Sort children of all/any filter arrays before comparing. This treats ["all", A, B] and ["all", B, A] as identical.

python -m map_style diff a.json b.json --sort-predicates

--ignore-defaults

Suppress diffs where one side uses the Mapbox GL spec default value. For example, if one file has "line-cap": "butt" (the default) and the other omits it, this option treats them as identical.

python -m map_style diff a.json b.json --ignore-defaults

Combine them

python -m map_style diff a.json b.json \
    --ignore-order \
    --normalize-expressions \
    --sort-predicates \
    --ignore-defaults

What gets compared

For each layer present in both files:

Skipped: id (match key), top-level name/sprite/glyphs/version.

Exit codes