Indicate which properties and layers are optional

[nvkelso]

Right now the documentation doesn't indicate when layers are optional (often people request no water layer to consider the map background water and fill earth over it), and some times properties Tilezen considers common are OSM data specific and don't interoperate well with non-OSM sources, and better document that the kind values are similarly the ones to use when the data is present in another non-OSM source but if it's not in the other source it's okay to not include it. Another way of saying this is promises about the Mapzen production service were made in the Tilezen schema version docs that should be disentangled from Mapzen (RIP).

This probably is a v2.0 breaking change so adding that label.

[musculman]

From my point of view, I see two different topics that can be probably addressed separately in parallel.

1. improve documentation and mention what is optional, what is mandatory and so on
2. adapt documentation for non-OSM data sources

The first one can be tackled by adding more information about every property, layer and set of properties.

The second one requires more thought as it needs to not only cover the optional and non optional data; but also explain extensively all the properties and what exactly do they mean, as well as possible alternatives in case the data is not available.
Some other properties simply require a documentation update, for example, id, it usually mentions that it is the id of OSM, but of course for non-OSM will be something else. Not to mention the kind values, which vary wildly between data providers.
Also for people not familiar with OSM it will be good to include examples as well of what does every property mean, as sometimes it is not really clear and there are almost no examples provided.

[zerebubuth]

I think we still have a large number of "passed through"† values from OSM, which I'd like to make sure are whitelisted. Covering all the kind, kind_detail and other categorised values with documented whitelists would make it easier for other providers to map onto those lists.

Some properties, such as name and shield_text, are free-text whereas others are numbers (of some unit) or categorised values. We document many of these at the moment, but it would be helpful to make sure that documentation is complete - and perhaps automatic and testable. The draft 3.0 of TileJSON has something very similar called vector_layers, which we could follow and extend to allow for type information and category enumeration.

†: E.g: the sport property on POIs or detail properties on kind: cemetery.