Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Link "type" field required for all link relations, clarify media types in examples #368

Merged
merged 17 commits into from
Mar 13, 2023
Merged

Link "type" field required for all link relations, clarify media types in examples #368

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
d18bf72
clarify media types in examples
philvarner Jan 13, 2023
ee44483
re-add header
philvarner Jan 13, 2023
310c8f9
more media type polish
philvarner Jan 13, 2023
c8a3caa
polish tables
philvarner Jan 13, 2023
01b03c4
polish tables
philvarner Jan 13, 2023
60be748
polish tables
philvarner Jan 13, 2023
95acf07
make Link object field 'type' required
philvarner Jan 16, 2023
4e5154f
make Link object field 'type' required
philvarner Jan 16, 2023
41ea349
Merge branch 'main' into pv/clarify-media-types-2
philvarner Jan 30, 2023
24ed8c9
fix header
philvarner Jan 31, 2023
b1e9912
Merge branch 'main' into pv/clarify-media-types-2
philvarner Feb 2, 2023
18dd96c
linting
philvarner Feb 2, 2023
6a92787
remove merge conflict detritus
Feb 2, 2023
d726941
unrequire type field
philvarner Feb 14, 2023
9db90fc
Merge branch 'main' into pv/clarify-media-types-2
philvarner Feb 14, 2023
1bf1acd
add language that explicitly requires Link type for all conformance c…
philvarner Feb 28, 2023
8e07e42
Update fragments/itemcollection/openapi.yaml
Mar 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 27 additions & 15 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/),
Expand All @@ -12,9 +13,10 @@ 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.

## [1.0.0-rc.2] - 2022-11-01
## [v1.0.0-rc.2] - 2022-11-01

### Added

Expand All @@ -24,18 +26,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

Expand All @@ -46,7 +48,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.
Expand All @@ -59,7 +61,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.
Expand Down Expand Up @@ -165,53 +167,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.
Expand All @@ -229,6 +240,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

Expand Down
50 changes: 25 additions & 25 deletions core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,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.
Expand Down Expand Up @@ -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** | **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),
Expand All @@ -112,20 +112,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 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
Expand All @@ -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 | 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),
Expand All @@ -167,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
{
Expand Down Expand Up @@ -288,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
Expand Down
10 changes: 10 additions & 0 deletions core/commons.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: |-
Expand Down Expand Up @@ -385,6 +388,7 @@ components:
required:
- href
- rel
- type
properties:
href:
type: string
Expand Down Expand Up @@ -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.
Expand Down
Loading