From d2142e74458744155af7bd035ae0688650b52c5a Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 16 Sep 2025 16:48:24 +0200 Subject: [PATCH 1/3] WMTS: REST request encoding --- CHANGELOG.md | 1 + README.md | 48 +++++++++++++++++++------ json-schema/schema.json | 77 ++++++++++++++++++++++++++++------------- 3 files changed, 91 insertions(+), 35 deletions(-) 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..fbf313e 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 @@ -77,19 +79,47 @@ Links to a [OGC Web Map Tile Service](https://www.ogc.org/standards/wmts) (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](#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:dimensions | Map\ | Any additional parameters for the request (see below). | +| wmts:encoding | string | Either `kvp` (see [KVP](#kvp)) or `rest` (see [REST](#rest)). Defaults to `KVP`. | -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. +The `href` can contain an optional server placeholder `{s}`. If `{s}` is used, the field [`href:servers`](#hrefservers) MUST be provided. + +#### KVP -#### href +This describes the key-value-pair (KVP) request encoding, +which uses query parameters to transmit additional parameters. -For WMTS, the `href` is pointing to the URL of the Capabilities document, but without the query parameters for the Capabilities request. +| Field Name | Type | Description | +| --------------- | -------------------- | ----------- | +| wmts:encoding | string | If provided, must be set to `kvp`. | +| 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. Will be added to the request as a query parameter. | +| wmts:dimensions | Map\ | Any additional dimension parameters to add to the request as key-value-pairs (i.e. query parameters). | + +**href**: For the KVP request encoding, 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`](#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. + +#### REST + +This describes the REST request encoding, which provides a URL template with variables. + +| Field Name | Type | Description | +| --------------- | -------------------- | ----------- | +| wmts:encoding | string | **REQUIRED**. Must be set to `rest`. | +| variables | Map\ | This object contains one key per substitution variable in the templated URL. | + +**href**: For the REST request encoding, the `href` is a URL template. +Variables with a constant value should be encoded directly in the URL without using a variable. + +**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). ### PMTiles @@ -119,9 +149,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..3e27a79 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -70,38 +70,65 @@ } }, "then": { - "required": [ - "wmts:layer" + "allOf": [ + { + "$ref": "#/definitions/servers" + } ], - "properties": { - "wmts:layer": { - "oneOf": [ - { - "type": "string", - "minLength": 1 - }, - { - "type": "array", - "minItems": 1, - "items": { + "if": { + "properties": { + "wmts:encoding": { + "const": "rest" + } + } + }, + "then": { + "$comment": "REST request encoding", + "properties": { + "wmts:encoding": { + "const": "rest" + }, + "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:encoding": { + "enum": [ + "kvp" + ] + }, + "wmts:layer": { + "oneOf": [ + { "type": "string", "minLength": 1 + }, + { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } } + ] + }, + "wmts:dimensions": { + "type": "object", + "additionalProperties": { + "type": "string" } - ] - }, - "wmts:dimensions": { - "type": "object", - "additionalProperties": { - "type": "string" } } - }, - "allOf": [ - { - "$ref": "#/definitions/servers" - } - ] + } } }, { From 6ccd8a7722822915abaf7111deb24fe00e425da6 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 16 Sep 2025 17:09:22 +0200 Subject: [PATCH 2/3] Update README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index fbf313e..ee1d5b2 100644 --- a/README.md +++ b/README.md @@ -120,6 +120,7 @@ and can thus include things like the data type of the variable, enumerations, mi 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. ### PMTiles From 256ff1b06509bf28025d4db9cbd6ab08e2902390 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 16 Sep 2025 21:11:26 +0200 Subject: [PATCH 3/3] Make REST auto-discoverable --- README.md | 45 +++++++++++++++++++++-------------------- json-schema/schema.json | 22 +++++++++++++++----- 2 files changed, 40 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index ee1d5b2..d12da95 100644 --- a/README.md +++ b/README.md @@ -76,13 +76,22 @@ 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:dimensions | Map\ | Any additional parameters for the request (see below). | -| wmts:encoding | string | Either `kvp` (see [KVP](#kvp)) or `rest` (see [REST](#rest)). Defaults to `KVP`. | +| 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**: -The `href` can contain an optional server placeholder `{s}`. If `{s}` is used, the field [`href:servers`](#hrefservers) MUST be provided. +- 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. #### KVP @@ -91,36 +100,28 @@ which uses query parameters to transmit additional parameters. | 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:layer | string\|\[string] | **REQUIRED**. The layers to show on the map by default, either a list of layer names or a single layer name. Will be added to the request as a query parameter. | | wmts:dimensions | Map\ | Any additional dimension parameters to add to the request as key-value-pairs (i.e. query parameters). | -**href**: For the KVP request encoding, 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`. - -**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. - #### REST This describes the REST request encoding, which provides a URL template with variables. -| Field Name | Type | Description | -| --------------- | -------------------- | ----------- | -| wmts:encoding | string | **REQUIRED**. Must be set to `rest`. | -| variables | Map\ | This object contains one key per substitution variable in the templated URL. | +| 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`. | -**href**: For the REST request encoding, the `href` is a URL template. -Variables with a constant value should be encoded directly in the URL without using a variable. - -**variables**: Each key defines the schema of one substitution variable using a JSON Schema fragmen +**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 diff --git a/json-schema/schema.json b/json-schema/schema.json index 3e27a79..06a1fba 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -76,6 +76,9 @@ } ], "if": { + "required": [ + "wmts:encoding" + ], "properties": { "wmts:encoding": { "const": "rest" @@ -84,10 +87,21 @@ }, "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." @@ -100,11 +114,6 @@ "wmts:layer" ], "properties": { - "wmts:encoding": { - "enum": [ - "kvp" - ] - }, "wmts:layer": { "oneOf": [ { @@ -121,6 +130,9 @@ } ] }, + "wmts:encoding": { + "const": "kvp" + }, "wmts:dimensions": { "type": "object", "additionalProperties": {