Skip to content

Commit 203e8fb

Browse files
m-mohrm-mohr
authored
WMTS: REST request encoding (#28)
* WMTS: REST request encoding * Update README.md * Make REST auto-discoverable * Improve description of variables object * Update README.md * Clarify Tile-variables, add WMTS REST example
1 parent 5b524c1 commit 203e8fb

File tree

5 files changed

+174
-41
lines changed

5 files changed

+174
-41
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99
### Added
1010

1111
- PMTiles
12+
- WMTS: REST request encoding
1213
- New property `wms:transparent` for WMS
1314

1415
### Changed

‎README.md‎

Lines changed: 52 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ This document explains the Web Map Links Extension to the
1212
It allows to provide links to web map services for visualization purposes.
1313

1414
The following services are supported:
15+
1516
- [3D Tiles](#3d-tiles)
1617
- [OGC WMS](#ogc-wms)
1718
- [OGC WMTS](#ogc-wmts)
@@ -20,6 +21,7 @@ The following services are supported:
2021
- [XYZ](#xyz)
2122

2223
Important resources in this extension:
24+
2325
- Examples:
2426
- [Item example](examples/item.json): Shows the basic usage of the extension in a STAC Item
2527
- [Collection example](examples/collection.json): Shows the basic usage of the extension in a STAC Collection
@@ -74,22 +76,61 @@ Links to a [OGC Web Map Tile Service](https://www.ogc.org/standards/wmts) (WMTS)
7476
| Field Name | Type | Description |
7577
| --------------- | -------------------- | ----------- |
7678
| rel | string | **REQUIRED**. Must be set to `wmts`. |
77-
| href | string | **REQUIRED**. Link to the WMTS, without any WMTS specific query parameters. |
78-
| type | string | The media type to be used for the tile requests, e.g. `image/png` or `image/jpeg`. |
79+
| href | string | **REQUIRED**. Link to the WMTS, without any WMTS specific parameters. |
7980
| href:servers | \[string] | See [href:servers](#hrefservers) below for details. |
80-
| 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. |
81-
| wmts:dimensions | Map\<string, string> | Any additional dimension parameters to add to the request as key-value-pairs, usually added as query parameters. |
81+
| 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). |
82+
| wmts:encoding | string | The WMTS request encoding, either `kvp` for [KVP](#kvp) or `rest`for [REST](#rest). Defaults to `kvp`. |
83+
84+
**href**:
8285

83-
If you provide multiple array elements in `wmts:layer` (e.g. `["layerA", "layerB"]`),
86+
- For REST encoding, the `href` must point to the capabilities document.
87+
- For KVP encoding, the `href` points to the URL of the capabilities document without any query parameters.
88+
So if your Capabilities can be requested from `https://example.com/geoserver/service/wmts?service=wmts&request=GetCapabilities`
89+
you'd provide `https://example.com/geoserver/service/wmts` as `href`.
90+
- The `href` can contain an optional server placeholder `{s}`. If `{s}` is used, the field [`href:servers`](#hrefservers) MUST be provided.
91+
92+
**wmts:layer**: If you provide multiple array elements in `wmts:layer` (e.g. `["layerA", "layerB"]`),
8493
each should occur in a separate layer in the mapping library so that individual requests for the layers are sent.
94+
For REST-encoding only a single string can be provided.
95+
96+
#### KVP
97+
98+
This describes the key-value-pair (KVP) request encoding,
99+
which uses query parameters to transmit additional parameters.
100+
101+
| Field Name | Type | Description |
102+
| --------------- | -------------------- | ----------- |
103+
| type | string | The media type to be used for the tile requests, e.g. `image/png` or `image/jpeg`. |
104+
| wmts:encoding | string | If provided, must be set to `kvp`. |
105+
| wmts:dimensions | Map\<string, string> | Any additional dimension parameters to add to the request as key-value-pairs (i.e. query parameters). |
106+
107+
#### REST
85108

86-
#### href
109+
This describes the REST request encoding, which provides a URL template with variables.
87110

88-
For WMTS, the `href` is pointing to the URL of the Capabilities document, but without the query parameters for the Capabilities request.
89-
So if your Capabilities can be requested from `https://example.com/geoserver/service/wmts?service=wmts&request=GetCapabilities`
90-
you'd provide `https://example.com/geoserver/service/wmts` as `href`.
111+
| Field Name | Type | Description |
112+
| ------------- | ---------------- | ----------- |
113+
| type | string | If provided, must be set to `application/xml`. |
114+
| wmts:encoding | string | **REQUIRED**. Must be set to `rest`. |
115+
| uriTemplate | string | Can override the URL template from the capabilities document with a custom version that can be customized with the `variables` provided. |
116+
| variables | Map\<string, \*> | This object contains one key per substitution variable in the `urlTemplate`. |
91117

92-
The `href` can contain an optional server placeholder `{s}`. If `{s}` is used, the field [`href:servers`](#hrefservers) MUST be provided.
118+
**variables**: This object may provide a JSON Schema definition for any variable defined in the `uriTemplate`,
119+
allowing to provide the default value for the specific STAC resource or the specification of ranges or other constraints.
120+
121+
The variables `{TileMatrixSet}`, `{TileMatrix}`, `{TileRow}`, `{TileCol}` do not need to be provided
122+
explicitly in the `variables` as they can be determined from the capabilities.
123+
Nevertheless, the corresponding variables can be provided if they should be further restricted to certain values or other contraints.
124+
125+
Providing a reasonable default value for all variables is strongly recommended as they
126+
are likely to be used for a default visualization.
127+
Additional information such as the data type of the variable, enumerations, minimum values, maximum values, etc.
128+
can be provided for creating interactive UIs where the user can select values depending on the schema.
129+
Note that clients may have varying capabilities to parse and handle the schemas provided for the variables.
130+
If you want to ensure that the WMTS can be easily read, stick to very simple schemas
131+
(e.g., enums for strings, minimum/maximum values for numbers).
132+
133+
Variables with a constant value should be encoded directly in the URL without using a variable.
93134

94135
### PMTiles
95136

@@ -119,9 +160,7 @@ Links to a XYZ, also known as slippy map.
119160
| type | string | Recommended to be set to the image file type the XYZ returns by default, usually `image/png` or `image/jpeg`. |
120161
| href:servers | \[string] | See [href:servers](#hrefservers) below for details. |
121162

122-
#### href
123-
124-
For XYZ, the `href` is a templated URI.
163+
**href**: For XYZ, the `href` is a templated URI.
125164
It MUST include the following placeholders: `{x}`, `{y}` and `{z}` and MAY include a placeholder for the server: `{s}`.
126165
If `{s}` is used, the field [`href:servers`](#hrefservers) MUST be provided.
127166
All other parameters should be [hard-coded](https://github.com/stac-extensions/web-map-links/issues/2) with specific values,

‎examples/collection.json‎

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,35 @@
4242
"href": "https://maps.example.com/wmts",
4343
"rel": "wmts",
4444
"type": "image/png",
45-
"title": "RGB composite visualized through a WMTS",
46-
"wmts:layer": "rgb",
45+
"title": "Mosaic visualized through a WMTS (KVP)",
46+
"wmts:layer": "mosaic",
4747
"wmts:dimensions": {
48-
"time": "2022-01-01"
48+
"time": "2025"
49+
}
50+
},
51+
{
52+
"href": "https://maps.example.com/wmts/WMTSCapabilities.xml",
53+
"rel": "wmts",
54+
"type": "application/xml",
55+
"title": "Mosaic visualized through a WMTS (REST)",
56+
"wmts:encoding": "rest",
57+
"wmts:layer": "mosaic",
58+
"uriTemplate": "https://maps.example.com/wmts/rest/mosaic/{time}/{style}/{TileMatrixSet}/{TileMatrix}/{TileRow}/{TileCol}.png",
59+
"variables": {
60+
"style": {
61+
"type": "string",
62+
"enum": [
63+
"rgb",
64+
"grayscale"
65+
],
66+
"default": "rgb"
67+
},
68+
"time": {
69+
"type": "integer",
70+
"minimum": 2015,
71+
"maximum": 2026,
72+
"default": 2025
73+
}
4974
}
5075
},
5176
{

‎examples/item.json‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,35 @@
5757
"satellite"
5858
]
5959
},
60+
{
61+
"href": "https://maps.example.com/wmts",
62+
"rel": "wmts",
63+
"type": "image/png",
64+
"title": "Mosaic visualized through a WMTS (KVP)",
65+
"wmts:layer": "mosaic",
66+
"wmts:dimensions": {
67+
"time": "2025"
68+
}
69+
},
70+
{
71+
"href": "https://maps.example.com/wmts/WMTSCapabilities.xml",
72+
"rel": "wmts",
73+
"type": "application/xml",
74+
"title": "Mosaic visualized through a WMTS (REST)",
75+
"wmts:encoding": "rest",
76+
"wmts:layer": "mosaic",
77+
"uriTemplate": "https://maps.example.com/wmts/rest/mosaic/2025/{style}/{TileMatrixSet}/{TileMatrix}/{TileRow}/{TileCol}.png",
78+
"variables": {
79+
"style": {
80+
"type": "string",
81+
"enum": [
82+
"rgb",
83+
"grayscale"
84+
],
85+
"default": "rgb"
86+
}
87+
}
88+
},
6089
{
6190
"href": "https://maps.example.com/wms",
6291
"rel": "wms",

‎json-schema/schema.json‎

Lines changed: 64 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -70,38 +70,77 @@
7070
}
7171
},
7272
"then": {
73-
"required": [
74-
"wmts:layer"
73+
"allOf": [
74+
{
75+
"$ref": "#/definitions/servers"
76+
}
7577
],
76-
"properties": {
77-
"wmts:layer": {
78-
"oneOf": [
79-
{
80-
"type": "string",
81-
"minLength": 1
82-
},
83-
{
84-
"type": "array",
85-
"minItems": 1,
86-
"items": {
78+
"if": {
79+
"required": [
80+
"wmts:encoding"
81+
],
82+
"properties": {
83+
"wmts:encoding": {
84+
"const": "rest"
85+
}
86+
}
87+
},
88+
"then": {
89+
"$comment": "REST request encoding",
90+
"required": [
91+
"wmts:layer"
92+
],
93+
"properties": {
94+
"wmts:layer": {
95+
"type": "string",
96+
"minLength": 1
97+
},
98+
"wmts:encoding": {
99+
"const": "rest"
100+
},
101+
"uriTemplate": {
102+
"type": "string",
103+
"minLength": 1
104+
},
105+
"variables": {
106+
"type": "object",
107+
"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."
108+
}
109+
}
110+
},
111+
"else": {
112+
"$comment": "KVP request encoding",
113+
"required": [
114+
"wmts:layer"
115+
],
116+
"properties": {
117+
"wmts:layer": {
118+
"oneOf": [
119+
{
87120
"type": "string",
88121
"minLength": 1
122+
},
123+
{
124+
"type": "array",
125+
"minItems": 1,
126+
"items": {
127+
"type": "string",
128+
"minLength": 1
129+
}
89130
}
131+
]
132+
},
133+
"wmts:encoding": {
134+
"const": "kvp"
135+
},
136+
"wmts:dimensions": {
137+
"type": "object",
138+
"additionalProperties": {
139+
"type": "string"
90140
}
91-
]
92-
},
93-
"wmts:dimensions": {
94-
"type": "object",
95-
"additionalProperties": {
96-
"type": "string"
97141
}
98142
}
99-
},
100-
"allOf": [
101-
{
102-
"$ref": "#/definitions/servers"
103-
}
104-
]
143+
}
105144
}
106145
},
107146
{

0 commit comments

Comments
 (0)