Merge pull request #21 from mapbox/v2.2.0

v2.2.0

2.2.0/README-zh.md

@@ -0,0 +1,113 @@
+# TileJSON 2.2.0
+
+本文档中的“**必须**”、“**必须不**”、“**必备**”、"**应该**"、“**不应该**”、“**建议**”、“**可以**”、“**可选**”的含义参照[RFC 2119](https://www.ietf.org/rfc/rfc2119.txt)。
+
+## 1. 目的
+
+本规范提出一种技术标准，来描述多种类型的网络地图图层的元数据信息，以方便客户端进行配置和浏览。
+
+
+## 2. 文件格式
+
+TileJSON描述文件采用JSON格式，参见RFC 4627。
+
+
+本规范的实现**必须**忽略掉未知key。但是，实现**必须**在他们的API中暴露出
+这些未知的key/values，使得API用户可以选择性地处理这些keys。
+实现**必须**忽略keys的无效values。如果key是必选的，实现**必须**认为整个
+TileJSON描述文件无效并且拒绝进一步处理。
+
+
+```javascript
+{
+    // **必选**。表示语义化的版本号。描述本JSON对象所遵守的TileJSON版本。
+    "tilejson": "2.1.0",
+
+    // **可选**。默认值：null。表示瓦片集的名称。名称可以是任何合法字符。
+    // 实现**不应该**将此名称当做HTML来解析。
+    "name": "compositing",
+
+    // **可选**。默认值：null。表示瓦片集的描述信息。描述可以是任何合法字符。
+    // 实现**不应该**将此描述当做HTML来解析。
+    "description": "A simple, light grey world.",
+
+    // **可选**。默认值："1.0.0"。表示语义化的版本号。当瓦片发生更改时，次版本号
+    // **必须**相应地更改。这可能导致标签的变化。因此，实现方能够在次版本号变化时
+    // 清除缓存。更新级别的更改，**必须**限制在单块瓦片之内。
+    // 当瓦片更改较大时，主版本号**必须**增加。
+    // 实现**必须不**要使用不同主版本号的瓦片。
+    "version": "1.0.0",
+
+    // **可选**。默认值：null。包含地图的所有者信息。
+    // 实现**可以**把这部分内容当做HTML或者纯文本。
+    // 处于安全方面的原因，要绝对确保本字段的不会被用来进行XSS攻击或beacon跟踪。
+    "attribution": "<a href='http://openstreetmap.org'>OSM contributors</a>",
+
+    // **可选**。默认值：null。包含一个mustache模板，用来格式化grids数据来完成交互。
+    // 参见https://github.com/mapbox/utfgrid-spec/tree/master/1.2的交互部分。
+    "template": "{{#__teaser__}}{{NAME}}{{/__teaser__}}",
+
+    // **可选**。默认值：null。包含地图图例信息。
+    // 实现**可以**把这部分内容当做HTML或者纯文本。
+    // 处于安全方面的原因，要绝对确保本字段的不会被用来进行XSS攻击或beacon跟踪。
+    "legend": "Dangerous zones are red, safe zones are green",
+、
+    // **可选**。默认值："xyz"。可以是"xyz"或"tms"。主要影响瓦片坐标的y轴方向。
+    // 默认为global-mercator(Spherical Mercator)坐标系。
+    "scheme": "xyz",
+
+    // **必选**。表示一组瓦片资源。
+    // 如果存在{z}、{x}和{y}，它们将会被相应的整数替换。
+    // 如果指定了多个资源，客户端可以使用任意的资源组合。
+    // 所有的资源**必须**为相同的URL返回相同的内容。
+    // 本数组**必须**至少包含一个资源。
+    "tiles": [
+        "http://localhost:8888/admin/1.0.0/world-light,broadband/{z}/{x}/{y}.png"
+    ],
+
+    // **可选**。默认值：[]。表示一组交互资源。
+    // 如果存在{z}、{x}和{y}，它们将会被相应的整数替换。
+    // 如果指定了多个资源，客户端可以使用任意的资源组合。
+    // 所有的资源**必须**为相同的URL返回相同的内容。
+    // 如果本数组没有任何内容，那么说明本瓦片集不支持交互数据。
+    // 参见https://github.com/mapbox/utfgrid-spec/tree/master/1.2的交互部分
+    "grids": [
+        "http://localhost:8888/admin/1.0.0/broadband/{z}/{x}/{y}.grid.json"
+    ],
+
+    // **可选**。默认值：[]。表示一组GeoJSON格式的数据文件。
+    // 如果存在{z}、{x}和{y}，它们将会被相应的整数替换。
+    // 如果指定了多个资源，客户端可以使用任意的资源组合。
+    // 所有的资源**必须**为相同的URL返回相同的内容。
+    // 如果本数组没有任何内容，那么地图上不会呈现数据内容。
+    "data": [
+        "http://localhost:8888/admin/data.geojson"
+    ],
+
+    // **可选**。默认值：0。值域范围[0, 30]。
+    // 表示最小缩放级别的一个整数。
+    "minzoom": 0,
+
+    // **可选**。默认值：30。值域范围[0, 30]。
+    // 表示最大缩放级别的一个整数。**必须**大于等于minzoom
+    "maxzoom": 11,
+
+    // 表示地图瓦片的最大范围。这个范围**必须**覆盖到所有的缩放级别。
+    // 范围用WGS84坐标系下的经纬度来表示，顺序为左、下、右、上。
+    // 范围值可能是整数或者浮点数。
+    "bounds": [ -180, -85.05112877980659, 180, 85.0511287798066 ],
+
+    // **可选**。默认值：null。
+    // 第一个值是经度，第二个是纬度（都为WGS84坐标系），第三个是表示缩放级别的整数。
+    // 经度和纬度**必须**在bounds范围内。缩放级别**必须**在minzoom和maxzoom之间。
+    // 实现可以根据这个值设置地图的默认显示位置。
+    // 如果这个值为null，实现可以根据自己的算法自行决定默认位置。
+    "center": [ -76.275329586789, 39.153492567373, 8 ]
+}
+```
+
+
+## 3. 缓存
+
+客户端**可以**缓存从远程服务器获取的文件。当实现决定采用缓存措施时，**必须**
+遵从为瓦片数据和TileJSON描述文件定义的有效HTTP缓存控制头。

2.2.0/README.md

@@ -0,0 +1,137 @@
+# TileJSON 2.2.0
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
+this document are to be interpreted as described in RFC 2119.
+
+## 1. Purpose
+
+This specification attempts to create a standard for representing
+metadata about multiple types of web-based layers, to aid clients
+in configuration and browsing.
+
+## 2. File format
+
+TileJSON manifest files use the JSON format as described in RFC 4627.
+
+Implementations MUST treat unknown keys as if they weren't present.
+However, implementations MUST expose unknown key/values in their API
+so that API users can optionally handle these keys. Implementations MUST
+treat invalid values for keys as if they weren't present. If the key is
+required, implementations MUST treat the entire TileJSON manifest file
+as invalid and refuse operation.
+
+
+```javascript
+{
+    // REQUIRED. A semver.org style version number. Describes the version of
+    // the TileJSON spec that is implemented by this JSON object.
+    "tilejson": "2.1.0",
+
+    // OPTIONAL. Default: null. A name describing the tileset. The name can
+    // contain any legal character. Implementations SHOULD NOT interpret the
+    // name as HTML.
+    "name": "compositing",
+
+    // OPTIONAL. Default: null. A text description of the tileset. The
+    // description can contain any legal character. Implementations SHOULD NOT
+    // interpret the description as HTML.
+    "description": "A simple, light grey world.",
+
+    // OPTIONAL. Default: "1.0.0". A semver.org style version number. When
+    // changes across tiles are introduced, the minor version MUST change.
+    // This may lead to cut off labels. Therefore, implementors can decide to
+    // clean their cache when the minor version changes. Changes to the patch
+    // level MUST only have changes to tiles that are contained within one tile.
+    // When tiles change significantly, the major version MUST be increased.
+    // Implementations MUST NOT use tiles with different major versions.
+    "version": "1.0.0",
+
+    // OPTIONAL. Default: null. Contains an attribution to be displayed
+    // when the map is shown to a user. Implementations MAY decide to treat this
+    // as HTML or literal text. For security reasons, make absolutely sure that
+    // this field can't be abused as a vector for XSS or beacon tracking.
+    "attribution": "<a href='http://openstreetmap.org'>OSM contributors</a>",
+
+    // OPTIONAL. Default: null. Contains a mustache template to be used to
+    // format data from grids for interaction.
+    // See https://github.com/mapbox/utfgrid-spec/tree/master/1.2
+    // for the interactivity specification.
+    "template": "{{#__teaser__}}{{NAME}}{{/__teaser__}}",
+
+    // OPTIONAL. Default: null. Contains a legend to be displayed with the map.
+    // Implementations MAY decide to treat this as HTML or literal text.
+    // For security reasons, make absolutely sure that this field can't be
+    // abused as a vector for XSS or beacon tracking.
+    "legend": "Dangerous zones are red, safe zones are green",
+
+    // OPTIONAL. Default: "xyz". Either "xyz" or "tms". Influences the y
+    // direction of the tile coordinates.
+    // The global-mercator (aka Spherical Mercator) profile is assumed.
+    "scheme": "xyz",
+
+    // REQUIRED. An array of tile endpoints. {z}, {x} and {y}, if present,
+    // are replaced with the corresponding integers. If multiple endpoints are specified, clients
+    // may use any combination of endpoints. All endpoints MUST return the same
+    // content for the same URL. The array MUST contain at least one endpoint.
+    "tiles": [
+        "http://localhost:8888/admin/1.0.0/world-light,broadband/{z}/{x}/{y}.png"
+    ],
+
+    // OPTIONAL. Default: []. An array of interactivity endpoints. {z}, {x}
+    // and {y}, if present, are replaced with the corresponding integers. If multiple
+    // endpoints are specified, clients may use any combination of endpoints.
+    // All endpoints MUST return the same content for the same URL.
+    // If the array doesn't contain any entries, interactivity is not supported
+    // for this tileset.
+    // See https://github.com/mapbox/utfgrid-spec/tree/master/1.2
+    // for the interactivity specification.
+    "grids": [
+        "http://localhost:8888/admin/1.0.0/broadband/{z}/{x}/{y}.grid.json"
+    ],
+
+    // OPTIONAL. Default: []. An array of data files in GeoJSON format.
+    // {z}, {x} and {y}, if present,
+    // are replaced with the corresponding integers. If multiple
+    // endpoints are specified, clients may use any combination of endpoints.
+    // All endpoints MUST return the same content for the same URL.
+    // If the array doesn't contain any entries, then no data is present in
+    // the map.
+    "data": [
+        "http://localhost:8888/admin/data.geojson"
+    ],
+
+    // OPTIONAL. Default: 0. >= 0, <= 30.
+    // An integer specifying the minimum zoom level.
+    "minzoom": 0,
+
+    // OPTIONAL. Default: 30. >= 0, <= 30.
+    // An integer specifying the maximum zoom level. MUST be >= minzoom.
+    "maxzoom": 11,
+
+    // OPTIONAL. Default: [-180, -90, 180, 90].
+    // The maximum extent of available map tiles. Bounds MUST define an area
+    // covered by all zoom levels. The bounds are represented in WGS:84
+    // latitude and longitude values, in the order left, bottom, right, top.
+    // Values may be integers or floating point numbers.
+    "bounds": [ -180, -85.05112877980659, 180, 85.0511287798066 ],
+
+    // OPTIONAL. Default: null.
+    // The first value is the longitude, the second is latitude (both in
+    // WGS:84 values), the third value is the zoom level as an integer.
+    // Longitude and latitude MUST be within the specified bounds.
+    // The zoom level MUST be between minzoom and maxzoom.
+    // Implementations can use this value to set the default location. If the
+    // value is null, implementations may use their own algorithm for
+    // determining a default location.
+    "center": [ -76.275329586789, 39.153492567373, 8 ]
+}
+```
+
+
+## 3. Caching
+
+Clients MAY cache files retrieved from a remote server.
+When implementations decide to perform caching, they MUST honor valid
+cache control HTTP headers as defined in the HTTP specification for both
+tile images and the TileJSON manifest file.

2.2.0/example/osm.layer

@@ -0,0 +1,16 @@
+{
+    "tilejson": "1.0.0",
+    "name": "OpenStreetMap",
+    "description": "A free editable map of the whole world.",
+    "version": "1.0.0",
+    "attribution": "(c) OpenStreetMap contributors, CC-BY-SA",
+    "scheme": "xyz",
+    "tiles": [
+        "http://a.tile.openstreetmap.org/${z}/${x}/${y}.png",
+        "http://b.tile.openstreetmap.org/${z}/${x}/${y}.png",
+        "http://c.tile.openstreetmap.org/${z}/${x}/${y}.png"
+    ],
+    "minzoom": 0,
+    "maxzoom": 18,
+    "bounds": [ -180, -85, 180, 85 ]
+}

2.2.0/schema.json

@@ -0,0 +1,73 @@
+{
+    "name": "TileJSON",
+    "type": "object",
+    "properties": {
+        "tilejson": {
+            "type": "string",
+            "pattern": "\\d+\\.\\d+\\.\\d+\\w?[\\w\\d]*"
+        },
+        "name": {
+            "type": "string"
+        },
+        "description": {
+            "type": "string"
+        },
+        "version": {
+            "type": "string",
+            "pattern": "\\d+\\.\\d+\\.\\d+\\w?[\\w\\d]*"
+        },
+        "attribution": {
+            "type": "string"
+        },
+        "template": {
+            "type": "string"
+        },
+        "legend": {
+            "type": "string"
+        },
+        "scheme": {
+            "type": "string"
+        },
+        "tiles": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
+        },
+        "grids": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
+        },
+        "data": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
+        },
+        "minzoom": {
+            "minimum": 0,
+            "maximum": 30,
+            "type": "integer"
+        },
+        "maxzoom": {
+            "minimum": 0,
+            "maximum": 30,
+            "type": "integer"
+        },
+        "bounds": {
+            "type": "array",
+            "items": {
+                "type": "number"
+            }
+        },
+        "center": {
+            "type": "array",
+            "items": {
+                "type": "number"
+            }
+        }
+    },
+    "required": ["tilejson", "tiles"]
+}