Link "type" field required for all link relations, clarify media type…

…s in examples (#368) * clarify media types in examples * make Link object field 'type' required * add language that explicitly requires Link type for all conformance classes
radiantearth · Mar 13, 2023 · 194e525 · 194e525
1 parent f7c2fb1
commit 194e525
Show file tree

Hide file tree

Showing 8 changed files with 149 additions and 97 deletions.
diff --git 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/),
@@ -17,7 +18,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
 
@@ -27,18 +28,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
 
@@ -49,7 +50,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.
@@ -62,7 +63,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.
@@ -168,53 +169,62 @@ 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 (<https://github.com/radiantearth/stac-api-spec/pull/157>)
 - 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
+  (<https://api.stacspec.org/v1.0.0-beta.3/item-search#filter:queryable-first-operand>) to
   "Queryable Second Operand"
-  (https://api.stacspec.org/v1.0.0-beta.3/item-search#filter: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
 
 ## [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.
@@ -232,6 +242,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/README.md b/core/README.md
@@ -97,13 +97,17 @@ 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** | **From**        | **Description**                                      |
-| -------------- | -------- | --------------- | ---------------------------------------------------- |
-| `root`         | `/`      | STAC API - 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 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 |
 
 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),
@@ -115,20 +119,20 @@ 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.
 
 If all Items in a Catalog can be accessed by traversing these links, the Browseable conformance class
 <https://api.stacspec.org/v1.0.0-rc.2/browseable> should be advertised.
 
-| **rel** | **href** | **From**        | **Description**                        |
-| ------- | -------- | --------------- | -------------------------------------- |
-| `child` | various  | STAC API - Core | The child STAC Catalogs & Collections. |
-| `item`  | various  | STAC API - Core | The child STAC Items.                  |
+| **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.                  |
 
 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 to sub-catalogs and collections before
@@ -152,10 +156,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),
@@ -170,9 +174,9 @@ 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
 

diff --git a/core/commons.yaml b/core/commons.yaml
@@ -245,11 +245,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: |-
@@ -650,19 +653,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.

diff --git 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,28 +56,33 @@
                     }
                 ]
             },
-            "collection": "CS3",
+            "collection": "cs3",
             "links": [
                 {
                     "rel": "self",
-                    "href": "https://stac-api.example.com/collections/CS3/items/CS3-20160503_132131_05"
+                    "type": "application/json",
+                    "href": "https://stac-api.example.com/collections/cs3/items/CS3-20160503_132131_05"
                 },
                 {
                     "rel": "root",
+                    "type": "application/json",
                     "href": "https://stac-api.example.com/"
                 },
                 {
                     "rel": "collection",
-                    "href": "https://stac-api.example.com/collections/CS3"
+                    "type": "application/json",
+                    "href": "https://stac-api.example.com/collections/cs3"
                 }
             ],
             "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"

diff --git 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/geo+json
               href: >-
                 http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk
         numberMatched: