Vector source documentation gaps

[stevage]

Links to related documentation

https://www.mapbox.com/mapbox-gl-js/style-spec/#sources-vector

Some issues:

• [ ] No statement that either "tiles" or "url" are required. (Both marked "optional".)
• [ ] This statement is confusing for me: "All geometric coordinates in vector tiles must be between -1 extent and (extent 2) - 1 inclusive." (I don't know what "extent" refers to here, or why this technical detail is important to know here.)
• [ ] No link to TileJSON spec.
• [ ] A simple example of a "tiles" value would help a lot, and avoid having to google the TileJSON spec. Eg, ["http://example.com/tiles/mylayer/{z}/{x}/{y}.pbf"]
• [x] "of the form mapbox://mapid" is confusing to me. Either of these would be better:
  • "of the form mapbox://username.tilesetid"
  • "of the form mapbox://tilesetid"
• [ ] No links to either "Slippy map tilenames scheme." or "OSGeo spec scheme". Would be much clearer with a very brief description of what each of these entails.

[andrewharvey]

"of the form mapbox://mapid" is confusing to me. Either of these would be better:

MapID is consistent with Mapbox Studio: https://www.mapbox.com/studio/tilesets/mapbox.mapbox-streets-v8/

[andrewharvey]

Good feedback @stevage

A simple example of a "tiles" value would help a lot, and avoid having to google the TileJSON spec. Eg, ["http://example.com/tiles/mylayer/{z}/{x}/{y}.pbf"] No link to TileJSON spec.

I think we should link the text mentioning TileJSON to the spec.

No links to either "Slippy map tilenames scheme." or "OSGeo spec scheme". Would be much clearer with a very brief description of what each of these entails.

I'm :+1: for including these links.

Did you want to submit a PR with these improvements?

[stevage]

MapID is consistent with Mapbox Studio: https://www.mapbox.com/studio/tilesets/mapbox.mapbox-streets-v8/

Honestly, I think that's confusing too. It's a tileset, not a map. For some reason, tilesets have "map ids" that include your username, while datasets have "dataset ids" that don't. What do styles have? "style URLs", of the form "mapbox://styles/username/aaa123123a123a132" - not the slash as separator, instead of dot

It's a little bit bizarre actually. Is there anything you ever do with a "map id" other than put "mapbox://" on the front of it and add it to a style JSON? Real consistency would be something like:

• Style URL: "mapbox://styles/username/xxx"
• Tileset URL: "mapbox://tilesets/username/xxx"
• Dataset URL: "mapbox://datasets/username/xxx"

Come to think of it, I find many things about these IDs confusing. When you first start using Mapbox, you see the examples, with these lovely IDs "mapbox.streets-v6", then you create your own and it's "stevage.1mfv6cox" with no possibility of changing the ID to something more meaningful.

[andrewharvey]

Yeah I agree with you on all those points, but changes would need to be made Mapbox wide, Studio, help guides, and API documentation. At the moment I think all we can do on the Mapbox GL side is keep it consistent with Mapbox.com.

I think a lot is due to historical reasons, as the stack has evolved over time.

PS. you can create Tilesets with your own non random name as the ID using https://github.com/mapbox/mapbox-upload#cli-usage or https://github.com/mapbox/mapbox-cli-py#upload

[andrewharvey]

MapID is consistent with Mapbox Studio: https://www.mapbox.com/studio/tilesets/mapbox.mapbox-streets-v8/

Mapbox Studio now refers to this ID as a "Tileset ID", documentation change is proposed at #8915

[andrewharvey]

..., with these lovely IDs "mapbox.streets-v6", then you create your own and it's "stevage.1mfv6cox" with no possibility of changing the ID to something more meaningful.

PS. You can use something more meaningful when uploading with the API https://github.com/mapbox/mapbox-cli-py#upload