- Title: Web Map Links
- Identifier: https://stac-extensions.github.io/web-map-links/v1.2.0/schema.json
- Field Name Prefix: none, but each relation type has potentially a distinct prefix for additional data (e.g.
wmtsandxyz) - Scope: Item, Catalog, Collection
- Extension Maturity Classification: Proposal
- Owner: @m-mohr
This document explains the Web Map Links Extension to the SpatioTemporal Asset Catalog (STAC) specification. It allows to provide links to web map services for visualization purposes.
The following services are supported:
Important resources in this extension:
- Examples:
- Item example: Shows the basic usage of the extension in a STAC Item
- Collection example: Shows the basic usage of the extension in a STAC Collection
- JSON Schema
- Changelog
This extension only extends the Link Object
used in all STAC entities (Catalogs, Collections, Items). It requires specific relation types to be set for the rel field in the
Link Object.
An attribution field is not defined as part of this extension, but it is RECOMMENDED to provide an attribution
in the top-level object of the document (in the properties for Items) via the attribution field as defined in
OGC API - Commons - Part 1.
Links to a 3D Tiles implementation (versions 1.x).
| Field Name | Type | Description |
|---|---|---|
| rel | string | REQUIRED. Must be set to 3d-tiles. |
| href | string | REQUIRED. Link to a tileset. |
| type | string | Recommended to be set to application/json. |
Links to a OGC Web Map Service (WMS) implementation (versions 1.3.0). Only (tiled) "Basic WMS" is supported at this time.
| Field Name | Type | Description |
|---|---|---|
| rel | string | REQUIRED. Must be set to wms. |
| href | string | REQUIRED. Link to the WMS, without any WMS specific query parameters. |
| type | string | The media type to be used for the tile requests, e.g. image/png or image/jpeg. |
| wms:layers | [string] | REQUIRED. The layers to show on the map by default. Can't be empty. |
| wms:styles | [string] | The styles to show on the map by default. If not provided or empty, an empty string will be used for the query parameter. |
| wms:dimensions | Map<string, string> | Any additional dimension parameters to add to the request as query parameters (e.g. the dimensions TIME or ELEVATION). |
| wms:transparent | boolean | Sets whether the layers should be rendered transparent or not. Default: false |
If you provide multiple array elements in wms:layers (e.g. ["layerA", "layerB"]),
each should occur in a separate layer in the mapping library so that requests for the layers are sent.
If you want to send multiple layers in a single request, provide them as a string with comma-separated values: ["layerA,layerB"].
wms:layers and wms:styles work in parallel, so the first style in the array will be used for the first layer, etc.
Links to a OGC Web Map Tile Service (WMTS) implementation (versions 1.x).
| Field Name | Type | Description |
|---|---|---|
| rel | string | REQUIRED. Must be set to wmts. |
| href | string | REQUIRED. Link to the WMTS, without any WMTS specific query parameters. |
| type | string | The media type to be used for the tile requests, e.g. image/png or image/jpeg. |
| href:servers | [string] | See href:servers below for details. |
| wmts:layer | string|[string] | REQUIRED. The layers to show on the map by default, either a list of layer names or a single layer name. |
| wmts:dimensions | Map<string, string> | Any additional dimension parameters to add to the request as key-value-pairs, usually added as query parameters. |
If you provide multiple array elements in wmts:layer (e.g. ["layerA", "layerB"]),
each should occur in a separate layer in the mapping library so that individual requests for the layers are sent.
For WMTS, the href is pointing to the URL of the Capabilities document, but without the query parameters for the Capabilities request.
So if your Capabilities can be requested from https://example.com/geoserver/service/wmts?service=wmts&request=GetCapabilities
you'd provide https://example.com/geoserver/service/wmts as href.
The href can contain an optional server placeholder {s}. If {s} is used, the field href:servers MUST be provided.
Links to a PMTiles file (versions 3.x).
| Field Name | Type | Description |
|---|---|---|
| rel | string | REQUIRED. Must be set to pmtiles. |
| href | string | REQUIRED. Link to a PMTiles file (usually ends with .pmtiles). |
| type | string | Recommended to be set to application/vnd.pmtiles. |
| pmtiles:layers | [string] | For vector tiles, the layers to show on the map by default. If not provided, it's up to the discretion of the implementation to choose a layer from the vector_layers in the PMTiles metadata. |
The Tile Type of the PMTiles data source can be read from the first 127 bytes of the the binary header.
It is typical to assume a tile size of 256x256 display (CSS) pixels for raster tiles and 512x512 display pixels for vector tiles. Tile sizes are not guaranteed to be uniform across an entire archive.
Links to a XYZ, also known as slippy map.
| Field Name | Type | Description |
|---|---|---|
| rel | string | REQUIRED. Must be set to xyz. |
| href | string | REQUIRED. Link to the XYZ as a templated URI. |
| type | string | Recommended to be set to the image file type the XYZ returns by default, usually image/png or image/jpeg. |
| href:servers | [string] | See href:servers below for details. |
For XYZ, the href is a templated URI.
It MUST include the following placeholders: {x}, {y} and {z} and MAY include a placeholder for the server: {s}.
If {s} is used, the field href:servers MUST be provided.
All other parameters should be hard-coded with specific values,
e.g. the {r} parameter in Leaflet could be replaced by 2x.
Links to a TileJSON document.
| Field Name | Type | Description |
|---|---|---|
| rel | string | REQUIRED. Must be set to tilejson. |
| href | string | REQUIRED. Link to the valid TileJSON document. |
| type | string | Recommended to be set to application/json. |
The following field applies to multiple types of web mapping services:
| Field Name | Type | Description |
|---|---|---|
| href:servers | [string] | A list of replacement values for {s} in hrefs. |
This field is used to specify a set of URLs for a web mapping library so that requests can be sent to multiple servers, which can avoid request limits in web browsers.
The field is used across multiple types of web mapping services and applies currently to XYZ and WMTS.
It is REQUIRED if {s} is used in the href and then a list of at least 2 allowed values for the placeholder {s} must be provided.
If you only have a single value don't provide href:servers and instead hard-code the value into the href.
The implementations can expand the given values into multiple URLs.
For example, if you provide https://{s}/example as href and href:servers is ["a.com", "b.eu"]
you can expand that to ["https://a.com/example", "https://b.eu/example"].
All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.
The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid.
To run tests locally, you'll need npm, which is a standard part of any node.js installation.
First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:
npm installThen to check markdown formatting and test the examples against the JSON schema, you can run:
npm testThis will spit out the same texts that you see online, and you can then go and fix your markdown or examples.
If the tests reveal formatting problems with the examples, you can fix them with:
npm run format-examples