Style definition to allow relative paths in URLs

[zstadler]

Motivation

ArcGIS REST API has a Vector Tile Style service that returns styles for vector tiles in Mapbox GL Style specification.

While the Mapbox Style requires that the URLs for glyphs, sprite, and sources must be absolute, the ArcGIS styles uses relative URLs. One advantage of this approach is that a style file can be used by different providers without modification.

It would be great if MapLibre is able to directly support style definitions with relative URLs.

An example from the above page:

{
   "version": 8,
   "sprite": "../sprites/sprite",
   "glyphs": "../fonts/{fontstack}/{range}.pbf",
   "sources": {
       "esri": {
           "type": "vector",
           "url": "../../"
       }
   },
   "layers": [
       {
           "id": "Graduated Color/GraduatedColor_poly/482025.000000 - 2135252.000000",
           "type": "fill",
           "source": "esri",
           "source-layer": "GraduatedColor_poly",
           "filter": [
               "==",
               "_symbol",
               0
           ],
           "layout": {},
           "paint": {
               "fill-color": "#FFFF80",
               "fill-outline-color": "#6E6E6E"
           }

...

       }
   ]
}

Design Alternatives

Design

Mock-Up

Concepts

Implementation

[github-actions]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 7 days.

[HarelM]

fetch is able to get content from relative path, I'm not sure this is not supported...
Relative urls are relative to the server that runs the site and the location of the "current" page and baseUrl...
Can you share an example where this is not working?

[zstadler]

This is the GL Style for ESRI World_Basemap_v2, for example.

I've only tried it as a new base map in Israel Hiking.

[HarelM]

This won't work, the relative path are for a server somewhere not related to Israel Hiking. I know Israel Hiking is replacing the fonts and glyphs so you can't really test this.
for example the relative path to the vector source is:
https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/
which seems like a definition of the vector source not part of the style, which is weird.
Maybe there's a mapbox powered site somewhere on this server that can present this style, I don't know honesty, but this library is treating the URLs are relative to the current location this it is running from.
I'm not sure there's anything to solve in this repo...

[xabbu42]

I think the idea is to interpret the paths relativ to the style as baseurl, instead of relativ to the current location maplibre-gl-js is running from. I am correct in my understanding @zstadler?

This actually seems to be the more useful way to handle relativ pathes and easy enough to implement. There could be installations out there which depend on the current behaviour of course, but as this styles are non-standard anyway I would not consider that change as breaking the api.

[HarelM]

The question of "relative to what" seems like a complex question to me - what if you are using a tileJson to define the location of the tiles and this tilejson is on another server - do you look for the tiles relative to it or relative to where the style is?
When looking at HTML and scripts loading, relative path is always to the server that hosts the page, this seems to me like a non ambiguous approach.
@xabbu42 if you feel this is easy to implement go for it :-)

[xabbu42]

We need to agree on the right thing to do first :-).

I would have expected tile urls in a tilejson to be relativ to that tilejson and tile urls directly in the style to be relativ to that style. So the least surprising and most useful way to handle relativ paths for me is to always interpret them relativ to the json file they occur in, just like relative paths in html are by default relativ to that html file itself.

[HarelM]

The above suggestion seems like the right logic to me, I tend to think there are a lot of edge cases for this request, but if you feel confident about it go ahead :-) We can always solve these later on...

[zstadler]

I think the idea is to interpret the paths relativ to the style as baseurl, instead of relativ to the current location maplibre-gl-js is running from. I am correct in my understanding @zstadler?

This actually seems to be the more useful way to handle relativ pathes and easy enough to implement. There could be installations out there which depend on the current behaviour of course, but as this styles are non-standard anyway I would not consider that change as breaking the api.

Yes.

For example,
https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/styles
has "sprite" : "../sprites/sprite",.
It would be interpreted as
https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/sprites/sprite

Sprite access will be done to
https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/sprites/sprite.json
https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/sprites/sprite.png
and https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/sprites/sprite@2x.png

Similarly,
"glyphs" : "../fonts/{fontstack}/{range}.pbf",
will be interpreted as
"glyphs" : "https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/fonts/{fontstack}/{range}.pbf",

and

"sources" : {
	"esri" : {
		"type" : "vector",
		"url" : "../../"
	}

will be interpreted as

"sources" : {
	"esri" : {
		"type" : "vector",
		"url" : "https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer"
	}

[zstadler]

Thanks @xabbu42 for taking this task in#645!

[klokan]

Discussed today on the SC meeting.

+1 for the idea - it seems to be a nice general implementation. Thanks for the effort!

Could we update the documentation in
https://github.com/maplibre/maplibre-gl-js-docs/tree/main/docs/pages/style-spec

Especially:

• https://maplibre.org/maplibre-gl-js-docs/style-spec/sources/
• https://maplibre.org/maplibre-gl-js-docs/style-spec/sprite/
• https://maplibre.org/maplibre-gl-js-docs/style-spec/glyphs/
  to explicitly mention the absolute URL currently, and relative URL as an option proposed here?