From d18bf726eff60fd4706ed7422803c1b88c9f8cae Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Fri, 13 Jan 2023 10:30:13 -0500 Subject: [PATCH 01/14] clarify media types in examples --- CHANGELOG.md | 2 +- core/README.md | 34 +++++++------------ .../examples/itemcollection-sample-full.json | 19 +++++++---- item-search/examples.md | 6 ++++ 4 files changed, 32 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ffc9aa55..14bc1e69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Item Search `limit` parameter semantics have been changed again to align with the current OAFeat definition, rather than the inconsistent definition in [version 1.0](http://www.opengis.net/doc/IS/ogcapi-features-1/1.0). The new behavior is that if a client requests a limit value above the maximum advertised by the server, that the server should treat the request as if the limit parameter were the maximum value. It must not respond with a error because the the limit value, and must respond with no more than that many items. -## [1.0.0-rc.2] - 2022-11-01 +## [v1.0.0-rc.2] - 2022-11-01 ### Added diff --git a/core/README.md b/core/README.md index ac750ecf..b3364e78 100644 --- a/core/README.md +++ b/core/README.md @@ -7,14 +7,6 @@ - [Extensions](#extensions) - [Structuring Catalog Hierarchies](#structuring-catalog-hierarchies) -- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.2/core)), -- **Conformance URIs:** - - - - -- **[Maturity Classification](../README.md#maturity-classification):** Candidate -- **Dependencies**: None - and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas. - All STAC API implementations must implement the *STAC API - Core* specification. The conformance class requires a server to provide a valid [STAC Catalog](../stac-spec/catalog-spec/catalog-spec.md) that also includes a `conformsTo` @@ -44,7 +36,7 @@ Recommendations for supporting both of these discussed in [Structuring Catalog H The root of a STAC API is the Landing Page. This resource is the starting point to determine what behaviors the API supports via the `conformsTo` array and the URIs of resources via link relations. -Support for this type of behavior in a web API is known as +Support for this type of behavior in a web API is known as [Hypermedia as the Engine of Application State (HATEOAS)](https://en.wikipedia.org/wiki/HATEOAS). A hypermedia-driven web API provides a robust, consistent, and flexible mechanism for interacting with remote resources. STAC API relies heavily on hypermedia for API resource discovery and navigation. @@ -90,11 +82,11 @@ Recommendations for structuring Catalogs hierarchically can be found in The following Link relations must 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` | OAFeat | The service description in a machine-readable format | +| **rel** | **href** | **Media Type** | **From** | **Description** | +| -------------- | -------- | ---------------- | --------- | ---------------------------------------------------- | +| `root` | `/` | application/json | STAC Core | The root URI | +| `self` | `/` | application/json | OAFeat | Self reference, same as root URI | +| `service-desc` | `/api` | various | OAFeat | The service description in a machine-readable format | The path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML), @@ -106,9 +98,9 @@ page, for example, in the form of [Redoc](https://github.com/Redocly/redoc) inte , but any format is allowed. The Link `type` field should correspond to whatever format or formats are supported by this endpoint, e.g., `text/html`. -| **rel** | **href** | **From** | **Description** | -| ------------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `service-doc` | `/api.html` | OAFeat | A human-consumable service description. The path for this endpoint is only recommended to be `/api.html`, but may be another path. | +| **rel** | **href** | **Media Type** | **From** | **Description** | +| ------------- | ----------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `service-doc` | `/api.html` | text/html | OAFeat | A human-consumable service description. The path for this endpoint is only recommended to be `/api.html`, but may be another path. | Additionally, `child` relations may exist to child Catalogs and Collections and `item` relations to Items. These relations form a directed graph that enables traversal from a root catalog or collection to items. @@ -116,10 +108,10 @@ relations form a directed graph that enables traversal from a root catalog or co If all Items in a Catalog can be accessed by traversing these links, the browseable conformance class should be advertised also. -| **rel** | **href** | **From** | **Description** | -| ------- | -------- | --------- | -------------------------------------- | -| `child` | various | STAC Core | The child STAC Catalogs & Collections. | -| `item` | various | STAC Core | The child STAC Items. | +| **rel** | **href** | **Media Type** | **From** | **Description** | +| ------- | -------- | -------------------- | --------- | -------------------------------------- | +| `child` | various | application/json | STAC Core | The child STAC Catalogs & Collections. | +| `item` | various | application/geo+json | STAC Core | The child STAC Items. | While it is valid to have `item` links from the landing page, most STAC API implementations serve large numbers of features, so they will typically use several layers of intermediate `child` links before diff --git a/fragments/itemcollection/examples/itemcollection-sample-full.json b/fragments/itemcollection/examples/itemcollection-sample-full.json index 8f18084d..ff1cf612 100644 --- a/fragments/itemcollection/examples/itemcollection-sample-full.json +++ b/fragments/itemcollection/examples/itemcollection-sample-full.json @@ -7,7 +7,7 @@ "stac_version": "1.0.0", "stac_extensions": [], "type": "Feature", - "id": "CS3-20160503_132131_05", + "id": "cs3-20160503_132131_05", "bbox": [ -122.59750209, 37.48803556, @@ -56,24 +56,28 @@ } ] }, - "collection": "CS3", + "collection": "cs3", "links": [ { "rel": "self", - "href": "https://stac-api.example.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.json" + "type": "application/json", + "href": "https://stac-api.example.com/catalog/cs3-20160503_132130_04/cs3-20160503_132130_04.json" }, { "rel": "collection", - "href": "https://stac-api.example.com/catalog/CS3-20160503_132130_04/catalog.json" + "type": "application/json", + "href": "https://stac-api.example.com/catalog/cs3-20160503_132130_04/catalog.json" } ], "assets": { "analytic": { - "href": "https://stac-api.example.com/catalog/CS3-20160503_132130_04/analytic.tif", + "href": "https://stac-api.example.com/catalog/cs3-20160503_132130_04/analytic.tif", + "type": "image/tiff; application=geotiff; profile=cloud-optimized", "title": "4-Band Analytic" }, "thumbnail": { - "href": "https://stac-api.example.com/catalog/CS3-20160503_132130_04/thumbnail.png", + "href": "https://stac-api.example.com/catalog/cs3-20160503_132130_04/thumbnail.png", + "type": "image/png", "title": "Thumbnail", "roles": [ "thumbnail" @@ -85,7 +89,8 @@ "links": [ { "rel": "self", - "href": "http://stac.example.com/search?collection=CS3" + "type": "application/geo+json", + "href": "http://stac.example.com/search?collection=cs3" } ] } \ No newline at end of file diff --git a/item-search/examples.md b/item-search/examples.md index 2086cb58..744171b7 100644 --- a/item-search/examples.md +++ b/item-search/examples.md @@ -21,12 +21,14 @@ GET /search?collections=mycollection&bbox=160.6,-55.95,-170,-25.89&limit=100&dat ### Paging Examples #### Simple GET based search + Request: ``` HTTP GET /search?bbox=-110,39.5,-105,40.5 ``` Response with `200 OK`: + ```json { "type": "FeatureCollection", @@ -40,10 +42,13 @@ Response with `200 OK`: ] } ``` + Following the link `https://stac-api.example.com/search?page=2` will send the user to the next page of results. #### POST search with body and merge fields + Request to `HTTP POST /search`: + ```json { "bbox": [-110, 39.5, -105, 40.5] @@ -51,6 +56,7 @@ Request to `HTTP POST /search`: ``` Response with `200 OK`: + ```json { "type": "FeatureCollection", From ee444832164ce316ea70024d34f189b82409ccfe Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Fri, 13 Jan 2023 10:41:09 -0500 Subject: [PATCH 02/14] re-add header --- core/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/core/README.md b/core/README.md index b3364e78..f789c49c 100644 --- a/core/README.md +++ b/core/README.md @@ -7,6 +7,14 @@ - [Extensions](#extensions) - [Structuring Catalog Hierarchies](#structuring-catalog-hierarchies) +- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.2/core)), +- **Conformance URIs:** + - + - +- **[Maturity Classification](../README.md#maturity-classification):** Candidate +- **Dependencies**: None + and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas. + All STAC API implementations must implement the *STAC API - Core* specification. The conformance class requires a server to provide a valid [STAC Catalog](../stac-spec/catalog-spec/catalog-spec.md) that also includes a `conformsTo` From 310c8f91c669026778d0ea9cf81d2df2367f231a Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Fri, 13 Jan 2023 15:33:53 -0500 Subject: [PATCH 03/14] more media type polish --- core/README.md | 30 ++++++++++++++++++------------ item-search/README.md | 4 ++++ item-search/examples.md | 7 +++++++ ogcapi-features/README.md | 37 ++++++++++++++++++++++--------------- 4 files changed, 51 insertions(+), 27 deletions(-) diff --git a/core/README.md b/core/README.md index f789c49c..76361516 100644 --- a/core/README.md +++ b/core/README.md @@ -1,12 +1,16 @@ # STAC API - Core Specification - [STAC API - Core Specification](#stac-api---core-specification) + - [Summary](#summary) + - [Overview](#overview) - [Link Relations](#link-relations) - [Endpoints](#endpoints) - [Example Landing Page for STAC API - Core](#example-landing-page-for-stac-api---core) - [Extensions](#extensions) - [Structuring Catalog Hierarchies](#structuring-catalog-hierarchies) +## Summary + - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.2/core)), - **Conformance URIs:** - @@ -15,6 +19,8 @@ - **Dependencies**: None and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas. +## Overview + All STAC API implementations must implement the *STAC API - Core* specification. The conformance class requires a server to provide a valid [STAC Catalog](../stac-spec/catalog-spec/catalog-spec.md) that also includes a `conformsTo` @@ -143,10 +149,10 @@ This conformance class also requires for the endpoints in the [STAC API - Core]( These endpoints are required, with details provided in this [OpenAPI specification document](openapi.yaml). -| Endpoint | Returns | Description | -| -------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `/` | [Catalog](../stac-spec/catalog-spec/README.md) | Landing page, links to API capabilities | -| `/api` | any | The service description of the service from the `service-desc` link `rel`. The path is only recommended to be `/api`, and is at the discretion of the implementer. | +| **Endpoint** | **Media Type** | **Returns** | **Description** | +| -------- | ----- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `/` | application/json | [Catalog](../stac-spec/catalog-spec/README.md) | Landing page, links to API capabilities | +| `/api` | various | any | The service description of the service from the `service-desc` link `rel`. The path is only recommended to be `/api`, and is at the discretion of the implementer. | The service description endpoint may return any specification format. It is recommended to use OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML), `application/vnd.oai.openapi+json;version=3.0` (3.0 JSON), @@ -161,22 +167,22 @@ class for OpenAPI 3.1, but may in the future. If sub-catalogs are used, it is **recommended** that these use the endpoint `/catalogs/{catalogId}` to avoid conflicting with other endpoints from the root. -| Endpoint | Returns | Description | -| ----------------------- | ---------------------------------------------- | -------------------- | -| `/catalogs/{catalogId}` | [Catalog](../stac-spec/catalog-spec/README.md) | child Catalog object | +| **Endpoint** | **Media Type** | **Returns** | **Description** | +| ----------------------- | -- | -------------------------------------------- | -------------------- | +| `/catalogs/{catalogId}` | application/json | [Catalog](../stac-spec/catalog-spec/README.md) | child Catalog object | ## Example Landing Page for STAC API - Core This JSON is what would be expected from an API that only implements *STAC API - Core*. It is a valid STAC Catalog -with additional Links and a `conformsTo` attribute. In practice, -most APIs will also implement other conformance classes, and those will be reflected in the `links` and -`conformsTo` attribute. A more typical Landing Page example is in +with additional Links and a `conformsTo` attribute. In practice, +most APIs will also implement other conformance classes, and those will be reflected in the `links` and +`conformsTo` attribute. A more typical Landing Page example is in the [overview](../overview.md#example-landing-page) document. This particular catalog provides both the ability to browse down to child Catalog objects through its `child` links, and also provides the search endpoint to be able to search across items in its collections. Note that some of those links are not required and other servers may provide -different conformance classes and a different set of links. +different conformance classes and a different set of links. ```json { @@ -282,7 +288,7 @@ per provider (e.g., Sentinel-2), per domain (e.g., cloud data), or per form of d Going the other direction, collections can be sub-grouped into smaller catalogs. For example, this example groups a catalog of Landsat 8 Collection 1 items by path, row, and date (the path/row system is used by this -product for gridding). +product for gridding). - / (root) - /catalogs/landsat_8_c1 diff --git a/item-search/README.md b/item-search/README.md index 1f47f2d5..a6fbddc8 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -15,6 +15,8 @@ - [Example Landing Page for STAC API - Item Search](#example-landing-page-for-stac-api---item-search) - [Extensions](#extensions) +## Summary + - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.2/item-search)) - **Conformance URIs:** - @@ -22,6 +24,8 @@ - **Dependencies**: [STAC API - Core](../core) - **Examples**: [examples.md](examples.md) +## Overview + The *STAC API - Item Search* specification defines the *STAC API - Item Search* conformance class (), which provides the ability to search for STAC [Item](../stac-spec/item-spec/README.md) diff --git a/item-search/examples.md b/item-search/examples.md index 744171b7..4dafd9db 100644 --- a/item-search/examples.md +++ b/item-search/examples.md @@ -93,6 +93,7 @@ This can be even more effective when using continuation tokens on the server, as repeated in the subsequent request: Response with `200 OK`: + ```json { "rel": "next", @@ -104,9 +105,11 @@ Response with `200 OK`: } } ``` + The above link tells the client not to merge (default of false) so it is only required to pass the next token in the body. Request to `POST /search`: + ```json { "next": "a9f3kfbc98e29a0da23" @@ -114,7 +117,9 @@ Request to `POST /search`: ``` #### POST search using headers + Request to `HTTP POST /search`: + ```json { "bbox": [-110, 39.5, -105, 40.5], @@ -124,6 +129,7 @@ Request to `HTTP POST /search`: ``` Response with `200 OK`: + ```json { "type": "FeatureCollection", @@ -145,6 +151,7 @@ Response with `200 OK`: This tells the client to POST to the search endpoint with the header `Search-After` to obtain the next set of results: Request: + ``` POST /search Search-After: LC81530752019135LGN00 diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index c75177f1..19cdedda 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -1,6 +1,8 @@ # STAC API - Collections and Features Specification - [STAC API - Collections and Features Specification](#stac-api---collections-and-features-specification) + - [Summary](#summary) + - [Overview](#overview) - [Conformance Classes](#conformance-classes) - [STAC API - Features](#stac-api---features) - [STAC API - Collections](#stac-api---collections) @@ -16,6 +18,8 @@ - [Example Collection Endpoint](#example-collection-endpoint) - [Extensions](#extensions) +## Summary + *based on [**OGC API - Features - Part 1: Core**](https://www.ogc.org/standards/ogcapi-features)* - **OpenAPI specifications:** @@ -30,6 +34,8 @@ - [OGC API - Features](https://www.ogc.org/standards/ogcapi-features) uses all the OGC API - Features openapi fragments to describe returning STAC Item objects. +## Overview + The *STAC API - Collections and Features* specification extends the [OGC API - Features - Part 1: Core](https://docs.opengeospatial.org/is/17-069r3/17-069r3.html) (OAFeat) specification. OAFeat @@ -190,8 +196,8 @@ or `token` and any additional filter parameters if given and required. For examp "links": [ { "rel": "next", + "type": "application/geo+json", "href": "https://stac-api.example.com/collections/my_collection/items?page=2" - "type": "application/geo+json" } ] ``` @@ -236,20 +242,21 @@ In our simple example of numerical pages, the response for `page=3` would have a `links` array containing these two Links indicating the URLs for the next (page=4) and previous (page=2) pages: -```none -"links": [ - ... - { - "rel": "prev", - "href": "https://stac-api.example.com/collections?page=2" - "type": "application/json" - }, - { - "rel": "next", - "href": "https://stac-api.example.com/collections?page=4" - "type": "application/json" - } -] +```json +{ + "links": [ + { + "rel": "prev", + "type": "application/json", + "href": "https://stac-api.example.com/collections?page=2" + }, + { + "rel": "next", + "type": "application/json", + "href": "https://stac-api.example.com/collections?page=4" + } + ] +} ``` In addition to supporting query parameters in the URL value of the `href` field, From c8a3caae5cec279fdcc3fd00e81a27dae4773ff2 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Fri, 13 Jan 2023 15:53:57 -0500 Subject: [PATCH 04/14] polish tables --- item-search/README.md | 18 +++++++++------- ogcapi-features/README.md | 45 ++++++++++++++++++++------------------- 2 files changed, 33 insertions(+), 30 deletions(-) diff --git a/item-search/README.md b/item-search/README.md index a6fbddc8..ddda2f01 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -1,6 +1,8 @@ # STAC API - Item Search - [STAC API - Item Search](#stac-api---item-search) + - [Summary](#summary) + - [Overview](#overview) - [Link Relations](#link-relations) - [Endpoints](#endpoints) - [Query Parameters and Fields](#query-parameters-and-fields) @@ -51,9 +53,9 @@ This conformance class also requires implementation of the link relations in the The following Link relations must exist in the Landing Page (root). -| **rel** | **href** | **From** | **Description** | -| -------- | --------- | ---------------------- | --------------------------- | -| `search` | `/search` | STAC API - Item Search | URI for the Search endpoint | +| **rel** | **href** | **Media Type** | **From** | **Description** | +| -------- | --------- | -------------------- | ---------------------- | --------------------------- | +| `search` | `/search` | application/geo+json | STAC API - Item Search | URI for the Search endpoint | This `search` link relation must have a `type` of `application/geo+json`. If no `method` attribute is specified, it is assumed to represent a GET request. If the server supports both GET and POST requests, two links should be included, one with a `method` of `GET` one with a `method` of `POST`. @@ -65,9 +67,9 @@ with, but these other types are not part of the STAC API requirements. This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented. -| Endpoint | Returns | Description | -| --------- | --------------- | --------------- | -| `/search` | Item Collection | Search endpoint | +| **Endpoint** | **Returns** | **Media Type** | **From** | **Description** | +| ------------ | --------------- | -------------------- | ---------------------- | --------------- | +| `/search` | Item Collection | application/geo+json | STAC API - Item Search | Search endpoint | ## Query Parameters and Fields @@ -97,7 +99,7 @@ For more examples see [examples.md](examples.md). The core parameters for STAC search are defined by OAFeat, and STAC adds a few parameters for convenience. -| Parameter | Type | Source API | Description | +| **Parameter** | **Type** | **Source API** | **Description** | | ----------- | ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | limit | integer | OAFeat | The maximum number of results to return (page size). | | bbox | \[number] | OAFeat | Requested bounding box. | @@ -185,7 +187,7 @@ execute a subsequent request for the next page of results. The following fields have been added to the Link object specification for the API spec: -| Parameter | Type | Description | +| **Parameter** | **Type** | **Description** | | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | method | string | The HTTP method of the request, usually `GET` or `POST`. Defaults to `GET` | | headers | object | A dictionary of header values that must be included in the next request | diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 19cdedda..b152d22a 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -64,6 +64,7 @@ The *STAC API - Collections* ( requires only the subset of the behavior of Features that relates to Collections. This subset is: + - the `data` link relation on the landing page - the `/collections` and `/collections/{collection_id}` endpoints @@ -98,31 +99,31 @@ This conformance class also requires implementation of the link relations in the The following Link relations must exist in the Landing Page (root). -| **rel** | **href** | **From** | **Description** | -| ------------- | -------------- | -------- | ------------------- | -| `conformance` | `/conformance` | OAFeat | Conformance URI | -| `data` | `/collections` | OAFeat | List of Collections | +| **rel** | **href** | **Media Type** | **From** | **Description** | +| ------------- | -------------- | ---------------- | -------- | ------------------- | +| `conformance` | `/conformance` | application/json | OAFeat | Conformance URI | +| `data` | `/collections` | application/json | OAFeat | List of Collections | The following Link relations must exist in the `/collections` endpoint response. -| **rel** | **href** | **From** | **Description** | -| ------- | -------------- | --------- | --------------- | -| `root` | `/` | STAC Core | The root URI | -| `self` | `/collections` | OAFeat | Self reference | +| **rel** | **href** | **Media Type** | **From** | **Description** | +| ------- | -------------- | ---------------- | --------- | --------------- | +| `root` | `/` | application/json | STAC Core | The root URI | +| `self` | `/collections` | application/json | OAFeat | Self reference | The following Link relations must 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 | +| **rel** | **href** | **Media Type** | **From** | **Description** | +| -------- | ----------------------------- | ---------------- | --------- | ------------------------------------------ | +| `root` | `/` | application/json | STAC Core | The root URI | +| `parent` | `/` | application/json | OAFeat | Parent reference, usually the root Catalog | +| `self` | `/collections/{collectionId}` | application/json | OAFeat | Self reference | 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. | +| **rel** | **href** | **Media Type** | **From** | **Description** | +| ----------- | -------- | -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `canonical` | various | 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 @@ -134,12 +135,12 @@ This conformance class also requires for the endpoints in the [STAC API - Core]( The *OGC API - Features* endpoints are shown below, with details provided in the OpenAPI specifications for [Features](openapi-features.yaml) or [Collections](openapi-collections.yaml). -| Endpoint | Returns | Description | -| ----------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | -| `/collections` | JSON | Object containing an array of Collection objects in the Catalog, and Link relations | -| `/collections/{collectionId}` | [Collection](../stac-spec/collection-spec/README.md) | Returns single Collection JSON | -| `/collections/{collectionId}/items` | [ItemCollection](../fragments/itemcollection/README.md) | GeoJSON FeatureCollection-conformant entity of Item objects in collection | -| `/collections/{collectionId}/items/{featureId}` | [Item](../stac-spec/item-spec/README.md) | Returns single Item (GeoJSON Feature) | +| **Endpoint** | **Returns** | **Media Type** | **Description** | +| ----------------------------------------------- | -------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `/collections` | application/json | JSON | Object containing an array of Collection objects in the Catalog, and Link relations | +| `/collections/{collectionId}` | application/json | [Collection](../stac-spec/collection-spec/README.md) | Returns single Collection JSON | +| `/collections/{collectionId}/items` | application/geo+json | [ItemCollection](../fragments/itemcollection/README.md) | GeoJSON FeatureCollection-conformant entity of Item objects in collection | +| `/collections/{collectionId}/items/{featureId}` | application/geo+json | [Item](../stac-spec/item-spec/README.md) | Returns single Item (GeoJSON Feature) | The OGC API - Features is a standard API that represents collections of geospatial data. It defines a RESTful interface to query geospatial data, with GeoJSON as a main return type. With OAFeat you can return any `Feature`, which is a geometry From 01b03c45bb165c19490c56a025be286d33763cd9 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Fri, 13 Jan 2023 15:55:10 -0500 Subject: [PATCH 05/14] polish tables --- item-search/README.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/item-search/README.md b/item-search/README.md index ddda2f01..84f3c59f 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -99,14 +99,14 @@ For more examples see [examples.md](examples.md). The core parameters for STAC search are defined by OAFeat, and STAC adds a few parameters for convenience. -| **Parameter** | **Type** | **Source API** | **Description** | -| ----------- | ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| limit | integer | OAFeat | The maximum number of results to return (page size). | -| bbox | \[number] | OAFeat | Requested bounding box. | -| datetime | string | OAFeat | Single date+time, or a range ('/' separator), formatted to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). Use double dots `..` for open date ranges. | -| intersects | GeoJSON Geometry | STAC | Searches items by performing intersection between their geometry and provided GeoJSON geometry. All GeoJSON geometry types must be supported. | -| ids | \[string] | STAC | Array of Item ids to return. | -| collections | \[string] | STAC | Array of one or more Collection IDs that each matching Item must be in. | +| **Parameter** | **Type** | **Source API** | **Description** | +| ------------- | ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| limit | integer | OAFeat | The maximum number of results to return (page size). | +| bbox | \[number] | OAFeat | Requested bounding box. | +| datetime | string | OAFeat | Single date+time, or a range ('/' separator), formatted to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). Use double dots `..` for open date ranges. | +| intersects | GeoJSON Geometry | STAC | Searches items by performing intersection between their geometry and provided GeoJSON geometry. All GeoJSON geometry types must be supported. | +| ids | \[string] | STAC | Array of Item ids to return. | +| collections | \[string] | STAC | Array of one or more Collection IDs that each matching Item must be in. | See [examples](examples.md) for some example requests. @@ -187,12 +187,12 @@ execute a subsequent request for the next page of results. The following fields have been added to the Link object specification for the API spec: -| **Parameter** | **Type** | **Description** | -| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| method | string | The HTTP method of the request, usually `GET` or `POST`. Defaults to `GET` | -| headers | object | A dictionary of header values that must be included in the next request | -| body | object | A JSON object containing fields/values that must be included in the body of the next request | -| merge | boolean | If `true`, the headers/body fields in the `next` link must be merged into the original request and be sent combined in the next request. Defaults to `false` | +| **Parameter** | **Type** | **Description** | +| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| method | string | The HTTP method of the request, usually `GET` or `POST`. Defaults to `GET` | +| headers | object | A dictionary of header values that must be included in the next request | +| body | object | A JSON object containing fields/values that must be included in the body of the next request | +| merge | boolean | If `true`, the headers/body fields in the `next` link must be merged into the original request and be sent combined in the next request. Defaults to `false` | The implementor has the freedom to decide exactly how to apply these extended fields for their particular pagination mechanism. The same freedom that exists for GET requests, where the actual URL parameter used to defined the next page From 60be748e4489cd22283422c5c0e98bc7a7a39f1b Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Fri, 13 Jan 2023 15:55:54 -0500 Subject: [PATCH 06/14] polish tables --- core/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/core/README.md b/core/README.md index 76361516..64719419 100644 --- a/core/README.md +++ b/core/README.md @@ -149,10 +149,10 @@ This conformance class also requires for the endpoints in the [STAC API - Core]( These endpoints are required, with details provided in this [OpenAPI specification document](openapi.yaml). -| **Endpoint** | **Media Type** | **Returns** | **Description** | -| -------- | ----- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `/` | application/json | [Catalog](../stac-spec/catalog-spec/README.md) | Landing page, links to API capabilities | -| `/api` | various | any | The service description of the service from the `service-desc` link `rel`. The path is only recommended to be `/api`, and is at the discretion of the implementer. | +| **Endpoint** | **Media Type** | **Returns** | **Description** | +| ------------ | ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `/` | application/json | [Catalog](../stac-spec/catalog-spec/README.md) | Landing page, links to API capabilities | +| `/api` | various | any | The service description of the service from the `service-desc` link `rel`. The path is only recommended to be `/api`, and is at the discretion of the implementer. | The service description endpoint may return any specification format. It is recommended to use OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML), `application/vnd.oai.openapi+json;version=3.0` (3.0 JSON), @@ -167,8 +167,8 @@ class for OpenAPI 3.1, but may in the future. If sub-catalogs are used, it is **recommended** that these use the endpoint `/catalogs/{catalogId}` to avoid conflicting with other endpoints from the root. -| **Endpoint** | **Media Type** | **Returns** | **Description** | -| ----------------------- | -- | -------------------------------------------- | -------------------- | +| **Endpoint** | **Media Type** | **Returns** | **Description** | +| ----------------------- | ---------------- | ---------------------------------------------- | -------------------- | | `/catalogs/{catalogId}` | application/json | [Catalog](../stac-spec/catalog-spec/README.md) | child Catalog object | ## Example Landing Page for STAC API - Core From 95acf07c4617e8c564bc522ea8eb382018cf54b1 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 16 Jan 2023 12:56:46 -0500 Subject: [PATCH 07/14] make Link object field 'type' required --- CHANGELOG.md | 40 ++++++++++++++++++++++++++-------------- core/commons.yaml | 10 ++++++++++ 2 files changed, 36 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 14bc1e69..d1cf6978 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,5 @@ # Changelog + All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), @@ -8,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- Link field `type` is now required for all Link objects. - Item Search `limit` parameter semantics have been changed again to align with the current OAFeat definition, rather than the inconsistent definition in [version 1.0](http://www.opengis.net/doc/IS/ogcapi-features-1/1.0). The new behavior is that if a client requests a limit value above the maximum advertised by the server, that the server should treat the request as if the limit parameter were the maximum value. It must not respond with a error because the the limit value, and must respond with no more than that many items. ## [v1.0.0-rc.2] - 2022-11-01 @@ -20,18 +22,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - The Collections specification has been incorporated into the *Features* specification, but remains as - a separate conformance class. + a separate conformance class. - The Browseable specification has been incorporated into the *Core* specification, but remains as a separate conformance class. - Extensions moved to standalone specification repositories: - - [Items and Collections API Version](https://github.com/stac-api-extensions/version) - - [Fields](https://github.com/stac-api-extensions/fields) - - [Filter](https://github.com/stac-api-extensions/filter) - - [Context](https://github.com/stac-api-extensions/context) - - [Sort](https://github.com/stac-api-extensions/sort) - - [Transaction](https://github.com/stac-api-extensions/transaction) - - [Query](https://github.com/stac-api-extensions/query) - - [Children](https://github.com/stac-api-extensions/children) + - [Items and Collections API Version](https://github.com/stac-api-extensions/version) + - [Fields](https://github.com/stac-api-extensions/fields) + - [Filter](https://github.com/stac-api-extensions/filter) + - [Context](https://github.com/stac-api-extensions/context) + - [Sort](https://github.com/stac-api-extensions/sort) + - [Transaction](https://github.com/stac-api-extensions/transaction) + - [Query](https://github.com/stac-api-extensions/query) + - [Children](https://github.com/stac-api-extensions/children) ### Fixed @@ -42,7 +44,7 @@ service description must return a 400 Bad Request status code. ### Added -- The CQL2 Accent and Case-insensitive Comparison +- The CQL2 Accent and Case-insensitive Comparison (`http://www.opengis.net/spec/cql2/1.0/conf/accent-case-insensitive-comparison`) conformance class adds the ACCENTI and CASEI functions for case-insensitive comparison. These replace the UPPER and LOWER psuedo-functions that were previously part of the Advanced Comparison Operators class. @@ -55,7 +57,7 @@ service description must return a 400 Bad Request status code. - Clarified behavior of Transaction Extension endpoints: - PUT and PATCH of a body that changes the `collection` or `id` is disallowed. - POST, PUT, and PATCH do not need to include the `collection` attribute, as it should be derived from the URL. - - POST and PUT can be used with a body that is at least a GeoJSON Feature, but does not have to be an Item, but for which + - POST and PUT can be used with a body that is at least a GeoJSON Feature, but does not have to be an Item, but for which the server can derive a valid Item, e.g., by populating the id and collection fields or adding links - Likewise, POST can be used with a body of a FeatureCollection that contains features that meet the same constraints. - Specifications now use the term "must" instead of "shall". The semantics of these words are identical. @@ -161,20 +163,23 @@ service description must return a 400 Bad Request status code. ## [v1.0.0-beta.3] - 2021-08-06 ### Added + - Added STAC API - Collections definition (subset of STAC API - Features) - More thorough definitions for valid `datetime` and `bbox` query parameter values. ### Changed -- Query extension not deprecated; recommendation to use Filter (https://github.com/radiantearth/stac-api-spec/pull/157) + +- Query extension not deprecated; recommendation to use Filter () - Filter Extension conformance classes refactored to better align with STAC API use cases. - Renamed conformance class "Queryable First Operand" - (https://api.stacspec.org/v1.0.0-beta.3/item-search#filter:queryable-first-operand) to + () to "Queryable Second Operand" - (https://api.stacspec.org/v1.0.0-beta.3/item-search#filter:queryable-second-operand) + () ### Deprecated ### Removed + - Remove stac_version and stac_extensions fields in ItemCollection ### Fixed @@ -182,32 +187,38 @@ service description must return a 400 Bad Request status code. ## [v1.0.0-beta.2] - 2021-06-01 ### Added + - Added Filter extension to integrate OAFeat Part 3 CQL - Catalog and Collection definitions now have required field "type" - Added recommendation to enable CORS for public APIs ### Changed + - Updated all STAC versions to 1.0.0 - Passing the `ids` parameter to an item search does not deactivate other query parameters [#125](https://github.com/radiantearth/stac-api-spec/pull/125) - The first extent in a Collection is always the overall extent, followed by more specific extents. [opengeospatial/ogcapi-features#520](https://github.com/opengeospatial/ogcapi-features/pull/520) ### Deprecated + - Query extension is now deprecated. Replaced by the Filter extension using OGC CQL. ### Removed ### Fixed + - Updated text description of root ('/') endpoint (also called landing page) that the return type is a Catalog ## [v1.0.0-beta.1] - 2020-12-10 ### Added + - The landing page returns the conformance classes in a property `conformsTo`, which mirrors `GET /conformances` from OGC APIs. - Conformance classes for all the major functionality and extensions, to be referenced in a new `conformsTo` JSON object in the landing page. - Fragments: reusable OpenAPI documents for sort, filter, fields and context, along with explanation of how they work. - ItemCollection moved from [STAC Core](https://github.com/radiantearth/stac-spec/blob/v0.9.0/item-spec/itemcollection-spec.md) to this repo. ### Changed + - Major re-organization of the content and directory structure to make better conformance classes. - STAC API Core is the landing page (a STAC catalog and conformance information). - Item Search is the `search` cross-collection item search resource. @@ -225,6 +236,7 @@ service description must return a 400 Bad Request status code. ### Removed ### Fixed + - BBOX openapi yaml to only allow 4 or 6 element arrays - Fixed invalid OpenAPI files diff --git a/core/commons.yaml b/core/commons.yaml index afbee37c..8b71b3b9 100644 --- a/core/commons.yaml +++ b/core/commons.yaml @@ -241,11 +241,14 @@ components: links: - rel: self href: 'http://cool-sat.com/collections/Sentinel-2' + type: application/json - rel: root href: 'http://cool-sat.com/collections' + type: application/json - rel: license href: 'https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf' title: Legal notice on the use of Copernicus Sentinel Data and Service Information + type: application/pdf extent: type: object description: |- @@ -385,6 +388,7 @@ components: required: - href - rel + - type properties: href: type: string @@ -646,19 +650,25 @@ components: links: - rel: self href: 'http://cool-sat.com/collections/CS3/items/20160503_132130_04' + type: application/geo+json - rel: root href: 'http://cool-sat.com/collections' + type: application/json - rel: parent href: 'http://cool-sat.com/collections/CS3' + type: application/json - rel: collection href: 'http://cool-sat.com/collections/CS3' + type: application/json assets: analytic: href: 'http://cool-sat.com/static-catalog/CS3/20160503_132130_04/analytic.tif' title: 4-Band Analytic + type: image/tiff; application=geotiff; profile=cloud-optimized thumbnail: href: 'http://cool-sat.com/static-catalog/CS3/20160503_132130_04/thumbnail.png' title: Thumbnail + type: image/png itemId: type: string description: Provider identifier, a unique ID. From 4e5154fb7c6c8a6e5687dcf41a007b490a87e717 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 16 Jan 2023 12:57:42 -0500 Subject: [PATCH 08/14] make Link object field 'type' required --- fragments/itemcollection/openapi.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/fragments/itemcollection/openapi.yaml b/fragments/itemcollection/openapi.yaml index 97425660..f6d156b8 100644 --- a/fragments/itemcollection/openapi.yaml +++ b/fragments/itemcollection/openapi.yaml @@ -31,6 +31,7 @@ components: $ref: '../../core/commons.yaml#/components/schemas/link' example: - rel: next + type: application/json href: >- http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk numberMatched: From 24ed8c986d816c3453d9bfac6cd38a0536576247 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 30 Jan 2023 19:13:52 -0500 Subject: [PATCH 09/14] fix header --- ogcapi-features/README.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index d7b17ded..4dd2c24a 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -19,11 +19,6 @@ - [Extensions](#extensions) ## Summary -<<<<<<< pv/clarify-media-types-2 - -*based on [**OGC API - Features - Part 1: Core**](https://www.ogc.org/standards/ogcapi-features)* -======= ->>>>>>> main - **OpenAPI specifications:** - [STAC API - Features](openapi-features.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-rc.2/ogcapi-features)) From 18dd96c5144167fa44a69c48e37637e29edee21f Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Wed, 1 Feb 2023 23:58:45 -0500 Subject: [PATCH 10/14] linting --- core/README.md | 12 ++++++------ ogcapi-features/README.md | 1 - 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/core/README.md b/core/README.md index 72233fb9..2d528dbd 100644 --- a/core/README.md +++ b/core/README.md @@ -96,11 +96,11 @@ Recommendations for structuring Catalogs hierarchically can be found in The following Link relations must exist in the Landing Page (root). -| **rel** | **href** | **Media Type** | **From** | **Description** | -| -------------- | -------- | ---------------- | --------- | ---------------------------------------------------- | +| **rel** | **href** | **Media Type** | **From** | **Description** | +| -------------- | -------- | ---------------- | --------------- | ---------------------------------------------------- | | `root` | `/` | application/json | STAC API - Core | The root URI | -| `self` | `/` | application/json | OAFeat | Self reference, same as root URI | -| `service-desc` | `/api` | various | OAFeat | The service description in a machine-readable format | +| `self` | `/` | application/json | OAFeat | Self reference, same as root URI | +| `service-desc` | `/api` | various | OAFeat | The service description in a machine-readable format | The path for the `service-desc` endpoint is recommended to be `/api`, but may be another path. Recommended to be OpenAPI 3.0 or 3.1 with media types `application/vnd.oai.openapi` (YAML), @@ -122,8 +122,8 @@ relations form a directed graph that enables traversal from a root catalog or co If all Items in a Catalog can be accessed by traversing these links, the browseable conformance class should be advertised also. -| **rel** | **href** | **Media Type** | **From** | **Description** | -| ------- | -------- | -------------------- | --------- | -------------------------------------- | +| **rel** | **href** | **Media Type** | **From** | **Description** | +| ------- | -------- | -------------------- | --------------- | -------------------------------------- | | `child` | various | application/json | STAC API - Core | The child STAC Catalogs & Collections. | | `item` | various | application/geo+json | STAC API - Core | The child STAC Items. | diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 787c026a..f8bfaf6e 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -119,7 +119,6 @@ The following Link relations must exist in the `/collections` endpoint response. | `root` | `/` | application/json | STAC API - Features, STAC API - Collections | The root URI | | `self` | `/collections` | application/json | OAFeat | Self reference | - ### Collection (/collections/{collectionId}) The following Link relations must exist in the Collection object returned from the `/collections/{collectionId}` endpoint. From 6a927876f7dd1ef9fc02a0599946986a7a03ca2d Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Thu, 2 Feb 2023 08:21:35 -0500 Subject: [PATCH 11/14] remove merge conflict detritus --- ogcapi-features/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index f8bfaf6e..015dbae3 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -113,7 +113,6 @@ The following Link relations must exist in the Landing Page (root). The following Link relations must exist in the `/collections` endpoint response. -<<<<<<< HEAD | **rel** | **href** | **Media Type** | **From** | **Description** | | ------- | -------------- | ---------------- | ------------------------------------------- | --------------- | | `root` | `/` | application/json | STAC API - Features, STAC API - Collections | The root URI | From d726941a5c51838cec62fe7cf1b4a4044a17d6dd Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 13 Feb 2023 21:04:29 -0500 Subject: [PATCH 12/14] unrequire type field --- CHANGELOG.md | 1 - core/commons.yaml | 1 - ogcapi-features/README.md | 4 ++++ 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b8a2bd2c..44651de8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,7 +15,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -- Link field `type` is now required for all Link objects. - Item Search `limit` parameter semantics have been changed again to align with the current OAFeat definition, rather than the inconsistent definition in [version 1.0](http://www.opengis.net/doc/IS/ogcapi-features-1/1.0). The new behavior is that if a client requests a limit value above the maximum advertised by the server, that the server should treat the request as if the limit parameter were the maximum value. It must not respond with a error because the the limit value, and must respond with no more than that many items. ## [v1.0.0-rc.2] - 2022-11-01 diff --git a/core/commons.yaml b/core/commons.yaml index be1281f2..91c6407f 100644 --- a/core/commons.yaml +++ b/core/commons.yaml @@ -388,7 +388,6 @@ components: required: - href - rel - - type properties: href: type: string diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 015dbae3..43d2dc64 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -100,6 +100,10 @@ by *STAC API - Core*, the These conformance classes also requires implementation of the link relations in the [STAC API - Core](../core) conformance class. +While the STAC definition does not require the existence of the `type` field in +all Link objects, this is required by OAFeat and is thereby required by the +*STAC API - Features* conformance class. + ### Landing Page (/) The following Link relations must exist in the Landing Page (root). From 1bf1acd27cded511ed62ec7c7849d120455050f4 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 27 Feb 2023 20:00:06 -0500 Subject: [PATCH 13/14] add language that explicitly requires Link type for all conformance classes --- core/README.md | 4 ++++ item-search/README.md | 4 ++++ ogcapi-features/README.md | 6 +++--- 3 files changed, 11 insertions(+), 3 deletions(-) diff --git a/core/README.md b/core/README.md index 4bf9f29d..b329cc50 100644 --- a/core/README.md +++ b/core/README.md @@ -97,6 +97,10 @@ Recommendations for supporting browse is discussed in [Structuring Catalog Hiera ## Link Relations +While the STAC definition of Link does not require the `type` field, +*STAC API - Core* requires all Links to have this field. +If the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`. + The following Link relations must exist in the Landing Page (root). | **rel** | **href** | **Media Type** | **From** | **Description** | diff --git a/item-search/README.md b/item-search/README.md index ef62f4c0..05635f42 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -49,6 +49,10 @@ Implementing `GET /search` is **required**, `POST /search` is optional, but reco ## Link Relations +While the STAC definition of Link does not require the `type` field, +*STAC API - Item Search* requires all Links to have this field. +If the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`. + This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class. The following Link relations must exist in the Landing Page (root). diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 43d2dc64..2dba03cd 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -100,9 +100,9 @@ by *STAC API - Core*, the These conformance classes also requires implementation of the link relations in the [STAC API - Core](../core) conformance class. -While the STAC definition does not require the existence of the `type` field in -all Link objects, this is required by OAFeat and is thereby required by the -*STAC API - Features* conformance class. +While the STAC definition of Link does not require the `type` field, this is required by OAFeat, +and is thereby required by the *STAC API - Features* conformance class. +If the target of a Link's `type` is unknown, `type` SHOULD be set to `application/octet-stream` or `text/plain`. ### Landing Page (/) From 8e07e4233b7eb11c588ac360655388127d82f376 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 6 Mar 2023 09:22:36 -0500 Subject: [PATCH 14/14] Update fragments/itemcollection/openapi.yaml Co-authored-by: Tim Schaub --- fragments/itemcollection/openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fragments/itemcollection/openapi.yaml b/fragments/itemcollection/openapi.yaml index f6d156b8..2b845861 100644 --- a/fragments/itemcollection/openapi.yaml +++ b/fragments/itemcollection/openapi.yaml @@ -31,7 +31,7 @@ components: $ref: '../../core/commons.yaml#/components/schemas/link' example: - rel: next - type: application/json + type: application/geo+json href: >- http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk numberMatched: