Skip to content

Commit cfa46ca

Browse files
m-mohrm-mohr
committed
WMTS: REST request encoding
1 parent 5b524c1 commit cfa46ca

File tree

3 files changed

+87
-35
lines changed

3 files changed

+87
-35
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: 34 additions & 10 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
@@ -77,19 +79,43 @@ Links to a [OGC Web Map Tile Service](https://www.ogc.org/standards/wmts) (WMTS)
7779
| href | string | **REQUIRED**. Link to the WMTS, without any WMTS specific query parameters. |
7880
| type | string | The media type to be used for the tile requests, e.g. `image/png` or `image/jpeg`. |
7981
| 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. |
82+
| wmts:dimensions | Map\<string, string> | Any additional parameters for the request (see below). |
83+
| wmts:encoding | string | Either `kvp` (see [KVP](#kvp)) or `rest` (see [REST](#rest)). Defaults to `KVP`. |
8284

83-
If you provide multiple array elements in `wmts:layer` (e.g. `["layerA", "layerB"]`),
84-
each should occur in a separate layer in the mapping library so that individual requests for the layers are sent.
85+
The `href` can contain an optional server placeholder `{s}`. If `{s}` is used, the field [`href:servers`](#hrefservers) MUST be provided.
86+
87+
#### KVP
8588

86-
#### href
89+
This describes the key-value-pair (KVP) request encoding,
90+
which uses query parameters to transmit additional parameters.
8791

88-
For WMTS, the `href` is pointing to the URL of the Capabilities document, but without the query parameters for the Capabilities request.
92+
| Field Name | Type | Description |
93+
| --------------- | -------------------- | ----------- |
94+
| wmts:encoding | string | If provided, must be set to `kvp`. |
95+
| 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. |
96+
| wmts:dimensions | Map\<string, string> | Any additional dimension parameters to add to the request as key-value-pairs (i.e. query parameters). |
97+
98+
**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.
8999
So if your Capabilities can be requested from `https://example.com/geoserver/service/wmts?service=wmts&request=GetCapabilities`
90100
you'd provide `https://example.com/geoserver/service/wmts` as `href`.
91101

92-
The `href` can contain an optional server placeholder `{s}`. If `{s}` is used, the field [`href:servers`](#hrefservers) MUST be provided.
102+
**wmts:layer**: If you provide multiple array elements in `wmts:layer` (e.g. `["layerA", "layerB"]`),
103+
each should occur in a separate layer in the mapping library so that individual requests for the layers are sent.
104+
105+
#### REST
106+
107+
This describes the REST request encoding, which provides a URL template with variables.
108+
109+
| Field Name | Type | Description |
110+
| --------------- | -------------------- | ----------- |
111+
| wmts:encoding | string | **REQUIRED**. Must be set to `rest`. |
112+
| variables | Map\<string, \*> | This object contains one key per substitution variable in the templated URL. |
113+
114+
**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.
115+
116+
**variables**: 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.
117+
Note that clients may have varying capabilities to parse and hanle the schemas provided for the variables.
118+
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).
93119

94120
### PMTiles
95121

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

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

‎json-schema/schema.json‎

Lines changed: 52 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -70,38 +70,65 @@
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+
"properties": {
80+
"wmts:encoding": {
81+
"const": "rest"
82+
}
83+
}
84+
},
85+
"then": {
86+
"$comment": "REST request encoding",
87+
"properties": {
88+
"wmts:encoding": {
89+
"const": "rest"
90+
},
91+
"variables": {
92+
"type": "object",
93+
"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."
94+
}
95+
}
96+
},
97+
"else": {
98+
"$comment": "KVP request encoding",
99+
"required": [
100+
"wmts:layer"
101+
],
102+
"properties": {
103+
"wmts:encoding": {
104+
"enum": [
105+
"kvp"
106+
]
107+
},
108+
"wmts:layer": {
109+
"oneOf": [
110+
{
87111
"type": "string",
88112
"minLength": 1
113+
},
114+
{
115+
"type": "array",
116+
"minItems": 1,
117+
"items": {
118+
"type": "string",
119+
"minLength": 1
120+
}
89121
}
122+
]
123+
},
124+
"wmts:dimensions": {
125+
"type": "object",
126+
"additionalProperties": {
127+
"type": "string"
90128
}
91-
]
92-
},
93-
"wmts:dimensions": {
94-
"type": "object",
95-
"additionalProperties": {
96-
"type": "string"
97129
}
98130
}
99-
},
100-
"allOf": [
101-
{
102-
"$ref": "#/definitions/servers"
103-
}
104-
]
131+
}
105132
}
106133
},
107134
{

0 commit comments

Comments
 (0)