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

Jump to bottom

incorporate feedback on collections from beta.3, cleanup related text #210

Merged
merged 6 commits into from
Oct 5, 2021
Merged

incorporate feedback on collections from beta.3, cleanup related text #210

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
590bf74
incorporate feedback on collections from beta.3, cleanup related text…
philvarner Sep 9, 2021
c818455
add changelog entries
philvarner Sep 9, 2021
e52bf39
Update CHANGELOG.md
philvarner Oct 5, 2021
0078ef5
clarify recommended /api path name
philvarner Oct 5, 2021
0ca27fd
clarify canonical, clean up recommended api url
philvarner Oct 5, 2021
a5b5852
update Collection canonical definition
philvarner Oct 5, 2021
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
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

- Support binding Sort, Fields, and Context Extensions to STAC Features items resource
endpoint (`/collections/{collection_id}/items`)
- In Collections, added `canonical` rel type, added `/` and `/api` to list of endpoints
- In Item Search, added endpoint table

### Changed

Expand Down
176 changes: 87 additions & 89 deletions collections/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
# STAC API - Collections

- [STAC API - Collections](#stac-api---collections)
- [Link Relations](#link-relations)
- [Endpoints](#endpoints)
- [Example](#example)
- [Conformance](#conformance)
- [Endpoints](#endpoints)
- [Example](#example)

- **OpenAPI specification:** Missing
- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.4/collections))
- **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.4/extensions/collections>
- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
- **Dependencies**: [STAC API - Core](../core)
Expand All @@ -21,126 +19,126 @@ Data](http://docs.opengeospatial.org/DRAFTS/20-024.html) as the [Collections req
class](http://docs.opengeospatial.org/DRAFTS/20-024.html#rc_collections-section). Once the Common version is released we will
aim to align with it. But it still seems to be in flux.*

## Link Relations

The following Link relations shall exist in the Landing Page (root).

| **rel** | **href** | **From** | **Description** |
| -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `root` | `/` | STAC Core | The root URI |
| `self` | `/` | OAFeat | Self reference, same as root URI |
| `service-desc` | `/api` (recommended) | OAFeat OpenAPI | The OpenAPI service description. Uses the `application/vnd.oai.openapi+json;version=3.0` media type to refer to the OpenAPI 3.0 document that defines the service's API |
| `service-desc` | `/api` | OAFeat OpenAPI | The OpenAPI service description. Uses the `application/vnd.oai.openapi+json;version=3.0` media type to refer to the OpenAPI 3.0 document that defines the service's API. The path for this endpoint is only recommended to be `/api`, but may be another path. |
| `data` | `/collections` | OAFeat | List of Collections |
A `service-doc` endpoint is recommended, but not required.
| **rel** | **href** | **From** | **Description** |


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

Additionally, these relations may exist:

Additionally, `child` relations may exist to individual catalogs and collections.
| **rel** | **href** | **From** | **Description** |
| -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `child` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects |

| `child` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects |
`child` relations are useful for supporting browsing a STAC API as if it were a static catalog.

The following Link relations should exist in the `/collections` endpoint response.
The following Link relations shall exist in the `/collections` endpoint response.

| **rel** | **href** | **From** | **Description** |
| ------- | -------------- | --------- | --------------- |
| `root` | `/` | STAC Core | The root URI |
| `self` | `/collections` | OAFeat | Self reference |

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

| **rel** | **href** | **From** | **Description** |
| -------- | ----------------------------------- | --------- | ------------------------------------------ |
| `root` | `/` | STAC Core | The root URI |
| `parent` | `/` | OAFeat | Parent reference, usually the root Catalog |
| `self` | `/collections/{collectionId}` | OAFeat | Self reference |
| `items` | `/collections/{collectionId}/items` | OAFeat | Items within Collection |

Additionally, these relations may exist for the `/collections/{collectionId}` endpoint:

| **rel** | **href** | **From** | **Description** |
| -------- | ----------------------------------- | --------- | ------------------------------------------ |
| `canonical` | various | STAC Core | Provides the preferred paths to get to STAC Collection and Item objects, if they differ from the URL that was used to retrieve the STAC object and thus duplicate other content. This can be useful in federated catalogs that present metadata that has a different location than the source metadata. |

Usually, the `self` link in a Collection must link to the same URL that was used to request
it. However, implementations may choose to have the canonical location of the Collection be
elsewhere. If this is done, it is recommended to include a `rel` of `canonical` to that location.

## Endpoints

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

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

## Example

Below is a minimal example, but captures the essence. Each collection object must be a valid STAC
[Collection](../stac-spec/collection-spec/README.md), and each must have a `self` link that communicates its canonical location. And then
the links section must include a `self` link, and it must also link to alternate representations (like html) of the collection.

```json
{
"collections": [
{
"stac_version": "1.0.0",
"stac_extensions": [ ],
"id": "cool-data",
"title": "Cool Data from X Satellite",
"description": "A lot of awesome words describing the data",
"type": "Collection",
"license": "CC-BY",
"extent": {
"spatial": {
"bbox": [[-135.17, 36.83, -51.24, 62.25]]
},
"temporal": {
"interval": [["2009-01-01T00:00:00Z",null]]
}
},
"links": [
{
"rel": "root",
"type": "application/json",
"href": "https://myservice.com"
},
{
"rel": "parent",
"type": "application/json",
"href": "https://myservice.com"
},
{
"rel": "self",
"type": "application/json",
"href": "https://myservice.com/collections/cool-data"
},
{
"rel": "items",
"type": "application/json",
"href": "https://myservice.com/collections/cool-data/items"
}
],
}
],
"links": [
{
"rel": "root",
"type": "application/json",
"href": "https://myservice.com"
},
{
"rel": "self",
"type": "application/json",
"href": "https://myservice.com/collections"
}
]
"collections": [
{
"stac_version": "1.0.0",
"stac_extensions": [ ],
"id": "cool-data",
"title": "Cool Data from X Satellite",
"description": "A lot of awesome words describing the data",
"type": "Collection",
"license": "CC-BY",
"extent": {
"spatial": {
"bbox": [[-135.17, 36.83, -51.24, 62.25]]
},
"temporal": {
"interval": [["2009-01-01T00:00:00Z",null]]
}
},
"links": [
{
"rel": "root",
"type": "application/json",
"href": "https://myservice.com"
},
{
"rel": "parent",
"type": "application/json",
"href": "https://myservice.com"
},
{
"rel": "self",
"type": "application/json",
"href": "https://myservice.com/collections/cool-data"
},
{
"rel": "items",
"type": "application/json",
"href": "https://myservice.com/collections/cool-data/items"
}
],
}
],
"links": [
{
"rel": "root",
"type": "application/json",
"href": "https://myservice.com"
},
{
"rel": "self",
"type": "application/json",
"href": "https://myservice.com/collections"
}
]
}
```

The above is a minimal example, but captures the essence. Each collection object must be a valid STAC
[Collection](../stac-spec/collection-spec/README.md), and each should have a `self` link that communicates its canonical location. And then
the links section must include a `self` link, and it should also link to alternate representations (like html) of the collection.

Each collection must also be accessible from `/collections/{collectionId}`. Usually this will be the location provided by the `self` link,
but implementations may choose to list the canonical location elsewhere. But `/collections/{collectionId}` must always contain the response,
and if the canonical location is elsewhere it is recommended to include a `rel` of `canonical` from `/collections/{collectionId}` to that location.

## Conformance

Any implementation that provides the STAC Collection functionality described above must add `http://stacspec.org/spec/api/1.0.0-beta.4/collections`,
the conformance URI, to the `conformsTo` JSON at the landing page.

The core STAC landing page (`/`) must also include a link with a `rel` of `data` that links to the `/collections` endpoint.

**NOTE**: *When this aligns with OGC API - Common it will also need to add it to the `/conformance` endpoint.*
9 changes: 5 additions & 4 deletions core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
- [Example Landing Page for STAC API - Core](#example-landing-page-for-stac-api---core)
- [Extensions](#extensions)

- **OpenAPI specification:** [openapi.yaml](openapi.yaml) describes the core endpoints ([rendered version](https://api.stacspec.org/v1.0.0-beta.4/core)),
- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.4/core)),
and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas.
- **Conformance URI:** <https://api.stacspec.org/v1.0.0-beta.4/core>
- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
Expand Down Expand Up @@ -54,19 +54,20 @@ The following Link relations shall exist in the Landing Page (root).
| -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `root` | `/` | STAC Core | The root URI |
| `self` | `/` | OAFeat | Self reference, same as root URI |
| `service-desc` | `/api` (recommended) | OAFeat OpenAPI | The OpenAPI service description. Uses the `application/vnd.oai.openapi+json;version=3.0` media type to refer to the OpenAPI 3.0 document that defines the service's API |
| `service-desc` | `/api` | OAFeat OpenAPI | The OpenAPI service description. Uses the `application/vnd.oai.openapi+json;version=3.0` media type to refer to the OpenAPI 3.0 document that defines the service's API. The path for this endpoint is only recommended to be `/api`, but may be another path. |

A `service-doc` endpoint is recommended, but not required.

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

Additionally, `child` relations may exist to individual catalogs and collections.

| **rel** | **href** | **From** | **Description** |
| -------------- | -------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `child` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects |


It is also valid to have `item` links from the landing page, but most STAC API services are used to
serve up a large number of features, so they typically
use several layers of intermediate `child` links before getting to Item objects. Note that the `items` (plural)
Expand Down
8 changes: 4 additions & 4 deletions fragments/fields/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,17 +38,17 @@ polygons can be very large when reprojected to EPSG:4326, as in the case of a hi
Implementations are also not required to implement semantics for nested values whereby one can include an object, but
exclude attributes of that object, e.g., include `properties` but exclude `properties.datetime`.

No error should be returned if a specified field has no value for it in the catalog. For example, if the attribute
No error must be returned if a specified field has no value for it in the catalog. For example, if the attribute
"properties.eo:cloud_cover" is specified but there is no cloud cover value for an Item or the API does not even
support the EO Extension, a successful HTTP response should be returned and the Item entities will not contain that
support the EO Extension, a successful HTTP response must be returned and the Item entities will not contain that
attribute.

If no `fields` are specified, the response is **must** be a valid [ItemCollection](../itemcollection/README.md). If a client excludes
attributes that are required in a STAC Item, the server may return an invalid STAC Item. For example, if `type`
and `geometry` are excluded, the entity will not even be a valid GeoJSON Feature, or if `bbox` is excluded then the entity
will not be a valid STAC Item.

Implementations may return attributes not specified, e.g., id, but should avoid anything other than a minimal entity
Implementations may return attributes not specified, e.g., id, but must avoid anything other than a minimal entity
representation.

## Include/Exclude Semantics
Expand All @@ -63,7 +63,7 @@ of default properties attributes should be kept to a minimum.
the `include` attributes (set difference operation). This will result in an entity that is not a valid Item if any
of the excluded attributes are in the default set of attributes.
4. If both `include` and `exclude` attributes are specified, semantics are that a field must be included and **not**
excluded. E.g., if `properties` is included and `properties.datetime` is excluded, then `datetime` should not appear
excluded. E.g., if `properties` is included and `properties.datetime` is excluded, then `datetime` must not appear
in the attributes of `properties`.

## Examples
Expand Down
4 changes: 2 additions & 2 deletions fragments/filter/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,7 @@ not compliant with this extension.
The Queryables mechanism allows a client to discover what variable terms are available for use when writing filter
expressions. These variables can be defined per-collection, and the intersection of these variables over all collections is what
is available for filtering when there are no collection restrictions. These queryables are the only variables that may be used
in filter expressions, and if any variable is used in expression that is not defined as a queryable and error should be
in filter expressions, and if any variable is used in expression that is not defined as a queryable and error must be
returned according to OAFeat Part 3. It is recognized that this is a severe restriction in STAC APIs that have highly variable
and dynamic content. It is possible that this will change in the OAFeat Part 3 spec, see
this [issue](https://github.com/opengeospatial/ogcapi-features/issues/582). For now, implementers may choose to allow
Expand Down Expand Up @@ -341,7 +341,7 @@ supported, the server must return a 400 error if `filter-lang=cql-text`.

## Interaction with Endpoints

In an implementation that supports several operator classes, the Landing Page (`/`) should return a document including
In an implementation that supports several operator classes, the Landing Page (`/`) must return a document including
at least these values:

```json
Expand Down
Loading