Page MenuHomePhabricator

Cross compatibility between styling specs
Closed, ResolvedPublic2 Estimated Story Points



There are many different styling specs on how to render maps in the client side.
Ideally, to avoid vendor lockdown or to enable our maps stack to use different solutions according to the project needs
it might be interested to investigate if we can support rendering engine agnostic styles.

Existing technology

  • maplibre
  • OpenLayers
  • tangram

Open questions

  • How would we migrate from maplibre-gl to OpenLayers and vice-versa?

There is no need for style migration between the two technologies because both renderers support the mapbox-gl-style spec.

  • How would we migrate from tangram to OpenLayers and vice-versa?

Tangram is nos supposed to support OpenLayers. Switch between the two styles means to choose between OpenLayers and Leaflet as renderers. Also, there is no tool that translates the style spec between the two technologies, if we need to change it we also need to rewrite the style for the chosen platform or create the software to translate it.

  • How would we migrate from maplibre-gl to tangram and vice-versa?

There isn't any automated way to translate mapbox-gl-style to tangram style and vice-versa.

  • What are the impacts on the client-side app? Does it change implementation? Does it need any big refactoring?

If we stick with the mapbox-gl-style we can make it work with both Leaflet and OpenLayers. If we choose tangram it will only work on Leaflet and OpenLayers style will work only in OpenLayers. Geostyler is an option to create a compatibility layer between OpenLayers style to mapbox-gl-style, but it's not common to have vector tile styles in the OpenLayers spec, osm-bright for example exists only in the mapbox-gl-style spec.

  • Is it possible to switch from OpenLayers to Leaflet without major changes and vice-versa? Can vuejs help with that?

This question is out of the scope for this investigation, but it's theoretically possible to architect the client-side components to abstract the interactions between the map, layers, and controls, but we should be careful because both software has different APIs, and not every feature have a correspondent parity.


The three evaluated technologies are stable enough and have their own pros and cons. Also, the style specs are accessible enough for us to use an open-licensed style or create our own style configuration based on current or different styles, which means that we can maintain the same expected user experience no matter what style spec/renderer we choose with insignificant to none variation between the renderers outputs. More detailed comparison can be found in this spreadsheet.

Acceptance criteria
  • Evaluate if the existing compatibility libraries/frameworks are stable enough for our projects
  • A user can view maps rendered using the same styling but backed by different engines

Event Timeline

sdkim set the point value for this task to 2.Jan 5 2021, 4:28 PM

Change 657099 had a related patch set uploaded (by MSantos; owner: MSantos):
[mediawiki/extensions/Kartographer@master] WIP: ADR for WebGL renderer style spec

Change 657099 merged by jenkins-bot:
[mediawiki/extensions/Kartographer@master] ADR for WebGL renderer style spec