Reusing values & blocks

A map document often repeats itself: the same colour on six layers, the same paint block with one value changed. YAML’s anchors, aliases and merge keys remove that repetition. They are part of YAML itself, resolved while the file is read, so <ml-map>, mlym validate and the Astro components all see the same expanded document, and an exported style.json contains plain values.

To share data between layers, use a named source first (Share one source between layers): the file is loaded once, which an anchor doesn’t do.

Anchors and aliases

Name a value with &name where it first appears, and reuse it with *name:

type: map
id: parks
config:
  center: [-73.97, 40.78]
  zoom: 13
  mapStyle: "https://tiles.openfreemap.org/styles/liberty"
sources:
  park:
    type: geojson
    region:
      coordinates:
        - [[-73.981, 40.768], [-73.958, 40.800], [-73.949, 40.797], [-73.973, 40.764], [-73.981, 40.768]]
      name: Central Park
layers:
  - id: park-fill
    type: fill
    source: park
    paint:
      fill-color: &green "#2f7d32"
      fill-opacity: 0.3
  - id: park-outline
    type: line
    source: park
    paint:
      line-color: *green
      line-width: 2

Change the value after &green and both layers change. An anchor can hold any value: a number, a list, or a whole mapping. It must come before the aliases that use it, and it works only inside the file it is in: another YAML file can’t refer to it.

Merge keys

<<: *name copies an anchored mapping into the current one. Keys you write beside it win:

layers:
  - &base-parcel
    id: parcels-built
    type: fill-extrusion
    source: parcels
    paint:
      fill-extrusion-color: "#8899aa"
      fill-extrusion-opacity: 0.9
  - <<: *base-parcel
    id: parcels-proposed
    paint:
      fill-extrusion-color: "#cc7744"

parcels-proposed is a copy of parcels-built with its own id and colour.

Merge is shallow

A key you write replaces the whole value it merges over. Above, parcels-proposed gets the new fill-extrusion-color and loses fill-extrusion-opacity, because its own paint: replaced the merged one. To keep the rest of a nested block, anchor that block too and merge inside it:

layers:
  - id: parcels-built
    type: fill-extrusion
    source: parcels
    paint: &base-paint
      fill-extrusion-color: "#8899aa"
      fill-extrusion-opacity: 0.9
  - id: parcels-proposed
    type: fill-extrusion
    source: parcels
    paint:
      <<: *base-paint
      fill-extrusion-color: "#cc7744"   # opacity 0.9 is kept

maplibre-yaml has no inheritance keyword of its own (such as extends:): anchors and merge keys do the job in every YAML tool, and need nothing from the schema or the editor.

Troubleshooting

• “Unresolved alias (the anchor must be set before the alias): green”: the alias comes before its anchor, the names differ, or the anchor is in another file.
• A merged layer lost a value: merge is shallow; see the caution above.

Moved

Safety

The alias-expansion limit is described in Parsing & validating › Documents from people you don’t control.