/web-map-links

Allows to provide links to web maps for visualization purposes. Currently, OGC WMTS and XYZ are supported.

Apache License 2.0Apache-2.0

Web Map Links Extension Specification

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:

Link Object Fields

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 via the attribution field as defined in OGC API - Commons - Part 1.

OGC WMTS

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 Recommended to be set to the media type the Capabilities document, usually application/xml.
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.

href

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.

XYZ

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.

href

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.

TileJSON

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

General

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.

href:servers

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"].

Contributing

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.

Running tests

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 install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This 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