v1.9.0 changelog (#2111)

- Bump version file
- Explicate schema license and other docs changes

Author: nvkelso

docs/CHANGELOG.md

@@ -0,0 +1,21 @@
+Copyright (c) 2015-2018 Mapzen
+Copyright (c) 2019 Linux Foundation
+
+# The MIT License (MIT)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

docs/LICENSE-SCHEMA.md

@@ -1,17 +1,28 @@
-# Mapzen Vector Tile documentation
+# Tilezen documentation
 
-This repository contains documentation for Mapzen's Vector Tile service.
+## Tilezen vector tile schema
+
+* [layers.md](layers.md) - Layers in the vector tile service detailed incuding available `kind` values and other tags.
+* [data-sources.md](data-sources.md) - Where does Tilezen's data come from?
+* [disputed-features.md](disputed-features.md) - How we handle dynamic viewpoints for disputed features.
+* [attribution.md](attribution.md) - Giving credit where credit is due, and when the data licence requires it.
+
+## Mapzen's Vector Tile service
+
+_NOTE: Mapzen's commercial service shut down in 2018. Limited tile access is available at [nextzen.org](https://www.nextzen.org/)_
 
 * [index.md](index.md) - This is where all the good stuff is.
 * [use-service.md](use-service.md) - Use the vector tile service, layers, and tile formats.
 * [api-keys-and-rate-limits.md](api-keys-and-rate-limits.md) - Don't ruin a good thing.
 * [display-tiles.md](display-tiles.md) - Display vector tiles in a map in Tangram, MapboxGL, D3, and other frameworks.
-* [layers.md](layers.md) - Layers in the vector tile service detailed incuding available `kind` values and other tags.
-* [data-sources.md](data-sources.md) - Where does Mapzen's data come from?
-* [disputed-features.md](disputed-features.md) - How we handle dynamic viewpoints for disputed features.
 * [http-status-codes.md](http-status-codes.md) - HTTP status codes.
-* [attribution.md](attribution.md) - Giving credit where credit is due, and the data licence requires it.
 
 ## Contributing
 
 If you have any comments on the documentation, you can drop a note as a GitHub issue, or fork it and add your own exercises.
+
+## Licenses
+
+- The Tilezen vector tile schema is [MIT](LICENSE-SCHEMA.md)
+- The project documentation and Tilezen vector tile schema documentation is [CC-BY 4.0](LICENSE-DOCS.md)
+- The code and all other material to generate the tiles is [MIT](LICENSE.md)

docs/README.md

@@ -251,9 +251,9 @@ Combination of OpenStreetMap administrative boundaries (zoom >= 8) and Natural E
 
 When there is a **boundary dispute** between two countries, the default boundary between them is generally shown according to the _de facto_ status marking where one country's on the ground administration ends and another's begins. The boundary line itself is marked `disputed`, and the extend of the other country's claim is tagged with one of `disputed_breakaway`, `disputed_claim`, `disputed_elusive`, and `disputed_reference_line`.
 
-Audiences in different countries may have different expectations and legal requirements so Tilezen optionally supports _de jure_ boundary viewpoints with `kind:xx` properties, where `xx` is a lower-cased [ISO 3166-1 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) with support for `ar`, `bd`, `br`, `cn`, `de`, `eg`, `es`, `fr`, `gb`, `gr`, `id`, `il`, `in`, `it`, `jp`, `ko`, `ma`, `nl`, `np`, `pk`, `pl`, `ps`, `pt`, `ru`, `sa`, `se`, `tr`, `tw`, `us`, `vn`. Use these properties to "turn off" `unrecognized_country` and `unrecognized_region` boundary lines, and restyle the claims as `country` and `region`. The range of values is the same as for `kind`, and should be used in conjunction with `kind` as `kind:xx` in a coalesce as it's only included when that country's viewpoint is different than the default. These should be paired with **places** layer viewpoint support for country and region capitals.
+Audiences in different countries may have different expectations and legal requirements so Tilezen optionally supports _de jure_ boundary viewpoints with `kind:xx` properties, where `xx` is a lower-cased [ISO 3166-1 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) with support for `ar`, `bd`, `br`, `cn`, `de`, `eg`, `es`, `fr`, `gb`, `gr`, `id`, `il`, `in`, `it`, `jp`, `ko`, `ma`, `nl`, `np`, `pk`, `pl`, `ps`, `pt`, `ru`, `sa`, `se`, `tr`, `tw`, `ua`, `us`, `vn`. Use these properties to "turn off" `unrecognized_country` and `unrecognized_region` boundary lines, and restyle the claims as `country` and `region`. The range of values is the same as for `kind`, and should be used in conjunction with `kind` as `kind:xx` in a coalesce as it's only included when that country's viewpoint is different than the default. These should be paired with **places** layer viewpoint support for country and region capitals.
 
-Some disputed boundaries, like the  [China 9-dashed line](https://en.wikipedia.org/wiki/Nine-dash_line), are marked `unrecognized_country` by default and are only available in a specific `kind:xx` viewpoint (in this case `kind:cn` and `kind:tw`).
+Some disputed boundaries, like the [China 9-dashed line](https://en.wikipedia.org/wiki/Nine-dash_line), are marked `unrecognized_country` by default and are only available in a specific `kind:xx` viewpoint (in this case `kind:cn` and `kind:tw`).
 
 ## Buildings and Addresses
 
@@ -268,7 +268,7 @@ Individual `building_part` geometries from OpenStreetMap following the [Simple 3
 
 Tilezen calculates the `landuse_kind` value by intercutting `buildings` with the `landuse` layer to determine if a building is over a parks, hospitals, universities or other landuse features. Use this property to modify the visual appearance of buildings over these features. For instance, light grey buildings look great in general, but aren't legible over most landuse colors unless they are darkened (or colorized to match landuse styling).
 
-Label position points may also have `closed` or `historical` kind_detail values if the original building name ended in "(closed)" or "(historical)", respectively. These points will have a `min_zoom` of 17, suggesting that they are suitable for display only at high zooms. _See related bug fix in [#1026](https://github.com/tilezen/vector-datasource/issues/1026)._
+Label position points may also have `closed` or `historical` `kind_detail` values if the original building name ended in "(closed)" or "(historical)", respectively. These points will have a `min_zoom` of 17, suggesting that they are suitable for display only at high zooms. _See related bug fix in [#1026](https://github.com/tilezen/vector-datasource/issues/1026)._
 
 Values for `kind_detail`  are sourced from OpenStreetMap's `building` tag for building footprints and from `building:part` tag for building parts.
 
@@ -278,6 +278,7 @@ Note that building geometries, like most geometries in Tilezen tiles, are clippe
 
 * `name`
 * `id`: from OpenStreetMap
+* `root_id`: so building parts can be associated back with their "root" building relation
 * `kind`: see below
 * `kind_detail`: see below
 * `source`: `openstreetmap.org`
@@ -869,7 +870,7 @@ The values of population rank are derived from the `population` value as follows
 * 1: Less than 200
 * 0: No `population` value available or `population` value zero.
 
-When available, for the largest cities, OSM localities gets their population_rank from NaturalEarth's `pop_max` tag because NaturalEarth `pop_max` is for the metro area and is more useful for label grading in the stylesheet.
+When available, for the largest cities, OSM localities gets their `population_rank` from NaturalEarth's `pop_max` tag because NaturalEarth `pop_max` is for the metro area and is more useful for label grading in the stylesheet.
 
 ## Points of Interest
 
@@ -1705,7 +1706,7 @@ Network value include:
 * `CA:NT`
 * `CA:ON:primary`
 * `CA:ON:secondary`
-* `CA:PE`
+* `CA:PE` (NOTE: was `CA:PEI` in error before)
 * `CA:QC:A`
 * `CA:QC:R`
 * `CA:SK:primary`
@@ -2487,12 +2488,15 @@ Tilezen calculates the composite exterior edge for overlapping water polygons an
 * `id`: OpenStreetMap feature `osm_id`, when sourced from `openstreetmap.org`
 * `is_tunnel`: for `line` features only (`true` values only)
 * `wikidata_id`: when present, the [Wikidata](https://www.wikidata.org) ID corresponding to this feature.
+* `alkaline`: boolean
+* `intermittent`: boolean
+* `reservoir`: boolean
 
 #### Water `kind` values:
 
 * `basin` - polygon
 * `bay` - point, intended for label placement only. With `tile_kind_rank`, see below.
-* `canal` - line
+* `canal` - line, can also indicate `boat: true` when navigable by a vessel
 * `ditch` - line
 * `dock` - polygon
 * `drain` - line
@@ -2522,12 +2526,12 @@ When `water` polygons are sourced from OpenStreetMap, we add `kind_detail` value
 * `river`
 * `stream`
 
-Additionally, a `reservoir: true` or `alkaline: true` value can be present on the appropriate `kind=lake` features. Intermittent water features that sometimes run dry or disappear seasonally are marked `intermittent: true`.
+Additionally, a `reservoir: true` or `alkaline: true` value can be present on the appropriate `kind=lake` features. Intermittent water features that sometimes run dry or disappear seasonally are marked `intermittent: true` (including implied infiltration and detention features).
 
 The kinds `bay`, `strait` and `fjord` are ranked by size and given a `kind_tile_rank` property that starts from 1 and counts up as the feature gets smaller. Note that the ranking is done on a "metatile", which means that each tile (of size 256px, 512px or other) won't necessarily contain the full range from 1 to N of `kind_tile_rank`s.
 
 **Gotchas:**
 
 * `lake` features with `alkaline: true` and `playa` features are sourced from Natural Earth at low zooms and are sparesly populated at high zooms from OpenStreetMap. Zooming in, your feature may disappear (when there is no equivalent in OpenStreetMap), or the feature may still exist as a water or lake polygon but without the alkaline indicator. Beware the desert around Great Salt Lake in Utah!
-* `lake` features from Natural Earth sometimes change to `water` features on zoom into OpenStreetMap data. _See planned bug fix in [#984](https://github.com/tilezen/vector-datasource/issues/984). However, kind_detail value is available._
+* `lake` features from Natural Earth sometimes change to `water` features on zoom into OpenStreetMap data. To work around this, also use `kind_detail` at high zooms.
 * Some of the minor kinds (like `bay`, `strait`, and `fjord`) are used for label_placement points only, as their area would duplicate water polygons already present from osmdata.openstreetmap.de.

docs/images/tilezen-v1d9-versus-v1d6-size-zooms.png

@@ -27,13 +27,14 @@
             "fields" : {
                 "name" : "String. Localized name variants are in properties like 'name:en'. Common value.",
                 "id" : "Number. Common value.",
-                "kind" : "String. Common value, one of: aboriginal_lands, country, county, disputed, disputed_breakaway, disputed_claim, disputed_elusive, disputed_reference_line, indefinite, indeterminate, lease_limit, line_of_control, macroregion, map_unit, municipality, overlay_limit, region.",
-                "kind:*": "String. Optional property for alternate points of view in boundaries layer with kind:* properties (like kind:iso). The following country and international organizations worldviews are supported: Argentina (ar), Bangladesh (bd), Brazil (br), China (cn), Egypt (eg), France (fr), Germany (de), Greece (gr), India (in), Indonesia (id), Israel (il), Italy (it), Japan (jp), Morocco (ma), Nepal (np), Netherlands (nl), Pakistan (pk), Palestine (ps), Poland (pl), Portugal (pt), Russia (ru), Saudi Arabia (sa), South Korea (ko), Spain (es), Sweden (se), Taiwan (tw), Turkey (tr), United Kingdom (gb), United States (us), Vietnam (vn), ISO (iso)",
+                "kind" : "String. Common value, one of: aboriginal_lands, country, county, disputed, disputed_breakaway, disputed_claim, disputed_elusive, disputed_reference_line, indefinite, indeterminate, lease_limit, line_of_control, macroregion, map_unit, municipality, overlay_limit, region, unrecognized_dispute.",
+                "kind:*": "String. Optional property for alternate points of view in boundaries layer with kind:* properties (like kind:iso). The following country and international organizations worldviews are supported: Argentina (ar), Bangladesh (bd), Brazil (br), China (cn), Egypt (eg), France (fr), Germany (de), Greece (gr), India (in), Indonesia (id), Israel (il), Italy (it), Japan (jp), Morocco (ma), Nepal (np), Netherlands (nl), Pakistan (pk), Palestine (ps), Poland (pl), Portugal (pt), Russia (ru), Saudi Arabia (sa), South Korea (ko), Spain (es), Sweden (se), Taiwan (tw), Turkey (tr), United Kingdom (gb), Ukraine (ua), United States (us), Vietnam (vn), ISO (iso)",
                 "min_zoom" : "Number. A suggested minimum zoom at which the features should become visible. Common value.",
                 "sort_rank" : "Integer. Suggestion for which order to draw features (lower values are bottom, bigger values on top). Common value.",
                 "collision_rank" : "Integer. Common property. Suggestion for which order labels should collide. Use as tie breaker with min_zoom.",
                 "area" : "Number. Common value.",
                 "admin_level" : "Common optional value, one of: 2, 4, 6, 8.",
+                "disputed_by" : "String. Optional property for alternate points of view in boundaries layer with kind:* properties (like kind:iso). The following country and international organizations worldviews are supported: Argentina (ar), Bangladesh (bd), Brazil (br), China (cn), Egypt (eg), France (fr), Germany (de), Greece (gr), India (in), Indonesia (id), Israel (il), Italy (it), Japan (jp), Morocco (ma), Nepal (np), Netherlands (nl), Pakistan (pk), Palestine (ps), Poland (pl), Portugal (pt), Russia (ru), Saudi Arabia (sa), South Korea (ko), Spain (es), Sweden (se), Taiwan (tw), Turkey (tr), United Kingdom (gb), Ukraine (ua), United States (us), Vietnam (vn), ISO (iso)",
                 "id:left" : "Integer. For the relation on the left side of the boundary line. Common optional value.",
                 "id:right" : "Integer. For the relation on the right side of the boundary line. Common optional value.",
                 "name:left" : "See name section above, other variants like `old_name` also supported. Common optional value.",
@@ -150,6 +151,7 @@
                 "aeroway" : "String. Common optional value.",
                 "attraction" : "String. Common optional value.",
                 "cuisine" : "String. Common optional value.",
+                "direction" : "generally only for viewpoint and other oriented features. Expressed as an integer in range of 0-359, where 0 is equal to north, using a clockwise rotation of the main direction.",
                 "drives_on_left" : "Boolean. Common optional value.",
                 "exit_to" : "String. Only for highway exits. Common optional value.",
                 "ref" : "generally only for `gate` and `station_entrance` features. Optional value.",
@@ -244,6 +246,8 @@
                 "ski" : "String. For ski pistes. Optional value.",
                 "snowshoe" : "String. For ski pistes. Optional value.",
                 "sport" : "String. Optional value.",
+                "shield_text"  : "String. Contains text to display on a shield. For example, I 90 would have a network of US:I and a shield_text of 90. For some roads, this can include non-numeric characters, for example the M1 motorway in the UK will have a shield_text of M1, rather than just 1. Whitepsace, punctuation, and prefixes are generally stripped. Common optional value.",
+                "shield_text_length"  : "String. The length of the shield_text field as a string.  E.g. if shield_text is 12345, shield_text_length would be 5. Missing if shield_text is !(0 < length < 7) or field doesn't exist. Common optional value.",
                 "state" : "String. Optional value.",
                 "symbol" : "String. For ski pistes. Optional value.",
                 "toll" : "Boolean. Optional value.",
@@ -289,14 +293,18 @@
             "fields" : {
                 "name" : "String. Localized name variants are in properties like 'name:en'. Common value.",
                 "kind" : "String. detailed below, per geometry type. Common value, one of: basin, bay, canal, dam, ditch, dock, drain, fjord, fountain, lake, ocean, playa, reef, river, riverbank, sea, strait, stream, swimming_pool, water.",
+                "kind_detail" : "String. Common optional value, one of: basin, canal, ditch, drain, lake, river, and stream.",
                 "source" : "String. Common value, one of: naturalearthdata.com, osmdata.openstreetmap.de, openstreetmap.org.",
                 "min_zoom" : "Number. A suggested minimum zoom at which the features should become visible. Common value.",
                 "boundary" : "Boolean. For line geometries only. Common value.",
                 "sort_rank" : "Integer. Suggestion for which order to draw features (lower values are bottom, bigger values on top). Common value.",
                 "collision_rank" : "Integer. Common property. Suggestion for which order labels should collide. Use as tie breaker with min_zoom.",
                 "area" : "in square meters (spherical Mercator, no real-world), `polygon` features only. Common optional value.",
                 "id" : "OpenStreetMap feature `osm_id`, when sourced from `openstreetmap.org`. Common optional value.",
-                "is_tunnel" : "for `line` features only (`true` values only). Common optional value."
+                "is_tunnel" : "Boolean (`true` values only), for `line` features only. Common optional value.",
+                "alkaline" : "Boolean  features only (`true` values only). Common optional value.",
+                "intermittent" : "Boolean  (`true` values only). Common optional value.",
+                "reservoir" : "Boolean (`true` values only). Common optional value."
             },
             "maxzoom" : 16.0,
             "minzoom" : 0.0,