Skip to content

Commit f1971c4

Browse files
cholmescholmes
committed
latest changes from dev
2 parents 6478ae4 + fc84a35 commit f1971c4

14 files changed

+681
-102
lines changed

‎README.md

+3
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ other tools.
3939
**[api-spec/](api-spec/)** defines a dynamic API, specified as a [yaml](api-spec/spec.yaml) file in [OpenAPI](http://openapis.org)
4040
2.0 (swagger).
4141

42+
**Extensions:** The *[extensions/](extensions/)* folder is where profiles and extensions live. Profiles are recommendations for
43+
adding fields for specific domains (like Earth Observation). Extensions bring additional functionality to the core specs.
44+
4245
**Additional documents** include the current [roadmap](roadmap.md) and a complementary [how to help](how-to-help.md)
4346
document, a [list of implementations](implementations.md),
4447
and a discussion of the collaboration [principles](principles.md) and specification approach.

‎api-spec/STAC-fragment.yaml

+9-21
Original file line numberDiff line numberDiff line change
@@ -125,17 +125,18 @@ components:
125125
name: time
126126
in: query
127127
description: >-
128-
A time range search that accepts a JSON search object.
129-
128+
Either a date-time or a period string that adheres to RFC3339. Examples:
129+
* A date-time: "2018-02-12T23:20:50Z"
130+
* A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S"
130131
Only features that have a temporal property that intersects the value of
131132
`time` are selected.
132-
133133
If a feature has multiple temporal properties, it is the decision of the
134-
server whether only a single temporal property is used to determine the
135-
extent or all relevant temporal properties.
134+
server whether only a single temporal property is used to determine
135+
the extent or all relevant temporal properties.
136136
required: false
137137
schema:
138-
$ref: '#/components/schemas/timeRange'
138+
type: string
139+
style: form
139140
explode: false
140141
schemas:
141142
searchBody:
@@ -151,9 +152,7 @@ components:
151152
- 39
152153
- -105
153154
- 41
154-
time:
155-
gt: "2018-03-15T00:00:00.000Z"
156-
lt: "2018-06-01T00:00:00.000Z"
155+
time: "2018-03-15T00:00:00.000Z"
157156
bboxFilter:
158157
type: object
159158
description: Only return items that intersect the provided bounding box.
@@ -165,7 +164,7 @@ components:
165164
type: object
166165
properties:
167166
time:
168-
$ref: '#/components/schemas/timeRange'
167+
$ref: '#/components/parameters/time'
169168
intersectsFilter:
170169
type: object
171170
description: Only returns items that intersect with the provided polygon.
@@ -221,17 +220,6 @@ components:
221220
description: >-
222221
A single date-time string that adheres to RFC3339, for example
223222
1985-04-12T23:20:50.52Z
224-
timeRange:
225-
type: object
226-
properties:
227-
gt:
228-
$ref: '#/components/schemas/time'
229-
lt:
230-
$ref: '#/components/schemas/time'
231-
gte:
232-
$ref: '#/components/schemas/time'
233-
lte:
234-
$ref: '#/components/schemas/time'
235223
itemCollection:
236224
type: object
237225
required:

‎api-spec/STAC-standalone.yaml

+8-16
Original file line numberDiff line numberDiff line change
@@ -150,27 +150,19 @@ components:
150150
time:
151151
name: time
152152
in: query
153-
description: >-
154-
A time range search that accepts a JSON search object.
155-
153+
description: |
154+
Either a date-time or a period string that adheres to RFC3339. Examples:
155+
* A date-time: "2018-02-12T23:20:50Z"
156+
* A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S"
156157
Only features that have a temporal property that intersects the value of
157158
`time` are selected.
158-
159159
If a feature has multiple temporal properties, it is the decision of the
160-
server whether only a single temporal property is used to determine the
161-
extent or all relevant temporal properties.
160+
server whether only a single temporal property is used to determine
161+
the extent or all relevant temporal properties.
162162
required: false
163163
schema:
164-
type: object
165-
properties:
166-
gt:
167-
$ref: '#/components/schemas/time'
168-
lt:
169-
$ref: '#/components/schemas/time'
170-
gte:
171-
$ref: '#/components/schemas/time'
172-
lte:
173-
$ref: '#/components/schemas/time'
164+
type: string
165+
style: form
174166
explode: false
175167
collectionId:
176168
name: collectionId

‎api-spec/WFS3core+STAC.yaml

+7-15
Original file line numberDiff line numberDiff line change
@@ -308,26 +308,18 @@ components:
308308
name: time
309309
in: query
310310
description: >-
311-
A time range search that accepts a JSON search object.
312-
311+
Either a date-time or a period string that adheres to RFC3339. Examples:
312+
* A date-time: "2018-02-12T23:20:50Z"
313+
* A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S"
313314
Only features that have a temporal property that intersects the value of
314315
`time` are selected.
315-
316316
If a feature has multiple temporal properties, it is the decision of the
317-
server whether only a single temporal property is used to determine the
318-
extent or all relevant temporal properties.
317+
server whether only a single temporal property is used to determine
318+
the extent or all relevant temporal properties.
319319
required: false
320320
schema:
321-
type: object
322-
properties:
323-
gt:
324-
$ref: '#/components/schemas/time'
325-
lt:
326-
$ref: '#/components/schemas/time'
327-
gte:
328-
$ref: '#/components/schemas/time'
329-
lte:
330-
$ref: '#/components/schemas/time'
321+
type: string
322+
style: form
331323
explode: false
332324
collectionId:
333325
name: collectionId

‎api-spec/filters.md

+42-19
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ and are required to be supported.
66

77
The filters are designed to be simple as possible for a client to construct. To match the default JSON responses the
88
encoding of filters is done by default in JSON. This allows clients to support filtering without additional tools. The
9-
search enpoint will accept application/json format queries, and GET on the collection will support URL encoded JSON. POST
9+
search endpoint will accept application/json format queries, and GET on the collection will support URL encoded JSON. POST
1010
search the is recommended way to filter results to avoid the URL encoding issues that can happen with GET.
1111

1212
Searching using POST will accept a JSON object where the top level keys are specifying which type of filter
@@ -20,33 +20,60 @@ This query will perform an intersects operation on the geometry values of the it
2020
objects may provide a bbox property in addition to geometry, but it should not be used for the bbox filter since
2121
it is an optional field in GeoJSON.
2222

23-
example
23+
###### examples: ######
24+
POST:
2425
```
2526
{
2627
"bbox": [-180,-90,180,90]
2728
}
2829
```
2930

30-
The temporal query will be based on [RFC 3339](https://tools.ietf.org/html/rfc3339) and should support time ranges as well as equality. To support range
31-
queries, we are using a simple JSON based language. Ranges will be specified as an object with keys indicating the comparison to use.
31+
GET:
32+
```
33+
?bbox=[-180,-90,180,90]
34+
```
35+
36+
The temporal query will be based on [RFC 3339](https://tools.ietf.org/html/rfc3339) and should support time ranges as well as equality. It will compare against the datetime property of the STAC Item.
37+
38+
###### To find items with an exact date ######
39+
40+
POST:
41+
```
42+
{
43+
"time": "2007-03-01T13:00:00Z"
44+
}
45+
```
3246

33-
Equality is specified as `{"time": "2018-03-20T16:11:44.353Z"}`
34-
Before is `{"time":{"lt":"2018-03-20T16:11:44.353Z"}}`
35-
After is `{"time":{"gt":"2018-03-20T16:11:44.353Z"}}`
36-
Before with Equality is `{"time":{"lte":"2018-03-20T16:11:44.353Z"}}`
37-
After with Equality is `{"time":{"gte":"2018-03-20T16:11:44.353Z"}}`
47+
GET:
48+
```
49+
?time=2007-03-01T13:00:00Z
50+
```
3851

39-
These queries can be combined to specify a search range:
52+
###### To specify a time range, use the interval syntax: ######
4053

54+
POST:
4155
```
4256
{
43-
"time": {
44-
"gt":"2018-03-15T00:00:00.000Z",
45-
"lt":"2018-06-01T00:00:00.000Z",
46-
}
47-
}
57+
"time": "2007-03-01T13:00:00Z/2008-05-11T15:30:00Z"
58+
}
4859
```
4960

61+
GET:
62+
```
63+
?time=2007-03-01T13:00:00Z/2008-05-11T15:30:00Z
64+
```
65+
66+
###### Specify intervals using durations: ######
67+
68+
`2007-03-01T13:00:00Z/P1Y2M10DT2H30M`
69+
70+
If time is a period with out a start or end date, the end date is assigned to now:
71+
72+
`P1Y2M10DT2H30M` is the same as `"P1Y2M10DT2H30M/" + new Date().toISOString()`
73+
74+
75+
76+
5077
Filter Extensions
5178
-----------------
5279

@@ -124,10 +151,6 @@ Some additional extensions that have been discussed:
124151
CQL support for generic queries:
125152
`{"CQL": "CQL Select String"}`
126153

127-
Time intervals:
128-
`{"time": "P1Y"}` Assume Duration/now if no time specified?
129-
`{"time": "2018/P1M"}` Any time in january of 2018
130-
131154

132155
Adding filters to search
133156
------------------------

‎api-spec/wfs-stac.md

+42-3
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,48 @@ STAC endpoint.
2727

2828
### WFS Structure
2929

30-
TODO: Give an overview of the main WFS endpoints
30+
A Web Feature Service is a standard API that represents collections of geospatial data.
31+
32+
```
33+
GET /collections
34+
```
35+
36+
Lists the collections of data on the server that can be queried ([7.11](https://rawgit.com/opengeospatial/WFS_FES/master/docs/17-069.html#_feature_collections_metadata)),
37+
and each describes basic information about the geospatial data collection, like its name and description, as well as the
38+
spatial and temporal extents of all the data contained. A STAC search extension would only query those collections which
39+
have data that validates as STAC `Items` - with a datetime field and references to assets. But a STAC can live alongside
40+
other WFS collections, like an organization might choose to have their building and road data in WFS collections, alongside
41+
their STAC-compatible imagery data.
42+
43+
```
44+
GET /collections/{name}/items?bbox=160.6,-55.95,-170,-25.89
45+
```
46+
47+
Requests all the data in the collection that is in New Zealand. The filtering is made to be compatible with the STAC API,
48+
and the two specs seek to share the general query and filtering patterns. The key difference is that a STAC search endpoint
49+
will do cross collection search. A typical WFS will have multiple collections, and each will just offer search for its particular
50+
collection.
51+
3152

3253
### Strongly Typed STAC data
3354

34-
TODO: explain the advantages of using WFS to provide schema information at a collection level, for stronger typing
35-
of data. Plus transactions.
55+
The scenario that using a WFS with a STAC search endpoint that makes the most sense is when a data provider wants to provide more
56+
insight in to heterogenous data that is exposed on a STAC search. For example they might have imagery data from different satellite providers
57+
and even some drone data. These will all have different fields. A single STAC endpoint can be used to expose them all. But it can be quite
58+
useful to let users inspect a particular data type. That area of the `/collections/{name}` hierarchy can be used to expose additional
59+
metadata and validation schemas that give more insight in to that data, as well as a place to query just that data.
60+
61+
In general it is recommended to provide as much information about different types of data as possible, so using WFS is recommended. But
62+
the standalone option is there for those who just want to expose their data as quickly and easily as possible. Note a WFS can
63+
provide heterogenous data from any of its collections endpoints, but the STAC API recommendation is to use one collection per
64+
logical data type.
65+
66+
### Potential Transaction Extension
67+
68+
The other benefit of individual collection endpoints is that it gives a logical location for simple RESTful transactions
69+
70+
```
71+
POST /collections/landsat/items/
72+
```
73+
74+
There have been a couple implementations that have done transactions, and soon will contribute an extension.

‎extensions/examples/L1T-collection.json

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
2+
{
3+
4+
5+
"properties": {
6+
"collection_name": "L1T",
7+
"collection_description": "Landat 8 imagery that is radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.",
8+
"provider": "USGS",
9+
"license": "PDDL-1.0",
10+
"eo:gsd" : 30,
11+
"eo:platform": "landsat-8",
12+
"eo:instrument": "OLI_TIRS",
13+
},
14+
15+
"eo:bands": {
16+
"1": {
17+
"common_name": "coastal",
18+
"gsd": 30.0,
19+
"accuracy": null,
20+
"wavelength": 0.44,
21+
"fwhm": 0.02
22+
},
23+
"2": {
24+
"common_name": "blue",
25+
"gsd": 30.0,
26+
"accuracy": null,
27+
"wavelength": 0.48,
28+
"fwhm": 0.06
29+
},
30+
"3": {
31+
"common_name": "green",
32+
"gsd": 30.0,
33+
"accuracy": null,
34+
"wavelength": 0.56,
35+
"fwhm": 0.06
36+
},
37+
"4": {
38+
"common_name": "red",
39+
"gsd": 30.0,
40+
"accuracy": null,
41+
"wavelength": 0.65,
42+
"fwhm": 0.04
43+
},
44+
"5": {
45+
"common_name": "nir",
46+
"gsd": 30.0,
47+
"accuracy": null,
48+
"wavelength": 0.86,
49+
"fwhm": 0.03
50+
},
51+
"6": {
52+
"common_name": "swir16",
53+
"gsd": 30.0,
54+
"accuracy": null,
55+
"wavelength": 1.6,
56+
"fwhm": 0.08
57+
},
58+
"7": {
59+
"common_name": "swir22",
60+
"gsd": 30.0,
61+
"accuracy": null,
62+
"wavelength": 2.2,
63+
"fwhm": 0.2
64+
},
65+
"8": {
66+
"common_name": "pan",
67+
"gsd": 15.0,
68+
"accuracy": null,
69+
"wavelength": 0.59,
70+
"fwhm": 0.18
71+
},
72+
"9": {
73+
"common_name": "cirrus",
74+
"gsd": 30.0,
75+
"accuracy": null,
76+
"wavelength": 1.37,
77+
"fwhm": 0.02
78+
},
79+
"10": {
80+
"common_name": "lwir11",
81+
"gsd": 100.0,
82+
"accuracy": null,
83+
"wavelength": 10.9,
84+
"fwhm": 0.8
85+
},
86+
"11": {
87+
"common_name": "lwir12",
88+
"gsd": 100.0,
89+
"accuracy": null,
90+
"wavelength": 12.0,
91+
"fwhm": 1.0
92+
}
93+
}

‎extensions/examples/README.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## Landsat Example with EO profile and Collection extension
2+
3+
The files in this directory contain a full example of Landsat data. It follows the Earth Observation
4+
Profile, and uses the 'Collection' extension to be less duplicative of information
5+
6+
* [landsat8-sample](landsat8-sample.json) is a core `Item` including the link to its collection information.
7+
* [L1T-collection](L1T-collection.json) shows the collection information for Landsat 8 L1T collection
8+
* [landsat8-merged](landsat8-merged.json) is a fully expanded record, showing the result of merging of the collection data and the core `Item`.

0 commit comments

Comments
 (0)