Theme Inheritance Patterns for Vector Tile Map Styling

{
  "version": 8,
  "name": "base",
  "metadata": {
    "pipeline:role": "base",
    "pipeline:version": "1.0.0"
  },
  "glyphs": "https://cdn.example.com/fonts/{fontstack}/{range}.pbf",
  "sprite": "https://cdn.example.com/sprites/default",
  "sources": {
    "openmaptiles": {
      "type": "vector",
      "tiles": ["https://tiles.example.com/{z}/{x}/{y}.pbf"],
      "minzoom": 0,
      "maxzoom": 14
    }
  },
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": { "background-color": "#f8f4f0" }
    },
    {
      "id": "water",
      "type": "fill",
      "source": "openmaptiles",
      "source-layer": "water",
      "paint": { "fill-color": "#a8d5e2" }
    },
    {
      "id": "road-primary",
      "type": "line",
      "source": "openmaptiles",
      "source-layer": "transportation",
      "filter": ["==", ["get", "class"], "primary"],
      "paint": { "line-color": "#e8c87a", "line-width": 2 }
    }
  ]
}

// theme.dark.json
{
  "name": "dark",
  "metadata": { "pipeline:role": "override", "pipeline:variant": "dark" },
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": { "background-color": "#1a1a2e" }
    },
    {
      "id": "water",
      "type": "fill",
      "source": "openmaptiles",
      "source-layer": "water",
      "paint": { "fill-color": "#16213e" }
    },
    {
      "id": "road-primary",
      "type": "line",
      "source": "openmaptiles",
      "source-layer": "transportation",
      "filter": ["==", ["get", "class"], "primary"],
      "paint": { "line-color": "#e94560", "line-width": 2 }
    }
  ]
}

import json
import hashlib
from pathlib import Path
from typing import Any

def merge_layers(base_layers: list, override_layers: list) -> list:
    """Merge layers arrays by 'id', preserving base ordering."""
    index = {layer["id"]: layer.copy() for layer in base_layers}
    for ol in override_layers:
        lid = ol.get("id")
        if lid in index:
            # Deep-merge paint and layout sub-dicts; scalar keys overwrite
            for key in ("paint", "layout"):
                if key in ol:
                    index[lid].setdefault(key, {}).update(ol[key])
            # Non-dict keys overwrite directly
            for key, val in ol.items():
                if key not in ("paint", "layout"):
                    index[lid][key] = val
        else:
            # Append new layers from override at the end
            index[lid] = ol.copy()
    # Preserve base ordering, then append override-only layers
    base_ids = [l["id"] for l in base_layers]
    extra = [v for k, v in index.items() if k not in base_ids]
    return [index[lid] for lid in base_ids] + extra


def deep_merge(base: dict, override: dict) -> dict:
    """Recursively merge override into base; arrays use by-id strategy for layers."""
    result = base.copy()
    for key, val in override.items():
        if key == "layers" and key in result:
            result[key] = merge_layers(result[key], val)
        elif isinstance(val, dict) and isinstance(result.get(key), dict):
            result[key] = deep_merge(result[key], val)
        else:
            result[key] = val
    return result


def compile_theme(
    base_path: Path,
    override_path: Path,
    output_dir: Path,
) -> Path:
    base_style = json.loads(base_path.read_text())
    override_style = json.loads(override_path.read_text())

    merged = deep_merge(base_style, override_style)

    # Deterministic content hash for cache-busting
    content_hash = hashlib.sha256(
        json.dumps(merged, sort_keys=True).encode()
    ).hexdigest()[:12]

    variant = override_style.get("name", override_path.stem)
    out_path = output_dir / f"{variant}-{content_hash}.json"
    output_dir.mkdir(parents=True, exist_ok=True)
    out_path.write_text(json.dumps(merged, indent=2, sort_keys=True))
    return out_path

import jsonschema
import requests

_SCHEMA_URL = (
    "https://raw.githubusercontent.com/maplibre/maplibre-style-spec"
    "/main/src/reference/v8.json"
)

def validate_style(style_path: Path, schema_cache_path: Path) -> None:
    """Raises jsonschema.ValidationError on any spec violation."""
    if not schema_cache_path.exists():
        schema_cache_path.write_text(requests.get(_SCHEMA_URL, timeout=10).text)

    schema = json.loads(schema_cache_path.read_text())
    style = json.loads(style_path.read_text())
    jsonschema.validate(instance=style, schema=schema)


def audit_get_refs(style: dict, known_attrs: set[str]) -> list[str]:
    """Return a list of attribute names referenced via ['get', ...] with no tile backing."""
    missing = []

    def walk(node: Any) -> None:
        if isinstance(node, list) and len(node) >= 2 and node[0] == "get":
            attr = node[1]
            if isinstance(attr, str) and attr not in known_attrs:
                missing.append(attr)
        elif isinstance(node, dict):
            for v in node.values():
                walk(v)
        elif isinstance(node, list):
            for item in node:
                walk(item)

    walk(style)
    return missing

# Compile all variants
python3 compile_themes.py \
  --base themes/base.style.json \
  --overrides themes/theme.*.json \
  --output dist/styles/

# Upload to Cloudflare R2 (or S3)
for f in dist/styles/*.json; do
  aws s3 cp "$f" "s3://example-tiles/styles/$(basename $f)" \
    --content-type "application/json" \
    --cache-control "public, max-age=31536000, immutable"
done

# Update the short-lived manifest that clients poll
aws s3 cp dist/styles/manifest.json s3://example-tiles/styles/manifest.json \
  --content-type "application/json" \
  --cache-control "public, max-age=60, must-revalidate"