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

Reorg conformance uris, endpoints, links, and maturity classification #240

Merged
merged 9 commits into from
Jan 5, 2022
Merged

Reorg conformance uris, endpoints, links, and maturity classification #240

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
0f1ff40
Merge pull request #216 from radiantearth/dev
philvarner Oct 7, 2021
ab633b2
update maturity, reorganize top list, add note on endpoint and links
philvarner Dec 11, 2021
dfacb8e
reorder top entries
philvarner Dec 14, 2021
febbe86
move maturity classification
philvarner Dec 14, 2021
6824af7
reword query extension language
philvarner Dec 14, 2021
0e5500d
lint fix
philvarner Dec 14, 2021
dc27246
revert maturity classification updates
philvarner Dec 14, 2021
2f84e28
Merge branch 'master' into reorg-conformance-uris-endpoint-and-links
philvarner Dec 20, 2021
72f852c
reword principles reference to maturity classification
philvarner Dec 20, 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
4 changes: 2 additions & 2 deletions PRINCIPLES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,8 @@ for data in a different projection.

- **Working code required.** Proposed changes should be accompanied by working code
(ideally with a link to an online service running the code). A reference implementation should be available
online to power the interactive documentation. Fully accepted specifications should have at least 3 implementations
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what "fully accepted" means here, since 3 impls is what we call Candidate in the Maturity Classification model. Rewording to just not be inconsistent with the MC.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think this predates extensions, and I think fully accepted was meant to mean like 1.0.0? Change looks good.

that cover the entire specification. Extensions have their own [Extention Maturity](extensions.md#extension-maturity) model.
online to power the interactive documentation. Both core conformance classes and extensions follow the
[Maturity Classification](README.md#maturity-classification) model.

- **Design for scale.** The design should work great with more data than can be imagined right now.
Ideally implementations are built with large test data sets to validate that they will work.
Expand Down
29 changes: 26 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
- [STAC API](#stac-api)
- [About](#about)
- [Stability Note](#stability-note)
- [Maturity Classification](#maturity-classification)
- [Communication](#communication)
- [In this repository](#in-this-repository)
- [Contributing](#contributing)
Expand All @@ -16,7 +17,6 @@ The SpatioTemporal Asset Catalog (STAC) family of specifications aim to standard
A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and
time. The core STAC specifications live in the GitHub repository [radiantearth/stac-spec](https://github.com/radiantearth/stac-spec).


A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns a STAC [Catalog](stac-spec/catalog-spec/catalog-spec.md),
[Collection](stac-spec/collection-spec/collection-spec.md), [Item](stac-spec/item-spec/item-spec.md),
or a STAC API [ItemCollection](fragments/itemcollection/README.md), depending on the endpoint.
Expand All @@ -36,11 +36,34 @@ rendered online into HTML at <https://api.stacspec.org/v1.0.0-beta.5>, in additi
## Stability Note

This specification has evolved over the past couple years, and is used in production in a variety of deployments. It is
currently in a 'beta' state, with no major changes anticipated. For 1.0-beta we remain fully aligned with [OGC API -
currently in a 'beta' state, with no major changes anticipated. For 1.0.0-beta.5, we remain fully aligned with [OGC API -
Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) Version 1.0, and we are working to stay aligned
as the additional OGC API components mature. This may result in minor changes as things evolve. The STAC API
specification follows [Semantic Versioning](https://semver.org/), so once 1.0.0 is reached any breaking change
will require the spec to go to 2.0.0.
will require the spec to go to 2.0.0.

## Maturity Classification
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this was moved from Extensions, since it applies to both the regular conformance classes and extensions


Conformance classes and extensions are meant to evolve to maturity, and thus may be in different states
in terms of stability and number of implementations. All extensions must include a
maturity classification, so that STAC API spec users can easily get a sense of how much they can count
on the extension.

| Maturity Classification | Min Impl # | Description | Stability |
| ----------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Proposal | 0 | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. |
| Pilot | 1 | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback |
| Candidate | 3 | A number of implementers are using it and are standing behind it as a solid extension. Can generally count on an extension at this maturity level | Mostly stable, breaking changes require a new version and minor changes are unlikely. |
| Stable | 6 | Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly. | Completely stable, all changes require a new version number and review process. |
| Deprecated | N/A | A previous extension that has likely been superseded by a newer one or did not work out for some reason. | Will not be updated and may be removed in an upcoming major release. |

Maturity mostly comes through diverse implementations, so the minimum number of implementations
column is the main gating function for an extension to mature. But extension authors can also
choose to hold back the maturity advancement if they don't feel they are yet ready to commit to
the less breaking changes of the next level.

A 'mature' classification level will likely be added once there are extensions that have been
stable for over a year and are used in twenty or more implementations.

## Communication

Expand Down
47 changes: 16 additions & 31 deletions collections/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,10 @@
- [Example](#example)

- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.5/collections))
- **Conformance URI:** <https://api.stacspec.org/v1.0.0-beta.5/collections>
- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
- **Conformance URIs:**
- <https://api.stacspec.org/v1.0.0-beta.5/collections>
- <https://api.stacspec.org/v1.0.0-beta.5/core>
- **[Maturity Classification](../README.md#maturity-classification):** Pilot
- **Dependencies**: [STAC API - Core](../core)

A STAC API can return information about all STAC [Collections](../stac-spec/collection-spec/collection-spec.md) available using a link
Expand All @@ -24,37 +26,20 @@ 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` | OAFeat | The service description in a machine-readable format |
| `data` | `/collections` | OAFeat | List of Collections |

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),
`application/vnd.oai.openapi+json;version=3.0` (3.0 JSON), or `application/vnd.oai.openapi+json;version=3.1`
(3.1 JSON).
This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class.

A `service-doc` endpoint is recommended, but not required. This commonly returns an HTML
page, for example, in the form of [Redoc](https://github.com/Redocly/redoc) interactive API
documentation, 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`.
The following Link relations shall exist in the Landing Page (root).

| **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** | **From** | **Description** |
| ------- | -------------- | -------- | ------------------- |
| `data` | `/collections` | OAFeat | List of Collections |

Additionally, `child` relations may exist to individual catalogs and collections.
Additionally, `child` relations may exist to child 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` relations are useful for supporting browsing a STAC API as if it were a static catalog.

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

| **rel** | **href** | **From** | **Description** |
Expand Down Expand Up @@ -82,12 +67,12 @@ elsewhere. If this is done, it is recommended to include a `rel` of `canonical`

## Endpoints

| Endpoint | Returns | Description |
| ----------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| `/` | Catalog | Landing Page and root Catalog |
| `/api` | any | The 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 |
This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.

| Endpoint | Returns | Description |
| ----------------------------- | ---------- | -------------------------------------------------------------------- |
| `/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.
Expand Down
11 changes: 7 additions & 4 deletions core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,11 @@
- [Extensions](#extensions)

- **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.5/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.5/core>
- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
- **Conformance URIs:**
- <https://api.stacspec.org/v1.0.0-beta.5/core>
- **[Maturity Classification](../README.md#maturity-classification):** Pilot
- **Dependencies**: None
and [commons.yaml](commons.yaml) is the OpenAPI version of the core [STAC spec](../stac-spec) JSON Schemas.

The base of a STAC API is its landing page. This resource is the starting point to discover what behaviors
the API supports via the `conformsTo` values and link relations.
Expand Down Expand Up @@ -80,10 +81,12 @@ Additionally, `child` relations may exist to individual catalogs and collections
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)
link will be used by APIs implementing STAC API - Features to link from a Collection to the items in that collection.
link relation is used by APIs implementing `STAC API - Features` to link from a Collection to the items in that collection.

## Endpoints

This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.

These endpoints are required, with details provided in this [OpenAPI specification document](openapi.yaml).

| Endpoint | Returns | Description |
Expand Down
Loading