Style compatibility?

[tmcw]

From the readme,

The library is intended to be a drop-in replacement for the Mapbox’s version with additional functionality.

I'm seeing changes in maplibre's style spec that are incompatible with the original Mapbox Style Spec, like icon-padding. I'd love to be able to switch between maplibre and Mapbox GL, and support maplibre styles with Mapbox GL and vice-versa. But if the style spec is going to be incompatible, that won't be possible. It doesn't seem like there's any attempt to coordinate on changes, which is a bit disappointing.

[samanpwbb]

A possible solution here would be to have maplibre-gl-js maintain a utility to migrate from a maplibre stylesheet of a given version, down to a gl js stylesheet of a given version. Ideally something that could either be run at build or runtime. I would strongly recommend the maintainers consider this. It would not only be useful for supporting maplibre -> mapbox gl compatibility, but also would enable style authoring tools built on the maplibre spec to output styles that are compatible with older versions of maplibre-gl-js.

[bdon]

@samanpwbb is the intended use of root key version which AFAIK is always hardcoded to 8 right now?

[tmcw]

I think that would be a good place to start - if Maplibre used a different version number or version scheme, it would be possible to detect and convert - like if Maplibre versions were "8+" or something. Right now it's tough: with the removal of the mapbox:// scheme, Maplibre doesn't support Mapbox styles, and with the addition of things like icon-padding, Mapbox doesn't support Maplibre styles, but neither can tell offhand which flavor of style they're looking at.

[HarelM]

mapbox:// scheme can be supported using a plugin one of the community members created. But there might be other style specs features that were added in mapbox 2.x that I'm not aware of...

[samanpwbb]

Some background on the version key:

• Backwards compatibility has always been maintained for everything on v8 styles. Since that flag switched from 7 to 8, zero features have been removed. There is a migration script in style_spec that will go from v7 -> v8 because v8 did introduce real breaking changes (like dropping support for constants I think?).
• On the other hand, upward compatibility, allowing old versions of GL to render new versions of stylesheets, has never been maintained. A style made with today's v8 is incompatible with old versions of GL JS.
• Informing users of styles of upwards incompatibilities is done here, with the sdk-support key: https://github.com/mapbox/mapbox-gl-js/blob/db83918000c9e3c3c1bffb3fae6c6045bb5b3ba5/src/style-spec/reference/v8.json#L615-L622.

With this in mind, incrementing a full version number up to v9 should probably only happen if you plan to make backwards incompatible changes.

It would be possible to enable forwards compatibility with a compatibility mode "transpiler" that is based on the sdk-support key. You'd scan a style for properties that don't work with your version of maplibre-gl-js, and then run a transform function to output a version of the style that is compatible. For example, the new padding value type could be transformed to a number by averaging or picking one of the values out of the padding array. The purpose of compatibility mode would not be to have perfect style parity (which would be impossible) but to ensure you don't get validation errors that prevent the map from rendering.

An alternative to writing a transpiler would be to borrow a pattern from CSS and allow users to provide fallback values to manually add support to older renderer versions.

[HarelM]

I'll fix the readme, this is no longer accurate.
You can use stylespec features that were introduced before 2.x, this is the right way to make sure both mapbox and maplibre support it.
This is a community driven project, if you want to create a style translator/checker you are more than welcome to do so.
The projects are going in different directions, and our focus is what the community drives forward.
We can't align with mapbox as we have no control over what they do and we can't have them defining where to go, this is not a reasonable request.
We also can't copy from them which makes things very hard for us legally. Thus divergence is inevitable.
You can spend the time and help the community by creating the tools that other may need.
Writing passive aggressive messages saying you are disappointed is the exact opposite of helping as it only discourage those that volunteer to maintain this project...

[tmcw]

Sorry if it came off as passive-aggressive - that wasn't intended it at all. I saw the readme and was going on the assumption that Maplibre was generally trying to stay compatible, at least at a style spec level, and learned that it wasn't. That's fine, it's the project's decision. I read something else, in the readme, and would prefer something that was compatible, hence the disappointment.

I'd be surprised if there's any legal challenge behind consuming the same format – at least under US law, writing alternative implementations based around formats is very well-established. Even if the style spec was legally encumbered, which it isn't, a reverse engineered reader would be fine. And coordinating on a shared specification seems, to me, in a general sense, to be something that's possible. Like any form of coordination, it'd mean less pure freedom for Maplibre and more requirements to meet and agree, but is it possible to at least ask around and see if changes could be coordinated? Probably, right?

But it's totally fine if that's not what the project is planning to do. I'm not trying to discourage anyone or anything like that. Maplibre is just doing something different than what I thought it was doing, and what the readme said it was doing, which is fine, but for my particular usecase, makes things trickier.

[HarelM]

I have re-read the readme and if you continue past the first paragraph you'll see some hints related to what I said. Having said that, you are more than welcome to open a pull request to update the readme to better explain what you learnt from this discussion 😀
If creating a unified spec is something that you want to push forward, by all means, please do.
I wouldn't know where to start, and this might be why we are where we are...
I think it might create a lot of bureaucracy and I'm not sure the benefit of it. I prefer encouraging contributors to make the changes in the code and allow a good steady flow of PR rather than asking them to setup a meeting and align the spec, but that might just be me...
As a side note, icon-padding was only enhanced and not changed, meaning new versions support improved functionally but the original definition is still supported, and this was introduced in 2.x version, where we started to diverge. 1.x versions are drop in replacement.
To be able to drop-in-replace version 2.x of mapbox is just asking to be sued from my point of view 😀 and unfortunately for you, I believe the more we diverge the safer we are...