diff --git a/CHANGELOG.md b/CHANGELOG.md index 2326621..4814c67 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - PMTiles +- WMTS: REST request encoding - New property `wms:transparent` for WMS ### Changed diff --git a/README.md b/README.md index 777a3d7..d12da95 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ This document explains the Web Map Links Extension to the It allows to provide links to web map services for visualization purposes. The following services are supported: + - [3D Tiles](#3d-tiles) - [OGC WMS](#ogc-wms) - [OGC WMTS](#ogc-wmts) @@ -20,6 +21,7 @@ The following services are supported: - [XYZ](#xyz) Important resources in this extension: + - Examples: - [Item example](examples/item.json): Shows the basic usage of the extension in a STAC Item - [Collection example](examples/collection.json): Shows the basic usage of the extension in a STAC Collection @@ -74,22 +76,52 @@ Links to a [OGC Web Map Tile Service](https://www.ogc.org/standards/wmts) (WMTS) | 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 | string | **REQUIRED**. Link to the WMTS, without any WMTS specific parameters. | | href:servers | \[string] | See [href:servers](#hrefservers) 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\ | Any additional dimension parameters to add to the request as key-value-pairs, usually added as query parameters. | +| wmts:layer | string\|\[string] | **REQUIRED**. The layers to show on the map, either a list of layer names (KVP only) or a single layer name (REST and KVP). | +| wmts:encoding | string | The WMTS request encoding, either `kvp` for [KVP](#kvp) or `rest`for [REST](#rest). Defaults to `kvp`. | + +**href**: -If you provide multiple array elements in `wmts:layer` (e.g. `["layerA", "layerB"]`), +- For REST encoding, the `href` must point to the capabilities document. +- For KVP encoding, the `href` points to the URL of the capabilities document without any query parameters. + 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`](#hrefservers) MUST be provided. + +**wmts:layer**: 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 REST-encoding only a single string can be provided. -#### href +#### KVP -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`. +This describes the key-value-pair (KVP) request encoding, +which uses query parameters to transmit additional parameters. -The `href` can contain an optional server placeholder `{s}`. If `{s}` is used, the field [`href:servers`](#hrefservers) MUST be provided. +| Field Name | Type | Description | +| --------------- | -------------------- | ----------- | +| type | string | The media type to be used for the tile requests, e.g. `image/png` or `image/jpeg`. | +| wmts:encoding | string | If provided, must be set to `kvp`. | +| wmts:dimensions | Map\ | Any additional dimension parameters to add to the request as key-value-pairs (i.e. query parameters). | + +#### REST + +This describes the REST request encoding, which provides a URL template with variables. + +| Field Name | Type | Description | +| ------------- | ---------------- | ----------- | +| type | string | If provided, must be set to `application/xml`. | +| wmts:encoding | string | **REQUIRED**. Must be set to `rest`. | +| uriTemplate | string | Can override the URL template from the capabilities document with a custom version that can be customized with the `variables` provided. | +| variables | Map\ | This object contains one key per substitution variable in the `urlTemplate`. | + +**variables**: Each key defines the schema of one substitution variable using a JSON Schema fragmen +and can thus include things like the data type of the variable, enumerations, minimum values, maximum values, etc. +Note that clients may have varying capabilities to parse and hanle the schemas provided for the variables. +If you want to ensure that the WMTS can be easily read, stick to very simply schemas +(e.g., enums for strings, minimum/maximum values for numbers). +Providing a reasonable default value for all variables is recommended. +Variables with a constant value should be encoded directly in the URL without using a variable. ### PMTiles @@ -119,9 +151,7 @@ Links to a XYZ, also known as slippy map. | 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](#hrefservers) below for details. | -#### href - -For XYZ, the `href` is a templated URI. +**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`](#hrefservers) MUST be provided. All other parameters should be [hard-coded](https://github.com/stac-extensions/web-map-links/issues/2) with specific values, diff --git a/json-schema/schema.json b/json-schema/schema.json index edddfba..06a1fba 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -70,38 +70,77 @@ } }, "then": { - "required": [ - "wmts:layer" + "allOf": [ + { + "$ref": "#/definitions/servers" + } ], - "properties": { - "wmts:layer": { - "oneOf": [ - { - "type": "string", - "minLength": 1 - }, - { - "type": "array", - "minItems": 1, - "items": { + "if": { + "required": [ + "wmts:encoding" + ], + "properties": { + "wmts:encoding": { + "const": "rest" + } + } + }, + "then": { + "$comment": "REST request encoding", + "required": [ + "wmts:layer" + ], + "properties": { + "wmts:layer": { + "type": "string", + "minLength": 1 + }, + "wmts:encoding": { + "const": "rest" + }, + "uriTemplate": { + "type": "string", + "minLength": 1 + }, + "variables": { + "type": "object", + "description": "This object contains one key per substitution variable in the templated URL. Each key defines the schema of one substitution variable using a JSON Schema fragment and can thus include things like the data type of the variable, enumerations, minimum values, maximum values, etc." + } + } + }, + "else": { + "$comment": "KVP request encoding", + "required": [ + "wmts:layer" + ], + "properties": { + "wmts:layer": { + "oneOf": [ + { "type": "string", "minLength": 1 + }, + { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } } + ] + }, + "wmts:encoding": { + "const": "kvp" + }, + "wmts:dimensions": { + "type": "object", + "additionalProperties": { + "type": "string" } - ] - }, - "wmts:dimensions": { - "type": "object", - "additionalProperties": { - "type": "string" } } - }, - "allOf": [ - { - "$ref": "#/definitions/servers" - } - ] + } } }, {