Skip to content

Commit 0f1ff40

Browse files
philvarnerphilvarner
authored
Merge pull request #216 from radiantearth/dev
merge to master for 1.0.0-beta.4 release
2 parents 8745df7 + f7b895f commit 0f1ff40

35 files changed

+674
-478
lines changed

‎.circleci/build-openapi.sh

+1-3
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,9 @@ for fin in $FNAMES; do
1010
fout=./build/$fin
1111
mkdir -p ${fout%/*}
1212
openapi bundle --ext yaml --output $fout $fin
13-
cp build/index.html ${fout%/*}/
13+
cp build/redoc_index.html ${fout%/*}/index.html
1414
done
1515

16-
cp build/core/openapi.yaml build/openapi.yaml
17-
1816
# use swagger-combine
1917
#swagger-combine build/swagger-config.yaml --continueOnConflictingPaths -o build/openapi.yaml
2018

‎CHANGELOG.md

+24-1
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
55
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
66

77

8-
## [Unreleased]
8+
## [v1.0.0-beta4] - 2020-10-05
99

1010
### Added
1111

12+
- Support binding Sort, Fields, and Context Extensions to STAC Features items resource
13+
endpoint (`/collections/{collection_id}/items`)
14+
- In Collections, added `canonical` rel type, added `/` and `/api` to list of endpoints
15+
- In Item Search, added endpoint table
16+
1217
### Changed
1318

19+
- Filter Extension - query language is now referred to as "CQL2" rather than CQL
20+
- Filter Extension now uses OAFeat Part 3 conformance class URIs
21+
- Filter Extension - The following changes have been made to the Filter Extension conformance classes to align with changes to the OAFeat CQL draft. All classes
22+
whose names have changed also have changed conformance URI strings.
23+
- "Basic CQL" now includes the "not equal" operator (`<>`)
24+
- "Basic CQL" has always supported datetime comparisons, but this is now explicitly mentioned
25+
- "Enhanced Comparison Operators" has been renamed "Advanced Comparison Operators". This is the same as the OAFeat CQL definition, except
26+
that it does not require the `upper` and `lower` functions.
27+
- "Enhanced Spatial Operators" has been renamed to just "Spatial Operators" (not to be confused with Basic Spatial Operators)
28+
- "Basic Temporal Operators" and "Enhanced Temporal Operators" have merged into "Temporal Operators"
29+
- "Functions" has been renamed "Custom Functions"
30+
- "Arithmetic" has been renamed "Arithmetic Expressions"
31+
- "Arrays" has been renamed "Array Operators"
32+
- "Queryable Second Operand" has been renamed "Property-Property Comparisons"
33+
- The required Link Relations and endpoints for each conformance class now use the wording of 'shall'
34+
instead of 'should'. While this technically changes the semantics, it was generally understood
35+
previously the semantics were those of 'shall' (must).
36+
1437
### Deprecated
1538

1639
### Removed

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ to search STAC catalogs, where the features returned are STAC [Item](stac-spec/i
2929
that have common properties, links to their assets and geometries that represent the footprints of the geospatial assets.
3030

3131
The specification for STAC API is provided as files that follow the [OpenAPI](http://openapis.org/) 3.0 specification,
32-
rendered online into HTML at <https://api.stacspec.org/v1.0.0-beta.3>, in addition to human-readable documentation.
32+
rendered online into HTML at <https://api.stacspec.org/v1.0.0-beta.4>, in addition to human-readable documentation.
3333

3434
## Stability Note
3535

‎build/index.html

+14-23
Original file line numberDiff line numberDiff line change
@@ -2,31 +2,22 @@
22
<html>
33

44
<head>
5-
<title>STAC API</title>
6-
<!-- needed for adaptive design -->
7-
<meta charset="utf-8" />
8-
<meta name="viewport" content="width=device-width, initial-scale=1">
9-
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
10-
11-
<!--
12-
ReDoc doesn't change outer page styles
13-
-->
14-
<style>
15-
body {
16-
margin: 0;
17-
padding: 0;
18-
}
19-
</style>
5+
<title>STAC API</title>
6+
<!-- needed for adaptive design -->
7+
<meta charset="utf-8" />
8+
<meta name="viewport" content="width=device-width, initial-scale=1">
9+
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
2010
</head>
2111

2212
<body>
23-
<redoc
24-
spec-url='openapi.yaml'
25-
expandResponses='200,201,202,203,204'
26-
pathInMiddlePanel='true'
27-
hideDownloadButton='true'
28-
></redoc>
29-
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
13+
<h1>STAC API</h1>
14+
<h2>Conformance Classes</h2>
15+
<ul>
16+
<li><a href="core/">Core</a></li>
17+
<li><a href="item-search/">Item Search</a></li>
18+
<li><a href="ogcapi-features/">STAC Features</a></li>
19+
<li><a href="collections/"></a>Collections</li>
20+
</ul>
3021
</body>
3122

32-
</html>
23+
</html>

‎build/redoc_index.html

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<!DOCTYPE html>
2+
<html>
3+
4+
<head>
5+
<title>STAC API</title>
6+
<!-- needed for adaptive design -->
7+
<meta charset="utf-8" />
8+
<meta name="viewport" content="width=device-width, initial-scale=1">
9+
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
10+
11+
<!--
12+
ReDoc doesn't change outer page styles
13+
-->
14+
<style>
15+
body {
16+
margin: 0;
17+
padding: 0;
18+
}
19+
</style>
20+
</head>
21+
22+
<body>
23+
<redoc
24+
spec-url='openapi.yaml'
25+
expandResponses='200,201,202,203,204'
26+
pathInMiddlePanel='true'
27+
hideDownloadButton='true'
28+
></redoc>
29+
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
30+
</body>
31+
32+
</html>

‎build/swagger-config.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
openapi: 3.0.3
22
info:
33
title: STAC API - Complete
4-
version: 1.0.0-beta.3
4+
version: 1.0.0-beta.4
55
apis:
66
- url: 'build/core/openapi.yaml'
77
paths:

‎collections/README.md

+91-86
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,9 @@
44
- [Link Relations](#link-relations)
55
- [Endpoints](#endpoints)
66
- [Example](#example)
7-
- [Conformance](#conformance)
87

9-
- **OpenAPI specification:** Missing
10-
- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.3/extensions/collections>
8+
- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.4/collections))
9+
- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.4/extensions/collections>
1110
- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
1211
- **Dependencies**: [STAC API - Core](../core)
1312

@@ -23,120 +22,126 @@ aim to align with it. But it still seems to be in flux.*
2322

2423
## Link Relations
2524

26-
The following Link relations should exist in the Landing Page (root).
25+
The following Link relations shall exist in the Landing Page (root).
2726

2827
| **rel** | **href** | **From** | **Description** |
2928
| -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3029
| `root` | `/` | STAC Core | The root URI |
3130
| `self` | `/` | OAFeat | Self reference, same as root URI |
32-
| `service-desc` | `/api` (recommended) | OAFeat OpenAPI | The OpenAPI service description. Uses the `application/vnd.oai.openapi+json;version=3.0` media type to refer to the OpenAPI 3.0 document that defines the service's API |
33-
| `child` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects |
34-
| `data` | `/collections` | OAFeat | List of Collections |
31+
| `service-desc` | `/api` | OAFeat OpenAPI | The OpenAPI service description. Uses the `application/vnd.oai.openapi+json;version=3.0` media type to refer to the OpenAPI 3.0 document that defines the service's API. The path for this endpoint is only recommended to be `/api`, but may be another path. |
32+
| `data` | `/collections` | OAFeat | List of Collections |
3533

36-
Additionally, a `service-doc` endpoint is recommended.
34+
A `service-doc` endpoint is recommended, but not required.
3735

38-
| **rel** | **href** | **From** | **Description** |
36+
| **rel** | **href** | **From** | **Description** |
3937
| ------------- | ------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
40-
| `service-doc` | `/api.html` (recommended) | OAFeat OpenAPI | An HTML service description. Uses the `text/html` media type to refer to a human-consumable description of the service |
38+
| `service-doc` | `/api.html` | OAFeat OpenAPI | An HTML service description. Uses the `text/html` media type to refer to a human-consumable description of the service. The path for this endpoint is only recommended to be `/api.html`, but may be another path. |
4139

42-
The following Link relations should exist in the `/collections` endpoint response.
40+
Additionally, `child` relations may exist to individual catalogs and collections.
41+
42+
| **rel** | **href** | **From** | **Description** |
43+
| -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44+
| `child` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects |
45+
46+
`child` relations are useful for supporting browsing a STAC API as if it were a static catalog.
47+
48+
The following Link relations shall exist in the `/collections` endpoint response.
4349

4450
| **rel** | **href** | **From** | **Description** |
4551
| ------- | -------------- | --------- | --------------- |
4652
| `root` | `/` | STAC Core | The root URI |
4753
| `self` | `/collections` | OAFeat | Self reference |
4854

49-
The following Link relations should exist in the `/collections/{collectionId}` endpoint response.
55+
The following Link relations shall exist in the Collection object returned from the `/collections/{collectionId}` endpoint.
5056

5157
| **rel** | **href** | **From** | **Description** |
5258
| -------- | ----------------------------------- | --------- | ------------------------------------------ |
5359
| `root` | `/` | STAC Core | The root URI |
5460
| `parent` | `/` | OAFeat | Parent reference, usually the root Catalog |
5561
| `self` | `/collections/{collectionId}` | OAFeat | Self reference |
56-
| `items` | `/collections/{collectionId}/items` | OAFeat | Items within Collection |
62+
63+
Additionally, these relations may exist for the `/collections/{collectionId}` endpoint:
64+
65+
| **rel** | **href** | **From** | **Description** |
66+
| -------- | ----------------------------------- | --------- | ------------------------------------------ |
67+
| `canonical` | various | STAC Core | Provides the preferred paths to get to STAC Collection and Item objects, if they differ from the URL that was used to retrieve the STAC object and thus duplicate other content. This can be useful in federated catalogs that present metadata that has a different location than the source metadata. |
68+
69+
Usually, the `self` link in a Collection must link to the same URL that was used to request
70+
it. However, implementations may choose to have the canonical location of the Collection be
71+
elsewhere. If this is done, it is recommended to include a `rel` of `canonical` to that location.
5772

5873
## Endpoints
5974

60-
| Endpoint | Returns | Description |
61-
| ----------------------------- | ---------- | -------------------------------------------------------------------- |
62-
| `/collections` | JSON | Object with a list of Collections contained in the catalog and links |
63-
| `/collections/{collectionId}` | Collection | Returns single Collection JSON |
75+
| Endpoint | Returns | Description |
76+
| -------- | ------- | ----------- |
77+
| `/` | Catalog | Landing Page and root Catalog |
78+
| `/api` | OAFeat OpenAPI | The OpenAPI service description. The path for this endpoint is only recommended to be `/api`, but may be another path. |
79+
| `/collections` | JSON | Object with a list of Collections contained in the catalog and links |
80+
| `/collections/{collectionId}` | Collection | Returns single Collection JSON |
6481

6582
STAC API's implementing the Collections class must support HTTP GET operation at `/collections`, with the return JSON document consisting
6683
of an array of all STAC Collections and an array of Links.
6784

6885
## Example
6986

87+
Below is a minimal example, but captures the essence. Each collection object must be a valid STAC
88+
[Collection](../stac-spec/collection-spec/README.md), and each must have a `self` link that communicates its canonical location. And then
89+
the links section must include a `self` link, and it must also link to alternate representations (like html) of the collection.
90+
7091
```json
7192
{
72-
"collections": [
73-
{
74-
"stac_version": "1.0.0",
75-
"stac_extensions": [ ],
76-
"id": "cool-data",
77-
"title": "Cool Data from X Satellite",
78-
"description": "A lot of awesome words describing the data",
79-
"license": "CC-BY",
80-
"extent": {
81-
"spatial": {
82-
"bbox": [[-135.17, 36.83, -51.24, 62.25]]
83-
},
84-
"temporal": {
85-
"interval": [["2009-01-01T00:00:00Z",null]]
86-
}
87-
},
88-
"links": [
89-
{
90-
"rel": "root",
91-
"type": "application/json",
92-
"href": "https://myservice.com"
93-
},
94-
{
95-
"rel": "parent",
96-
"type": "application/json",
97-
"href": "https://myservice.com"
98-
},
99-
{
100-
"rel": "self",
101-
"type": "application/json",
102-
"href": "https://myservice.com/collections/cool-data"
103-
},
104-
{
105-
"rel": "items",
106-
"type": "application/json",
107-
"href": "https://myservice.com/collections/cool-data/items"
108-
}
109-
],
110-
}
111-
],
112-
"links": [
113-
{
114-
"rel": "root",
115-
"type": "application/json",
116-
"href": "https://myservice.com"
117-
},
118-
{
119-
"rel": "self",
120-
"type": "application/json",
121-
"href": "https://myservice.com/collections"
122-
}
123-
]
93+
"collections": [
94+
{
95+
"stac_version": "1.0.0",
96+
"stac_extensions": [ ],
97+
"id": "cool-data",
98+
"title": "Cool Data from X Satellite",
99+
"description": "A lot of awesome words describing the data",
100+
"type": "Collection",
101+
"license": "CC-BY",
102+
"extent": {
103+
"spatial": {
104+
"bbox": [[-135.17, 36.83, -51.24, 62.25]]
105+
},
106+
"temporal": {
107+
"interval": [["2009-01-01T00:00:00Z",null]]
108+
}
109+
},
110+
"links": [
111+
{
112+
"rel": "root",
113+
"type": "application/json",
114+
"href": "https://myservice.com"
115+
},
116+
{
117+
"rel": "parent",
118+
"type": "application/json",
119+
"href": "https://myservice.com"
120+
},
121+
{
122+
"rel": "self",
123+
"type": "application/json",
124+
"href": "https://myservice.com/collections/cool-data"
125+
},
126+
{
127+
"rel": "items",
128+
"type": "application/json",
129+
"href": "https://myservice.com/collections/cool-data/items"
130+
}
131+
],
132+
}
133+
],
134+
"links": [
135+
{
136+
"rel": "root",
137+
"type": "application/json",
138+
"href": "https://myservice.com"
139+
},
140+
{
141+
"rel": "self",
142+
"type": "application/json",
143+
"href": "https://myservice.com/collections"
144+
}
145+
]
124146
}
125147
```
126-
127-
The above is a minimal example, but captures the essence. Each collection object must be a valid STAC
128-
[Collection](../stac-spec/collection-spec/README.md), and each should have a `self` link that communicates its canonical location. And then
129-
the links section must include a `self` link, and it should also link to alternate representations (like html) of the collection.
130-
131-
Each collection must also be accessible from `/collections/{collectionId}`. Usually this will be the location provided by the `self` link,
132-
but implementations may choose to list the canonical location elsewhere. But `/collections/{collectionId}` must always contain the response,
133-
and if the canonical location is elsewhere it is recommended to include a `rel` of `canonical` from `/collections/{collectionId}` to that location.
134-
135-
## Conformance
136-
137-
Any implementation that provides the STAC Collection functionality described above must add `http://stacspec.org/spec/api/1.0.0-beta.3/collections`,
138-
the conformance URI, to the `conformsTo` JSON at the landing page.
139-
140-
The core STAC landing page (`/`) must also include a link with a `rel` of `data` that links to the `/collections` endpoint.
141-
142-
**NOTE**: *When this aligns with OGC API - Common it will also need to add it to the `/conformance` endpoint.*

‎collections/openapi.yaml

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
openapi: 3.0.3
22
info:
33
title: STAC API - Collections
4-
version: '1.0.0-beta.3'
4+
version: '1.0.0-beta.4'
55
description: >-
66
This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Core
77
specification. This is a subset of the STAC API - Collections specification.
@@ -38,13 +38,13 @@ paths:
3838
schema:
3939
$ref: '../core/openapi.yaml#/components/schemas/landingPage'
4040
example:
41-
stac_version: 1.0.0-beta.3
41+
stac_version: 1.0.0-beta.4
4242
type: Catalog
4343
id: sentinel
4444
title: Copernicus Sentinel Imagery
4545
description: Catalog of Copernicus Sentinel 1 and 2 imagery.
4646
conformsTo:
47-
- 'https://api.stacspec.org/v1.0.0-beta.3/core'
47+
- 'https://api.stacspec.org/v1.0.0-beta.4/core'
4848
- 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core'
4949
- 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30'
5050
- 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson'

0 commit comments

Comments
 (0)