Merge pull request #216 from radiantearth/dev

merge to master for 1.0.0-beta.4 release
radiantearth · Oct 7, 2021 · 0f1ff40 · 0f1ff40
2 parents 8745df7 + f7b895f
commit 0f1ff40
Show file tree

Hide file tree

Showing 35 changed files with 674 additions and 478 deletions.
diff --git a/.circleci/build-openapi.sh b/.circleci/build-openapi.sh
@@ -10,11 +10,9 @@ for fin in $FNAMES; do
     fout=./build/$fin
     mkdir -p ${fout%/*}
     openapi bundle --ext yaml --output $fout $fin
-    cp build/index.html ${fout%/*}/
+    cp build/redoc_index.html ${fout%/*}/index.html
 done
 
-cp build/core/openapi.yaml build/openapi.yaml
-
 # use swagger-combine
 #swagger-combine build/swagger-config.yaml --continueOnConflictingPaths -o build/openapi.yaml 
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,12 +5,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
-## [Unreleased]
+## [v1.0.0-beta4] - 2020-10-05
 
 ### Added
 
+- Support binding Sort, Fields, and Context Extensions to STAC Features items resource
+  endpoint (`/collections/{collection_id}/items`)
+- In Collections, added `canonical` rel type, added `/` and `/api` to list of endpoints
+- In Item Search, added endpoint table
+
 ### Changed
 
+- Filter Extension - query language is now referred to as "CQL2" rather than CQL
+- Filter Extension now uses OAFeat Part 3 conformance class URIs
+- 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
+  whose names have changed also have changed conformance URI strings.
+  - "Basic CQL" now includes the "not equal" operator (`<>`)
+  - "Basic CQL" has always supported datetime comparisons, but this is now explicitly mentioned
+  - "Enhanced Comparison Operators" has been renamed "Advanced Comparison Operators". This is the same as the OAFeat CQL definition, except
+    that it does not require the `upper` and `lower` functions.
+  - "Enhanced Spatial Operators" has been renamed to just "Spatial Operators" (not to be confused with Basic Spatial Operators)
+  - "Basic Temporal Operators" and "Enhanced Temporal Operators" have merged into "Temporal Operators"
+  - "Functions" has been renamed "Custom Functions"
+  - "Arithmetic" has been renamed "Arithmetic Expressions"
+  - "Arrays" has been renamed "Array Operators"
+  - "Queryable Second Operand" has been renamed "Property-Property Comparisons"
+- The required Link Relations and endpoints for each conformance class now use the wording of 'shall' 
+  instead of 'should'. While this technically changes the semantics, it was generally understood 
+  previously the semantics were those of 'shall' (must).
+
 ### Deprecated
 
 ### Removed

diff --git a/README.md b/README.md
@@ -29,7 +29,7 @@ to search STAC catalogs, where the features returned are STAC [Item](stac-spec/i
 that have common properties, links to their assets and geometries that represent the footprints of the geospatial assets.
 
 The specification for STAC API is provided as files that follow the [OpenAPI](http://openapis.org/) 3.0 specification, 
-rendered online into HTML at <https://api.stacspec.org/v1.0.0-beta.3>, in addition to human-readable documentation.  
+rendered online into HTML at <https://api.stacspec.org/v1.0.0-beta.4>, in addition to human-readable documentation.  
 
 ## Stability Note
 

diff --git a/build/index.html b/build/index.html
@@ -2,31 +2,22 @@
 <html>
 
 <head>
-  <title>STAC API</title>
-  <!-- needed for adaptive design -->
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
-
-  <!--
-    ReDoc doesn't change outer page styles
-    -->
-  <style>
-    body {
-      margin: 0;
-      padding: 0;
-    }
-  </style>
+    <title>STAC API</title>
+    <!-- needed for adaptive design -->
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
 </head>
 
 <body>
-  <redoc 
-    spec-url='openapi.yaml'
-    expandResponses='200,201,202,203,204'
-    pathInMiddlePanel='true'
-    hideDownloadButton='true'
-  ></redoc>
-  <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
+    <h1>STAC API</h1>
+    <h2>Conformance Classes</h2>
+    <ul>
+        <li><a href="core/">Core</a></li>
+        <li><a href="item-search/">Item Search</a></li>
+        <li><a href="ogcapi-features/">STAC Features</a></li>
+        <li><a href="collections/"></a>Collections</li>
+    </ul>
 </body>
 
-</html>
+</html>
diff --git a/build/redoc_index.html b/build/redoc_index.html
@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <title>STAC API</title>
+  <!-- needed for adaptive design -->
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+
+  <!--
+    ReDoc doesn't change outer page styles
+    -->
+  <style>
+    body {
+      margin: 0;
+      padding: 0;
+    }
+  </style>
+</head>
+
+<body>
+  <redoc 
+    spec-url='openapi.yaml'
+    expandResponses='200,201,202,203,204'
+    pathInMiddlePanel='true'
+    hideDownloadButton='true'
+  ></redoc>
+  <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
+</body>
+
+</html>
diff --git a/build/swagger-config.yaml b/build/swagger-config.yaml
@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: STAC API - Complete
-  version: 1.0.0-beta.3
+  version: 1.0.0-beta.4
 apis:
   - url: 'build/core/openapi.yaml'
     paths:

diff --git a/collections/README.md b/collections/README.md
@@ -4,10 +4,9 @@
   - [Link Relations](#link-relations)
   - [Endpoints](#endpoints)
   - [Example](#example)
-  - [Conformance](#conformance)
 
-- **OpenAPI specification:** Missing
-- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.3/extensions/collections>
+- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.4/collections))
+- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.4/extensions/collections>
 - **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
 - **Dependencies**: [STAC API - Core](../core)
 
@@ -23,120 +22,126 @@ aim to align with it. But it still seems to be in flux.*
 
 ## Link Relations
 
-The following Link relations should exist in the Landing Page (root).
+The following Link relations shall exist in the Landing Page (root).
 
 | **rel**        | **href**             | **From**       | **Description**                                                                                                                                                         |
 | -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `root`         | `/`                  | STAC Core      | The root URI                                                                                                                                                            |
 | `self`         | `/`                  | OAFeat         | Self reference, same as root URI                                                                                                                                        |
-| `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 |
-| `child`        | various              | STAC Core      | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects                                                                |
-| `data`         | `/collections`       | OAFeat         | List of Collections                                                                                                                                                     |
+| `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. |
+| `data`         | `/collections`       | OAFeat         | List of Collections   |
 
-Additionally, a `service-doc` endpoint is recommended.
+A `service-doc` endpoint is recommended, but not required.
 
-| **rel**       | **href**                  | **From**       | **Description**                                                                                                         |
+| **rel**       | **href**                  | **From**       | **Description**  |
 | ------------- | ------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `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 |
+| `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. |
 
-The following Link relations should exist in the `/collections` endpoint response.
+Additionally, `child` relations may exist to individual catalogs and collections.
+
+| **rel**        | **href**             | **From**       | **Description**                                                                                                                                                         |
+| -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `child`        | various              | STAC Core      | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects |
+
+`child` relations are useful for supporting browsing a STAC API as if it were a static catalog.
+
+The following Link relations shall exist in the `/collections` endpoint response.
 
 | **rel** | **href**       | **From**  | **Description** |
 | ------- | -------------- | --------- | --------------- |
 | `root`  | `/`            | STAC Core | The root URI    |
 | `self`  | `/collections` | OAFeat    | Self reference  |
 
-The following Link relations should exist in the `/collections/{collectionId}` endpoint response.
+The following Link relations shall exist in the Collection object returned from the `/collections/{collectionId}` endpoint.
 
 | **rel**  | **href**                            | **From**  | **Description**                            |
 | -------- | ----------------------------------- | --------- | ------------------------------------------ |
 | `root`   | `/`                                 | STAC Core | The root URI                               |
 | `parent` | `/`                                 | OAFeat    | Parent reference, usually the root Catalog |
 | `self`   | `/collections/{collectionId}`       | OAFeat    | Self reference                             |
-| `items`  | `/collections/{collectionId}/items` | OAFeat    | Items within Collection                    |
+
+Additionally, these relations may exist for the `/collections/{collectionId}` endpoint:
+
+| **rel**  | **href**                            | **From**  | **Description**                            |
+| -------- | ----------------------------------- | --------- | ------------------------------------------ |
+| `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. |
+
+Usually, the `self` link in a Collection must link to the same URL that was used to request
+it. However, implementations may choose to have the canonical location of the Collection be
+elsewhere. If this is done, it is recommended to include a `rel` of `canonical` to that location.
 
 ## Endpoints
 
-| Endpoint                      | Returns    | Description                                                          |
-| ----------------------------- | ---------- | -------------------------------------------------------------------- |
-| `/collections`                | JSON       | Object with a list of Collections contained in the catalog and links |
-| `/collections/{collectionId}` | Collection | Returns single Collection JSON                                       |
+| Endpoint | Returns | Description |
+| -------- | ------- | ----------- |
+| `/`                           | Catalog        | Landing Page and root Catalog |
+| `/api`                        | OAFeat OpenAPI | The OpenAPI service description. The path for this endpoint is only recommended to be `/api`, but may be another path. |
+| `/collections`                | JSON           | Object with a list of Collections contained in the catalog and links |
+| `/collections/{collectionId}` | Collection     | Returns single Collection JSON |
 
 STAC API's implementing the Collections class must support HTTP GET operation at `/collections`, with the return JSON document consisting
 of an array of all STAC Collections and an array of Links.
 
 ## Example
 
+Below is a minimal example, but captures the essence. Each collection object must be a valid STAC 
+[Collection](../stac-spec/collection-spec/README.md), and each must have a `self` link that communicates its canonical location. And then 
+the links section must include a `self` link, and it must also link to alternate representations (like html) of the collection.
+
 ```json
 {
-	"collections": [
-		{
-			"stac_version": "1.0.0",
-			"stac_extensions": [ ],
-			"id": "cool-data",
-			"title": "Cool Data from X Satellite",
-			"description": "A lot of awesome words describing the data",
-			"license": "CC-BY",
-			"extent": {
-				"spatial": {
-					"bbox": [[-135.17, 36.83, -51.24, 62.25]]
-				},
-				"temporal": {
-					"interval": [["2009-01-01T00:00:00Z",null]]
-				}
-			},
-			"links": [
-				{
-					"rel": "root",
-					"type": "application/json",
-					"href": "https://myservice.com"
-				},
-				{
-					"rel": "parent",
-					"type": "application/json",
-					"href": "https://myservice.com"
-				},
-				{
-					"rel": "self",
-					"type": "application/json",
-					"href": "https://myservice.com/collections/cool-data"
-				},
-				{
-					"rel": "items",
-					"type": "application/json",
-					"href": "https://myservice.com/collections/cool-data/items"
-				}
-			],
-		}
-	],
-	"links": [
-		{
-			"rel": "root",
-			"type": "application/json",
-			"href": "https://myservice.com"
-		},
-		{
-			"rel": "self",
-			"type": "application/json",
-			"href": "https://myservice.com/collections"
-		}
-	]
+  "collections": [
+    {
+      "stac_version": "1.0.0",
+      "stac_extensions": [ ],
+      "id": "cool-data",
+      "title": "Cool Data from X Satellite",
+      "description": "A lot of awesome words describing the data",
+      "type": "Collection",
+      "license": "CC-BY",
+      "extent": {
+        "spatial": {
+          "bbox": [[-135.17, 36.83, -51.24, 62.25]]
+        },
+        "temporal": {
+          "interval": [["2009-01-01T00:00:00Z",null]]
+        }
+      },
+      "links": [
+        {
+          "rel": "root",
+          "type": "application/json",
+          "href": "https://myservice.com"
+        },
+        {
+          "rel": "parent",
+          "type": "application/json",
+          "href": "https://myservice.com"
+        },
+        {
+          "rel": "self",
+          "type": "application/json",
+          "href": "https://myservice.com/collections/cool-data"
+        },
+        {
+          "rel": "items",
+          "type": "application/json",
+          "href": "https://myservice.com/collections/cool-data/items"
+        }
+      ],
+    }
+  ],
+  "links": [
+    {
+      "rel": "root",
+      "type": "application/json",
+      "href": "https://myservice.com"
+    },
+    {
+      "rel": "self",
+      "type": "application/json",
+      "href": "https://myservice.com/collections"
+    }
+  ]
 }
 ```
-
-The above is a minimal example, but captures the essence. Each collection object must be a valid STAC 
-[Collection](../stac-spec/collection-spec/README.md), and each should have a `self` link that communicates its canonical location. And then 
-the links section must include a `self` link, and it should also link to alternate representations (like html) of the collection.
-
-Each collection must also be accessible from `/collections/{collectionId}`. Usually this will be the location provided by the `self` link,
-but implementations may choose to list the canonical location elsewhere. But `/collections/{collectionId}` must always contain the response, 
-and if the canonical location is elsewhere it is recommended to include a `rel` of `canonical` from `/collections/{collectionId}` to that location.
-
-## Conformance
-
-Any implementation that provides the STAC Collection functionality described above must add `http://stacspec.org/spec/api/1.0.0-beta.3/collections`,
-the conformance URI, to the `conformsTo` JSON at the landing page.
-
-The core STAC landing page (`/`) must also include a link with a `rel` of `data` that links to the `/collections` endpoint.
-
-**NOTE**: *When this aligns with OGC API - Common it will also need to add it to the `/conformance` endpoint.*
diff --git a/collections/openapi.yaml b/collections/openapi.yaml
@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: STAC API - Collections
-  version: '1.0.0-beta.3'
+  version: '1.0.0-beta.4'
   description: >-
     This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Core
     specification.  This is a subset of the STAC API - Collections specification.
@@ -38,13 +38,13 @@ paths:
               schema:
                 $ref: '../core/openapi.yaml#/components/schemas/landingPage'
               example:
-                stac_version: 1.0.0-beta.3
+                stac_version: 1.0.0-beta.4
                 type: Catalog
                 id: sentinel
                 title: Copernicus Sentinel Imagery
                 description: Catalog of Copernicus Sentinel 1 and 2 imagery.
                 conformsTo:
-                  - 'https://api.stacspec.org/v1.0.0-beta.3/core'
+                  - 'https://api.stacspec.org/v1.0.0-beta.4/core'
                   - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core'
                   - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30'
                   - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson'