[Updated 20 April 2016 by @jfirebaugh]

The Mapbox GL Style Specification forms the domain model for Mapbox maps. It defines objects such as:

• styles
• sources
• layers
• paint and layout properties

These domain objects are central to rendering and manipulating the map, and they should be exposed by both the core mapbox-gl-native API and by the Android and iOS bindings.

This functionality exists in mapbox-gl-js already, via APIs such as addSource, addLayer, and setPaintProperty. Together, we call this set of APIs the runtime styling API (not to be confused with the Mapbox Styles API, a web API).

To get a sense of what is possible with read and write access to the style and its contents, take a look the mapbox-gl-js examples: the large majority of them use one or more runtime styling APIs.

• Show and hide layers (uses setLayoutProperty)
• Create a timeline animation (uses setFilter)
• Add live realtime data (uses addSource and setData)

Furthermore, the rich functionality provided by mapbox-gl-js plugins like mapbox-gl-directions, mapbox-gl-geocoder, and mapbox-gl-draw are enabled by the runtime styling API.

What we have now

mapbox-gl-native and the mobile SDKs currently have an "Annotations API" which provides some forms of runtime styling, namely adding and removing markers, lines, and polygons, with a limited degree of control over their visual appearance.

Rough compatibility with other mapping SDKs, and familiarity to users porting from them, were higher design priorities for the Annotations API than exposing the full gamut of GL style capabilities. This allowed us to satisfy a number of common and important use cases quickly, but it is limiting in a number of respects, and has led to a impedance mismatch between what users expect to be able to accomplish with the Annotations API versus what can be tractably and efficiently implemented.

The primary problem in this regard is that the Annotations API does not provide any means to group annotations into subsets that share common data sources or rendering properties. This is exactly the problem that style sources and layers were designed to solve, and instead of continuing to try to warp the Annotations API to fit sources and layers, or vice versa, we should expose sources and layers as first class API entities.

Specific runtime styling API related feature requests

• Add "markers" (actually, symbol layers) with full control over style properties (e.g. rotation, sprite image, text, etc.)
• Add lines and polygons with full control over style properties (e.g. dashes, line join, line cap, etc.)
• Dynamically show/hide layers (Show / Hide a layer programmatically #3169)
• Add new layers (CustomLayer usage to add custom tiles as map layer #4210)
• Control layer z-ordering (Z-ordering of MGLAnnotationImages #3992)
• Dynamic modifications of layer filters (Filtering features at runtime #2840)

Timeline

We've been working on internal prerequisites for a runtime styling API for some time now. Most importantly, we:

• Converted the internal representation of layers to a class hierarchy matching the style specification
• Moved ownership of the style and associated data from an auxiliary thread to the main thread, so that it is possible to manipulate it without complex cross-thread communication

Current development on the runtime styling API is focused on adding support to the core C++ API for adding and manipulating layers, including rendering properties. The approach is to use code generators whose input is the style specification itself.

Another major task that remains is to convert the internal representation of sources to a class hierarchy matching the style specification. This is a significant internal refactoring that will be necessary to support runtime creation and manipulation of sources.

The runtime styling API is a high priority, but as always, competes with other high priority items for resources. We currently aim to ship a runtime styling API in some form in late Q2 to early Q3.