Skip to content

Commit

Permalink
Merge pull request #60 from radiantearth/add-conformance
Browse files Browse the repository at this point in the history 
Add conformance class information
  • Loading branch information
@cholmes
cholmes authored Dec 3, 2020
2 parents 6af6ec0 + f1c797b commit 211f372
Show file tree
Hide file tree
Showing 39 changed files with 2,224 additions and 6,184 deletions.
8 changes: 8 additions & 0 deletions .circleci/.spectral-fragments.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
extends: "spectral:oas"
rules:
openapi-tags: off
info-contact: off
oas3-api-servers: off
oas3-unused-components-schema: off
operation-operationId: off
oas3-parameter-description: true
4 changes: 2 additions & 2 deletions .circleci/.spectral.yml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
extends: "spectral:oas"
rules:
# Ported from Spectral 4.0
contact-properties: true
oas3-api-servers: off
oas3-schema: warn
tag-description: true
oas3-parameter-description: true
120 changes: 119 additions & 1 deletion CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# STAC API Development & Release Process

## Contributing

Anyone building software that catalogs imagery or other geospatial assets is welcome to collaborate.
Expand All @@ -9,4 +11,120 @@ proposed change would also update all of the examples, but for now that is not r
can validate and update all examples before a release. But it is recommended to update at least a
couple examples to reflect the change.

All pull requests require a review of two team members.
## Development Process

The SpatioTemporal Asset Catalog API specification is under active development.

The `master` branch aims to always be stable, meaning that all the pieces of the specification are consistent and well
explained, and all the examples are consistent with the specification. The `dev` branch is a place of active development,
where a new change in one part of the spec might not yet be fully updated everywhere else. The team uses the
[stac-api-spec issue tracker](https://github.com/radiantearth/stac-api-spec/issues) to identify and track all that will be done for
a release. Once all the major issues are resolved the core team makes sure everything is consistent across the spec and
examples.

Any changes to the spec must be made as pull requests to the `dev` branch. Anyone is welcome and encouraged to bring ideas
and improvements, to the issue tracker or (ideally) as pull requests. To merge a new pull request the work must be reviewed
by at least two members of the STAC spec core team (who have write access to the main repository). It also must pass the
Continuous Integration testing.

### Working with the OpenAPI files

The definitive specification for STAC API is provided as an [OpenAPI](http://openapis.org/) 3.0 specification that is
contained within several YAML files in the various directories.

TODO: Update with the latest folders / structure, and update the below instructions if they change

```bash
npm install
npm run generate-all
```

You can also dynamically serve a human-readable version of your edited files at `http://127.0.0.1:8080` using the following commands:
- Only the core STAC API:
```bash
npm install
npm run serve
```
- The STAC API including all extensions:
```bash
npm install
npm run serve-ext
```

Create your own OpenAPI document by combining the STAC definition with the extensions you want by creating a `myapi.merge.yaml` file.
This file should contain a line indicating the files that need to be merged:

```yaml
!!files_merge_append ["STAC.yaml", "extensions/query/query.fragment.yaml"]
```

Then, run the [yaml-files](https://www.npmjs.com/package/yaml-files) command line tool:

```bash
npm -g install
yaml-files myapi.merge.yaml myapi.yaml
```

The commands above require root/administrator level access to install the npm packages globally.
If you do not have the required permissions or do not want to install the packages globally for any other reason check the
npm documentation for your platform for instructions to install and run local packages. Unix bash users for instance may use:

```bash
npm install
$(npm bin)/yaml-files myapi.merge.yaml myapi.yaml
```

## Release Process

To release a new version of the STAC spec the following list of tasks must be done.

- **Update Issue Tracker**: Each release has a [milestone](https://github.com/radiantearth/stac-spec/milestones) in the github
issue tracker, and before a release is done all open issues that are filed against it should be reviewed. All issues do not
need to be completed, but the core release team should all review the issues to make sure that the critical ones for the
release have been addressed. Issues that aren't seen as essential should be moved to future releases, so that there are no
open issues against the milestone.
- **Check dependencies**: STAC relies on OGC API - Features and STAC Core specifications at its core, and will likely rely
on additional Features API extensions as well as OGC API - Commons. We aim to always reference the latest version of these,
so before releasing we should check to make sure we are on the latest stable versions, and upgrade if it makes sense. We include
the latest stable STAC core spec version as a 'submodule', so before release we should update that to be the latest.
- **Agreement from core team**: The core STAC API team should meet (on video or on gitter) and decided that the release is ready.
This should include review of the issues, as well as looking at the spec holistically, to make sure the new changes keep
with a coherent whole.
- **Final Spec Read Through**: There should be a final read through of the core specification to make sure it makes sense
and there are no typos, errors, etc.
- **Update the Changelog**: The [changelog](CHANGELOG.md) should be reviewed to make sure it includes all major improvements
in the release. And anything in 'unreleased' section should move to the version of the spec to be released.
- **Merge dev to master**: As there is no 'build' process, since the specification *is* the markdown files in the github
repository, the key step in a release is to merge the `dev` branch into `master`, as `master` is the current stable state
of the spec.
- **Check Online API Docs**: Check to make sure the online API docs reflect the release at <https://stacspec.org/STAC-api.html>
and <https://stacspec.org/STAC-ext-api.html> (this step may go away once we are confident this works well, as this publishing is in flux)
- **Release on Github**: The final step to create the release is to add a new 'release' on
<https://github.com/radiantearth/stac-spec/releases>. This should use a tag like the others, with a 'v' prefix and then the
release number, like v0.5.2. The changelog should be copied over to be the release notes, and then also include a link to
the full milestone of everything closed in the issue tracker.
- **Promote the release**: A blog post and tweet should be composed and sent out, and then inform those in the gitter channel
to post / promote it.

### Release Candidates

Before any release that has *major* changes (made as a judgement call by the core contributors) there should be a 'release
candidate' to ensure the wider community of implementors can try it out
and catch any errors *before* a full release. It is only through actual implementations that we can be sure the new spec
version is good, so this step is essential if there are major changes. The release should proceed as normal, but called
vX.Y.Z-RC.1. The core STAC community should be told and encouraged to update their implementations. At least 2 implementations
should be updated to the new specification before there is a real release. And ideally an API client is also
updated. This provides the core sanity check. If there are changes or fixes to the spec or
schemas needed from their feedback then make fixes and do RC2. If it is just fixes to the examples or tooling then no
additional RC is needed. After there is no more changes to spec or schemas then the release process should be done on master,
with no changes to the spec - just updating the version numbers.

## Governance

The goal of STAC is to have a Project Steering Committee of core contributors, representing diverse organizations and
implementations. To bootstrap Chris Holmes is the Benevolent Dictator for
Life or until a PSC is formed, so we don't get stuck waiting for votes when there is not enough activity.

The longer term goal is to contribute STAC spec to the Open Geospatial Consortium, and indeed to align as much as possible
with their next generation spec. The current plan is to contribute STAC API as an OGC 'community module' when we reach
1.0.0, and to work to have it become part of the OGC API baseline.
112 changes: 112 additions & 0 deletions OVERVIEW.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
## About

The STAC API defines a RESTful JSON-based server to browse and query [SpatioTemporal Asset Catalogs](stac-spec/)
(STAC). While the core STAC specification provides a structure and language to describe assets, users usually want to access
a subset of the entire catalog, such as for a certain date range, in a particular area of interest, or matching properties
they care about. STAC API extensions specifies those query parameters, and compliant servers return collections of STAC Items that
match the user's preferences. A lot of additional functionality can added through the [OGC API](https://ogcapi.ogc.org/) family of
standards, particularly [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) (OAFeat, for our
shorthand).
As STAC APIs follow a RESTful model, a core principal of this is the use of HTTP Request Methods ("verbs") and
the `Content-Type` header to drive behavior on resources ("nouns").

## Overview

The [core](core/) of STAC API simply returns a valid [STAC Catalog](stac-spec/catalog-spec/catalog-spec.md) and a description
of what parts of the fuller STAC API specification it conforms to. The `links` section of the Catalog is the jumping
off point for the more powerful capabilities - it contains a list of URL's, each described by particular link
'relationships' (`rel`) to indicate their functionality. Note that the [STAC Core specification](stac-spec) provides
most all the content of API responses - the STAC API is primarily concerned with the return of STAC
[Items](stac-spec/item-spec/README.md) and [Collections](stac-spec/collection-spec/README.md) through API functionality.

There are then three major sets of functionality that build on the core, which are designed to be complementary, letting
implementations choose which parts they want to utilize. Most every STAC API implements at least one, and many follow
two or all three.

### Item Search

The [item search](item-search) functionality is one of the most common, provided by the `search` rel often
located at a `/search` endpoint. It re-uses all of the OAFeat [query
parameters](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_) specified in their 'core', and adds a
couple more. It does not require a full implementation of OAFeat, it is instead a simplified construct that can run a
search across any set of indexed STAC [`Items`](stac-spec/item-spec/README.md).

### OGC API - Features

The final major functionality for a STAC API is to [provide individual `item` query endpoints](ogcapi-features/)
for each collection. Some STAC API implementations only describe their Collections, without providing search of individual
Items, indeed they may not have Items. Many implementations go further than just providing the `search` rel by becoming fully compliant with
[OGC API - Features Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_core), implementing
following their [GeoJSON](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_geojson) and
[OpenAPI](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_openapi_3_0) options, as STAC
is always in GeoJSON and OpenAPI is used to specify STAC API. Full compliance involves splitting STAC `Items` into
individual `/collections/{collectionId}/items` endpoints that expose querying single collections, as OAFeat does
not currently allow cross-collection search. And it adds a few other requirements, which are highlighted in the
[features description](ogcapi-features/), in order to help STAC implementors understand OAFeat without having to
read the full spec from scratch.

### Extensions

Both STAC API and OAFeat allow 'extensions' that can be added for additional functionality.
We are working to fully merge the extensions, so that every STAC extension is specified at the OGC API level, and
STAC API just presents a curated set of extension options.

## Capabilities List

The following table describes the service resources available in a full STAC API implementation. Note that the 'Endpoint'
column is more of an example in most cases. OGC API makes some endpoint locations required, those will be bolded below.

| Endpoint | Link Relationship | Returns | Description |
| ----------------------------------------------- | ------------------ | ------------------------------------------------- | ----------- |
| `/` | root | [Catalog](stac-spec/catalog-spec/catalog-spec.md) | Extends `/` from OAFeat to return a full STAC catalog. |
| `/search` | search | ItemCollection | Retrieves a group of Items matching the provided search predicates, probably containing search metadata from the `search` extension |
| **`/collections`** | data | JSON | Object with a list of Collections contained in the catalog and links |
| **`/conformance`** | conformance | JSON | Info about standards to which the API conforms |
| `/api` | service-desc | OpenAPI 3.0 JSON | The OpenAPI definition of the endpoints in this service |
| **`/collections/{collectionId}`** | collection | Collection | Returns single Collection JSON |
| **`/collections/{collectionId}/items`** | items | ItemCollection | GeoJSON FeatureCollection-conformant entity of Items in collection |
| **`/collections/{collectionId}/items/{featureId}`** | Item | Returns single Item (GeoJSON Feature) |

## Conformance Classes

STAC API is evolving to utilize OAFeat's
'[Conformance](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_declaration_of_conformance_classes)' JSON structure. For
STAC API 1.0.0-beta.1 we declare new STAC Conformance classes, and specify which OAFeat ones to use. These are detailed in the relevant
sections below.The core STAC conformance classes communicate the conformance JSON only in the root (`/`) document, while OGC API
requires they also live at the `/conformance` endpoint.

**NOTE:** *By 1.0.0 we aim to have requirements classes specified in detail, as testable assertions,
like OGC does, but for now the core reference is just this spec document and the OpenAPI yaml. We also desire to have the
URI's for conformance to actually resolve to machine-readable information clients can use.*

## STAC Core and OGC Versions

This version of STAC API depends on OGC API - Features - Part 1: Core [Version 1.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html),
and on [OGC API - Commons - Part 2: Collections](https://github.com/opengeospatial/ogcapi-common/blob/cc8ca2f011d7e1b19721268c4bf2b97c163d160a/20-024.pdf)
from the [August 18 V2 Commit](https://github.com/opengeospatial/ogcapi-common/tree/cc8ca2f011d7e1b19721268c4bf2b97c163d160a/collections)
(we hope they will publish at least a 'beta' version that we can point to soon).

This version of STAC API is intended to work with any STAC core specification version 0.9.x or 1.x.x (included betas), but is not
designed to work with STAC 2.0 and above (since we use [SemVer](https://semver.org/) it may introduce backwards incompatible changes).
The STAC API spec is released with the latest stable STAC core specification version included in the [`/stac-spec`](stac-spec/)
directory as a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). To determine which version it is just check the
[`/stac-spec/CHANGELOG.md`](stac-spec/CHANGELOG.md) for the topmost version & release date.

## STAC API

The STAC API is broken up into a number of discrete parts, specified by 'Conformance Classes'. The only one required to be considered
a valid STAC API is 'STAC API Core', but the majority of implementations will implement at least 'STAC Search' or 'Commons Collections'.
A majority of the conformance classes are defined by OGC (Commons and OAFeat), and the number will likely increase as OGC capabilities
expand and STAC works to align.

| **Name** | **API** | **Conformance URI** | **Description** |
|---------------------------|--------|----------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| STAC API Core | STAC | <http://stacspec.org/spec/api/1.0.0-beta.1/core> | Specifies the STAC Landing page `/`, communicating conformance and available endpoints. |
| STAC Search | STAC | <http://stacspec.org/spec/api/1.0.0-beta.1/req/stac-search> | Enables search of all STAC Items on the server, with the STAC `[/search](#stac-api-endpoints)` endpoint. |
| OACommon Collections | OACommon | <http://www.opengis.net/spec/ogcapi_common-2/1.0/req/collections> | Provides listing of OGC API Collections ([reference](http://docs.opengeospatial.org/DRAFTS/20-024.html#rc_collections-section)) |
| STAC Response | STAC | <http://stacspec.org/spec/api/1.0.0-beta.1/req/stac-response> | Specifies that OAFeat's relevant responses conform to STAC: STAC Collections for OGC API Commons - [collections](http://docs.opengeospatial.org/DRAFTS/20-024.html#rc_collections-section) & STAC Items for OGC API's [Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_) Collections from the OAFeat `/collections` and `/collections/{collectionId}` endpoints. |
| OAFeat Core | OAFeat | <http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core> | The core OGC API - Features endpoints & parameters Returns one or more STAC Collections from the OAFeat `/collections` and `/collections/{collectionId}` endpoints. Depends on OAFeat Core. ([reference](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_core)) |
| OpenAPI specification 3.0 | OAFeat | <http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30> | Describes the API as OpenAPI 3.0 ([reference](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_oas30)) |
| GeoJSON | OAFeat | <http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson> | Requires OGC API - Features responses to be in GeoJSON ([reference](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_geojson)) | |

Additional conformance classes are specified in the [STAC Extensions](extensions.md).
Loading

0 comments on commit 211f372

Please sign in to comment.