diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7831ecf2..d4e34f8a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -11,4 +11,3 @@ - [ ] This PR is made against the dev branch (all proposed changes except releases should be against dev, not master). - [ ] This PR has **no** breaking changes. - [ ] I have added my changes to the [CHANGELOG](https://github.com/radiantearth/stac-api-spec/blob/dev/CHANGELOG.md) **or** a CHANGELOG entry is not required. -- [ ] OpenAPI files only: I have run `npm run generate-all` to update the [generated OpenAPI files](https://github.com/radiantearth/stac-api-spec/blob/dev/README.md#openapi-definitions). diff --git a/CHANGELOG.md b/CHANGELOG.md index bd14c539..5119eaf0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,8 +8,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### 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. + - STAC API - Features is the OGC API - Features standards to be used in a STAC API. + - Extensions are specified in the relevant functionality directory, though they can share openapi yaml's in the 'fragments' directory. - Updated to STAC specification version 1.0.0-beta.2 - Named explicit supported STAC core versions to be from 0.9.0 up to (and not including) 2.0.0 - Context Extension OpenAPI spec was updated to remove the no longer used `next` attribute diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8f5f2e74..fa6dd985 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,57 +22,61 @@ where a new change in one part of the spec might not yet be fully updated everyw 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. +### Submitting Pull Requests -### Working with the OpenAPI files +Any proposed changes to the specification should be done as pull requests. Please make these +requests against the [`dev`](https://github.com/radiantearth/stac-api-spec/tree/dev) branch (this will +require you to switch from the default of 'master', which we keep so it displays first). -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. +Creating a Pull Request will show our PR template, which includes checkbox reminders for a number +of things. -TODO: Update with the latest folders / structure, and update the below instructions if they change +- Adding an entry the [CHANGELOG](CHANGELOG.md). If the change is more editorial and minor then this +is not required, but any change to the actual specification should definitely have one. +- Base the PR against dev, as mentioned above - even if the branch was made off of dev this reminds +you to change the base in GitHub's PR creation page. +- Highlight if the PR makes breaking changes to the specification (in beta there can still be +select breaking changes, but after 1.0 this will change) -```bash -npm install -npm run generate-all -``` +All pull requests should submit clean markdown, which is checked by the continuous integration +system. Please use `npm run check-markdown` locally, as described in the [next section](#using-check-markdown-locally), +to ensure that the checks on the pull request succeed. If it does not then you can look at the +mistakes online, which are the same as running `check-markdown` locally would surface. -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"] -``` +All pull requests that modify or create JSON examples should use [JSON +formatter](https://jsonformatter.org/) to keep files consistent across the repo. -Then, run the [yaml-files](https://www.npmjs.com/package/yaml-files) command line tool: +All pull requests additionally require a review of two STAC core team members. Releases are cut +from dev to master (and require 3 approvals). -```bash -npm -g install -yaml-files myapi.merge.yaml myapi.yaml -``` +### Using check-markdown locally + +The same check-markdown program that runs as a check on PR's is part of the repo and can be run locally. +To install you'll need npm, which is a standard part of any [node.js installation](https://nodejs.org/en/download/). +Alternatively, you can also use [yarn](https://yarnpkg.com/) instead of npm. In this case replace all occurrences of +`npm` with `yarn` below. -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: +First you'll need to install everything with npm once. Just navigate to the root of the stac-spec repo and on +your command line run: ```bash npm install -$(npm bin)/yaml-files myapi.merge.yaml myapi.yaml ``` +Then to do the check on your markdown you run: + +```bash +npm run check-markdown +``` + +This will spit out the same text that you see online, and you can then go and fix your markdown. + +### 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. These live in the same place as the markdown defining +various parts of the specification. Currently we expect developers to be up to speed with +OpenAPI and using their own tools to modify things. In the future we will provide tools to make it easier to work with. +We do publish full OpenAPI files online, at TODO: Matt to add final location. ## Release Process diff --git a/README.md b/README.md index 3899271d..2b5dd0ea 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ time. The core STAC specification lives at [gitub.com/radiantearth/stac-spec](ht 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 ItemCollection, depending on the endpoint. +or a STAC API [ItemCollection](core/itemcollection.md), depending on the endpoint. Catalogs and Collections are JSON, while Items and ItemCollections are GeoJSON-compliant entities with foreign members. Typically, a Feature is used when returning a single Item, and FeatureCollection when multiple Items (rather than a JSON array of Item entities). @@ -25,10 +25,8 @@ The specification for STAC API is provided as an [OpenAPI](http://openapis.org/) 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 - -Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) Version 1.0. We have further aligned STAC extensions -with OGC API - Features extensions, particularly [CQL](https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/cql/) -and [Transactions](https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/transactions). These are not -yet entirely stable, so if they change then STAC will update to remain in line. +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. ## Communication @@ -42,19 +40,29 @@ the specification takes place in the [issue tracker](https://github.com/radiante The **[Overview](overview.md)** document describes all the various parts of the STAC API and how they fit together. **STAC API - Core Specification:** -The main description of the core STAC API specification is in the *[core](core/)* folder and -allows browsing catalogs and retrieving the API capabilities. -An implementation will most always add extensions for broader functionality than just browsing catalogs. +The *[core](core/)* folder describes the core STAC API specification that enables browsing catalogs and +retrieving the API capabilities. This includes the OpenAPI schemas for STAC items, catalogs and collections. + +**STAC API - Item Search Specification:** +The *[item-search](item-search)* folder contains the Item Search specification, which enables +cross-collection search of STAC Items at a `search` endpoint, as well as a number of extensions. + +**STAC API - Features:** +The *[ogcapi-features](ogcapi-features)* folder describes how a STAC API can fully implement [OGC API - +Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) to expose individual `items` endpoints for search of +each STAC collection. It also includes extensions that can be used to further enhance OAFeat. **Extensions:** -The [extensions/](extensions.md) document links to additional capabilities that can be added to enrich the functionality of STAC API - Core. -OpenAPI YAML documents are provided for each extension with additional documentation and examples provided in a README. +The *[extensions](extensions.md) document* describes how STAC incubates new functionality, and it links to the existing + +extensions that can be added to enrich the functionality of a STAC API. Each has an OpenAPI yaml, but some of the yaml +documents live as fragments in the [fragments/](fragments/) folder. **Fragments:** -The [fragments/](fragments/) folder contains re-usable building blocks to be used in STAC API - Core and STAC API extensions. -This includes the OpenAPI schemas for items, catalogs and collections, but also common schemas and parameters for behavior like -sorting and querying. Most all of them are compatible with OGC API - Features, and the plan is to fully align the relevant -functionality and have it be useful for all OAFeat implementations. +The *[fragments/](fragments/)* folder contains re-usable building blocks to be used in a STAC API, including common OpenAPI +schemas and parameters for behavior like sorting and filtering. Most all of them are compatible with +OGC API - Features, and the plan is to fully align the relevant functionality and have it be useful for all OAFeat implementations. +OpenAPI YAML documents are provided for each extension with additional documentation and examples provided in a README. **STAC Specification:** This repository includes a '[sub-module](https://git-scm.com/book/en/v2/Git-Tools-Submodules)', which is a copy of the [STAC specification](stac-spec/) tagged at the latest stable version. diff --git a/core/README.md b/core/README.md index bf49e176..30bd7c67 100644 --- a/core/README.md +++ b/core/README.md @@ -3,6 +3,8 @@ - **Conformance URI:** - **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot - **Dependencies**: None +- **OpenAPI Specifications**: [openapi.yaml](openapi.yaml) describes the core endpoints, and [commons.yaml](commons.yaml) is the OpenAPI + version of the core [STAC spec](../stac-spec) JSON Schemas. The core of a STAC API is its landing page, which is the starting point to discover STAC data and what the API supports. diff --git a/core/itemcollection-spec.md b/core/itemcollection.md similarity index 100% rename from core/itemcollection-spec.md rename to core/itemcollection.md diff --git a/extensions.md b/extensions.md index 46bd5df1..373fa12d 100644 --- a/extensions.md +++ b/extensions.md @@ -1,15 +1,17 @@ # API Extensions -This folder contains extensions to the SpatioTemporal Asset Catalog API specification by providing new OpenAPI fragments. +STAC aims to define a small core of functionality, with richer capabilities enabled by extensions. This document +lists the existing extensions, and explains the process of creating and maturing an extension. -Anyone is welcome to create an extension (see section 'Extending STAC'), and is encouraged to at least link to the extension from here. +Anyone is welcome to create an extension (see [info on this](#creating-new-extensions) below), and is encouraged to at least +link to the extension from here. The third-party / vendor extension section is for the sharing of extensions. As third parties create useful extensions for their implementation it is expected that others will make use of it, and then evolve to make it a 'community extension', that several providers maintain together. -For now anyone from the community is welcome to use this extensions/ folder of the stac-spec repository to collaborate. +For now anyone from the community is welcome to use the appropriate parts of the stac-api-spec repository to collaborate. ## Extension Maturity -Extensions in this directory are meant to evolve to maturity, and thus may be in different states +Extensions are meant to evolve to maturity, and thus may be in different states in terms of stability and number of implementations. All extensions included must include a maturity classification, so that STAC spec users can easily get a sense of how much they can count on the extension. @@ -30,19 +32,46 @@ 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. +## Extensions, Fragments and Conformance + +Each extension has its own conformance class, which is specified with a 'conformance URI' that is defined for the extension, and listed in +the table below. These must be listed in the `conformsTo` JSON of the landing page, as specified by [STAC API Core](core/), to let clients +know that they can utilize the functionality. + +Each extension is defined to work against only one of the main API spec's conformance classes. A number of extensions define functionality +that could be used easily in a number of endpoints, such as additional parameters for search. For this repository we put those in the +[fragments](fragments/) directory. The main definition of the functionality lives there, but a fragment does not define a conformance class. +Only extensions have conformance classes, as they define the functionality along with the scope - where it is used. + +**NOTE**: *Currently the fragments are only used in item-search, but in the next release we will define extensions for all the fragments that +are scoped against ogcapi-features*. + ## List of community extensions -| Extension Name | Scope* | Conformance URI | Description | Maturity | -|--------------------------------------------------------|----------------|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|------------| -| [Fields](fragments/fields/README.md) | *None* | | Adds parameter to control which fields are returned in the response. | *Pilot* | -| [Query](fragments/query/README.md) | *None* | | Adds parameter to search Item and Collection properties. | *Pilot* | -| [Context](fragments/context/README.md) | [ItemCollection](core/itemcollection-spec.md) | | Adds search related metadata (context) to ItemCollection. | *Proposal* | -| [Sort](fragments/sort/README.md) | *None* | | Adds Parameter to control sorting of returns results. | *Pilot* | -| [Transaction](ogcapi-features/extensions/transaction/README.md) | *None* | | Adds PUT and DELETE endpoints for the creation, editing, and deleting of items and Collections. | *Pilot* | -| [Items and Collections API Version](ogcapi-features/extensions/version/README.md) | *None* | | Adds GET versions resource to collections and items endpoints and provides semantics for a versioning scheme for collections and items. | *Proposal* | +This is the list of all extensions that are contained in the stac-api-spec repository. + +| Extension Name | Scope* | Description | Maturity | +|-----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|------------| +| [Fields](item-search/README.md#fields) | [Item Search](item-search/) request | Adds parameter to control which fields are returned in the response. | *Pilot* | +| [Query](item-search/README.md#query) | [Item Search](item-search/) request | Adds parameter to search Item and Collection properties. | *Pilot* | +| [Context](item-search/README.md#context) | [Item Search](item-search/) response ([ItemCollection](core/itemcollection.md)) | Adds search related metadata (context) to ItemCollection. | *Proposal* | +| [Sort](item-search/README.md#sort) | [Item Search](item-search/) request | Adds Parameter to control sorting of returns results. | *Pilot* | +| [Transaction](ogcapi-features/extensions/transaction/README.md) | [STAC - Features API](ogcapi-features) POST on `/items` endpoint, DELETE/PUT on `/items/{itemId}` endpoint | Adds PUT and DELETE endpoints for the creation, editing, and deleting of items and Collections. | *Pilot* | +| [Items and Collections API Version](ogcapi-features/extensions/version/README.md) | [STAC - Features API](ogcapi-features) on `/items` endpoint | Adds GET versions resource to collections and items endpoints and provides semantics for a versioning scheme for collections and items. | *Proposal* | + +### Conformance classes of extensions -\* The scope refers to the STAC specifications an extension extends. As all extensions here are API extensions, -the API is not mentioned explicitly as scope and only the core STAC specifications (Catalog, Collection, Item and ItemCollection) are listed. +Each extension has its own conformance URI, which is used in the `conformsTo` response of the landing page to let clients know what capabilities +the service supports. This are listed at the top of each extension description, but the full table is given here for ease of reference. + +| Extension Name | Conformance URI | +|-----------------------------------------------------------------------------------|----------------------------------------------------------------------------| +| [Fields](item-search/README.md#fields) | | +| [Query](item-search/README.md#query) | | +| [Context](item-search/README.md#context) | | +| [Sort](item-search/README.md#sort) | | +| [Transaction](ogcapi-features/extensions/transaction/README.md) | | +| [Items and Collections API Version](ogcapi-features/extensions/version/README.md) | | ## Third-party / vendor extensions @@ -56,106 +85,14 @@ Please contact a STAC maintainer or open a Pull Request to add your extension to | -------- | ----- | ----------- | ------ | | None yet | | | | -## Proposed extensions - -The following extensions are proposed through the -[STAC issue tracker](https://github.com/radiantearth/stac-api-spec/issues) and are considered to be -implemented. If you would find any of these helpful or are considering to implement a similar -extension, please get in touch through the referenced issues: - -- None yet - ## Creating new extensions -Creating new extensions requires creating an OpenAPI fragment to define it. - -Example fragment: - -```yaml -IntersectsFilter: - type: object - description: >- - Only returns items that intersect with the provided polygon. - properties: - intersects: - $ref: "#/definitions/Polygon" -Polygon: - type: object - properties: - type: - type: string - enum: - - polygon - coordinates: - $ref: "#/definitions/Polygon2D" - required: - - type - - coordinates -Polygon2D: - type: array - minItems: 1 - items: - $ref: "#/definitions/LinearRing2D" -LinearRing2D: - type: array - minItems: 4 - items: - $ref: "#/definitions/Point2D" - example: [[-104, 35], [-103, 35], [-103, 34], [-104, 34], [-104, 35]] -Point2D: - description: A 2d geojson point - type: array - minimum: 2 - maximum: 2 - items: - type: number - format: double - example: - - -104 - - 35 -``` - -It is likely that there are schemas that should be used in common for types of filters that target different fields. -We should define a common set of filter types that can be used in defining filters for different fields. - -- `NumberRange` -- `TimeRange` -- `Text` -- `ArrayIncludes` -- Etc. - -When defining a new filter fragment, you would reference these common filter types: - -```yaml -CloudCover: - type: object - description: >- - Filter items by desired cloud coverage. - properties: - cloudcover: - $ref: "#/definitions/NumberRange" -``` - -Some additional extensions that have been discussed: - -CQL support for generic queries: - -```json -{ - "CQL": "CQL Select String" -} -``` - -### Adding filters to search - -Filters should be documented as properties in the `searchBody`: - -```yaml -searchBody: - description: The search criteria - type: object - allOf: - - $ref: "#/components/schema/bboxFilter" - - $ref: "#/components/schema/datetimeFilter" - - $ref: "#/components/schema/intersectsFilter" -``` +Creating new extensions requires creating an OpenAPI fragment to define it, along with a README markdown file that gives +an overview of the functionality. In the README a conformance URI should be provided, so clients can use it to tell if +a service has the indicated functionality. It is also recommended to note the 'extension maturity', as defined above, +so others can know how widely it is used. + +The new extension can live anywhere online, with a recommendation of using a GitHub repository to be able to track changes. +The first step in sharing the extension is to add it to the third-party / vendor extension table above. If it is of something +that the wider community may be interested in then it should be added to the appropriate folder in the main repo as a pull +request. diff --git a/fragments/context/README.md b/fragments/context/README.md index ddbb851a..64dacf89 100644 --- a/fragments/context/README.md +++ b/fragments/context/README.md @@ -5,10 +5,10 @@ - **Dependents:** - [Item Search](../../item-search) -This extension is intended to augment the core [ItemCollection](../../core/itemcollection-spec.md) +This extension is intended to augment the core [ItemCollection](../../core/itemcollection.md) object when the ItemCollection is the result of a search, for example, from calling the `/search` API endpoint. -**Note**: *This extension is currently only used by [STAC Item Search](../../item-search) functionality. +**Note**: *This fragment is currently scoped to just the STAC-specific functionality such as [STAC Item Search](../../item-search). OGC API has their own way returning `numberMatched` and `numberReturned` at the top level, instead of in a context object. We are hoping to [align](https://github.com/opengeospatial/ogcapi-common/issues/82), but until then it is recommended to use STAC Context in the cross-collection `search` endpoint, and follow the OGC API way when @@ -21,7 +21,7 @@ implementing OGC API - Features.* | Element | Type | Description | | --------- | --------------------------------- | ----------- | -| `context` | [Context Object](#context-object) | **REQUIRED.** The search-related metadata for the [ItemCollection](../../core/itemcollection-spec.md). | +| `context` | [Context Object](#context-object) | **REQUIRED.** The search-related metadata for the [ItemCollection](../../core/itemcollection.md). | ## Context Object diff --git a/fragments/fields/README.md b/fragments/fields/README.md index f9d6bfda..3b615d44 100644 --- a/fragments/fields/README.md +++ b/fragments/fields/README.md @@ -34,7 +34,7 @@ No error should be returned if a specified field has no value for it in the cata support the EO Extension, a successful HTTP response should be returned and the Item entities will not contain that attribute. -If no `fields` are specified, the response is **must** be a valid [ItemCollection](../../core/itemcollection-spec.md). If a client excludes +If no `fields` are specified, the response is **must** be a valid [ItemCollection](../../core/itemcollection.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. diff --git a/item-search/README.md b/item-search/README.md index 6eaa3e8a..741c0c5e 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -1,13 +1,12 @@ # STAC API - Item Search - **OpenAPI specification:** [openapi.yaml](openapi.yaml) -- **Conformance URI:** -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot +- **Conformance URI:** - **Dependencies**: [STAC API - Core](../core) - **Examples**: [examples.md](examples.md) A search endpoint, linked to from the STAC landing page, provides the ability to query STAC `Items` across collections. -It retrieves a group of Items that match the provided parameters, wrapped in an [ItemCollection](../core/itemcollection-spec.md) (which is a +It retrieves a group of Items that match the provided parameters, wrapped in an [ItemCollection](../core/itemcollection.md) (which is a valid [GeoJSON FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) that contains STAC Items). Several core query parameters are defined by [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html), with a few additions specified in this document. @@ -129,6 +128,8 @@ property can be specified. This indicates that the client should send the same p request, but with the specified headers/body values merged in. This allows servers to indicate what needs to change to get to the next page without mirroring the entire query structure back to the client. +See the [paging examples](examples.md#paging-examples) for additional insight. + ## HTTP Request Methods and Content Types The STAC API follow a RESTful model. A core principal of this is the use of HTTP Request Methods ("verbs") and @@ -206,7 +207,7 @@ of this extension can be found in the [sort fragment](../fragments/sort). ### Context -- **Conformance URI:** ** +- **Conformance URI:** - **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot - **Definition**: [STAC API - Context Fragment](../fragments/context/) diff --git a/item-search/examples.md b/item-search/examples.md index 64ab5c90..0e2913ff 100644 --- a/item-search/examples.md +++ b/item-search/examples.md @@ -1,6 +1,26 @@ -#### Examples +## Item Search Examples -##### Simple GET based search +### Single Collection example + +This example shows how you can request Items from a single collection from the `search` endpoint, without having to using +OGC API - Features. It requests 100 results in `mycollection` that is in New Zealand at anytime on January 1st, 2019: + +```json +{ + "collections": ["mycollection"], + "bbox": [160.6,-55.95,-170,-25.89], + "limit": 100, + "datetime": "2019-01-01T00:00:00Z/2019-01-01T23:59:59Z" +} +``` + +```http +GET /search?collections=mycollection&bbox=160.6,-55.95,-170,-25.89&limit=100&datetime=2019-01-01T00:00:00Z/2019-01-01T23:59:59Z +``` + +### Paging Examples + +#### Simple GET based search Request: ```http HTTP GET /search?bbox=-110,39.5,-105,40.5 @@ -21,7 +41,7 @@ Response with `200 OK`: ``` Following the link `http://api.cool-sat.com/search?page=2` will send the user to the next page of results. -##### POST search with body and merge fields +#### POST search with body and merge fields Request to `HTTP POST /search`: ```json { @@ -84,7 +104,7 @@ Request to `POST /search`: } ``` -##### POST search using headers +#### POST search using headers Request to `HTTP POST /search`: ```json { diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 8b2bf1ad..51a1c4c4 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -2,13 +2,12 @@ *based on [**OGC API - Features - Part 1: Core**](https://www.ogc.org/standards/ogcapi-features)* -- **OpenAPI specification:** [openapi.yaml](openapi.yaml) +- **OpenAPI specification:** [openapi.yaml](openapi.yaml) uses all the OGC API - Features openapi fragments to describe returning STAC Items. - **Conformance URIs:** - - + - - - [Requirements Class Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_core)) - - [Requirements Class OpenAPI 3.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_oas30)) - - [Requirements Class GeoJSON](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_geojson)) -- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Mature - **Dependencies**: - [STAC API - Core](../core) - [OGC API - Features](https://www.ogc.org/standards/ogcapi-features) @@ -34,7 +33,7 @@ The core OGC API - Features endpoints are shown below, with details provided in | `/conformance` | JSON | Info about standards to which the API conforms | | `/collections` | JSON | Object with a list of Collections contained in the catalog and links | | `/collections/{collectionId}` | Collection | Returns single Collection JSON | -| `/collections/{collectionId}/items` | [ItemCollection](../core/itemcollection-spec.md) | GeoJSON FeatureCollection-conformant entity of Items in collection | +| `/collections/{collectionId}/items` | [ItemCollection](../core/itemcollection.md) | GeoJSON FeatureCollection-conformant entity of Items in collection | | `/collections/{collectionId}/items/{featureId}` | Item | Returns single Item (GeoJSON Feature) | | `/api` | OpenAPI 3.0 JSON | Returns an OpenAPI description of the service from the `service-desc` link `rel` - not required to be `/api`, but the document is required | @@ -70,19 +69,11 @@ STAC API. Implementing OAFeat enables a wider range of clients to access the API's STAC Items, as it is a more widely implemented protocol than STAC. -## API Evolution - -The STAC API is still a work in progress. It currently tries to adhere to the OGC API - Features (OAFeat) specification, -with some STAC specific extensions. The OAFeat portion of the API is provided in the *[openapi.yaml](openapi.yaml)* in this directory, -and represents the version of OAFeat that is currently being used by STAC. It may diverge some with the -*[OAFeat](https://github.com/opengeospatial/ogcapi-features)* spec at any given time, either out of date or 'ahead', -with proposals to align OAFeat. The long term goal is for STAC's API and OAFeat to completely align, -ideally all of STAC API is made from OAFeat plus its extension ecosystem, and STAC just focuses on the content. -But until then STAC will work to bring practical implementation experience to OAFeat. - ## Examples -Note that the OAFeat endpoints *only* supports HTTP GET. HTTP POST requests are not supported. +Note that the OAFeat endpoints *only* supports HTTP GET. HTTP POST requests are not supported. If POST is required it is +recommended to use STAC Item Search, as it can be constrained to a single collection to act the same as an OAFeat `items` +endpoint. Request all the data in `mycollection` that is in New Zealand: @@ -107,37 +98,3 @@ Request 10 results from the data in `mycollection` from between January 1st (inc ```http GET /collections/mycollection/items?datetime=2019-01-01T00:00:00Z/2019-03-31T23:59:59Z&limit=10 ``` - -## STAC API - -The STAC API `/search/` endpoint can support the same requests as above, as POST. - -Request 100 results in `mycollection` that is in New Zealand at anytime on January 1st, 2019: - -```json -{ - "collections": ["mycollection"], - "bbox": [160.6,-55.95,-170,-25.89], - "limit": 100, - "datetime": "2019-01-01T00:00:00Z/2019-01-01T23:59:59Z" -} -``` - -Use the *[Query](../fragments/query/README.md)* extension to search for any data falling within a specific geometry -collected between Jan 1st and May 1st, 2019: - -Request to `POST /search`: -```json -{ - "limit": 100, - "intersects": { - "type": "Polygon", - "coordinates": [[ - [-77.0824, 38.7886], [-77.0189, 38.7886], - [-77.0189, 38.8351], [-77.0824, 38.8351], - [-77.0824, 38.7886] - ]] - }, - "datetime": "2019-01-01/2019-05-01" -} -``` diff --git a/overview.md b/overview.md index c1ac0433..1fe1f2e2 100644 --- a/overview.md +++ b/overview.md @@ -1,4 +1,4 @@ -## About +# 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 @@ -7,10 +7,8 @@ they care about. STAC API extensions specifies those query parameters, and compl 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 +## STAC API Description 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 @@ -19,7 +17,7 @@ off point for the more powerful capabilities - it contains a list of URL's, each 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 +There are then two 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. @@ -33,80 +31,87 @@ 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 +The other major functionality for a STAC API is to [serve STAC Collections and Items](ogcapi-features) through +[OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html). This enables any OAFeat client +to access STAC Items in the same way they do any other data. Every STAC Collection becomes available at the +`collections/` endpoint, with each `collections/{collectionId}/items` endpoint allowing search of the items +in that single collection. For STAC this means implementing [OGC API - Features +Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_core), as well as 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 +[OpenAPI](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_openapi_3_0) options, since 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 +### Extensions & Fragments + +Both STAC API and OAFeat allow 'extensions' that can be added for additional functionality. The STAC community has +created a number of extensions to OAFeat, in order to meet requirements of its implementors, and the complete list +can be found in the [extensions document](extensions.md), which links to each of them and details their maturity . +These are specified in OpenAPI, which works cleanly when the new functionality is a new api location (a complete +resource, or adding POST to an existing one). Many of the additions, however, are done at the parameter or response +level, like adding a `sortby` field to return ordered results. To make these reusable by both Item Search and OAFeat, +in STAC they are specified in the [fragments/](fragments/) directory, where the core functionality is described. +Each *extension* is made specifically against a part of the STAC API, so that it can be specified as a conformance +class (to say, for example, that item-search supports `sortby` but ogcapi-features does not). But if it is based +on a fragment then it will likely just be a thin wrapper to declare the conformance. This is a bit less than ideal, +but it seemed to be the best approach that actually works with OpenAPI. + +We are working to fully align STAC's OAFeat extensions to be the same as the OGC API building blocks being worked on, +so that every STAC extension is specified at the OGC API level. The end goal is for STAC API to just present a +curated set of extension options. + +## 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). +Future versions will likely depend on [OGC API Common](https://github.com/opengeospatial/ogcapi-common) and additional parts of +Features as components evolve and mature. -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. +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. ## Capabilities List +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") - the endpoints listed below. + 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](core/itemcollection-spec.md) | 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) | +column is more of an example in some cases. OGC API makes some endpoint locations required, those will be bolded below. + +| Endpoint | Specified in | Link Relationship | Returns | Description | +|-----------------------------------------------------|----------------------------|-------------------|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| `/` | [Core](core) | root | [Catalog](stac-spec/catalog-spec/catalog-spec.md) | Extends `/` from OAFeat to return a full STAC catalog. | +| `/search` | [Item Search](item-search) | search | [ItemCollection](core/itemcollection.md) | Retrieves a group of Items matching the provided search predicates, probably containing search metadata from the `search` extension | +| **`/collections`** | [OAFeat](ogcapi-features) | data | JSON | Object with a list of Collections contained in the catalog and links | +| **`/conformance`** | [OAFeat](ogcapi-features) | conformance | JSON | Info about standards to which the API conforms | +| `/api` | [OAFeat](ogcapi-features) | service-desc | OpenAPI 3.0 JSON | The OpenAPI definition of the endpoints in this service | +| **`/collections/{collectionId}`** | [OAFeat](ogcapi-features) | collection | Collection | Returns single Collection JSON | +| **`/collections/{collectionId}/items`** | [OAFeat](ogcapi-features) | items | ItemCollection | GeoJSON FeatureCollection-conformant entity of Items in collection | +| **`/collections/{collectionId}/items/{featureId}`** | [OAFeat](ogcapi-features) | 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. +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. STAC's conformance structure is detailed in the [core](core/). **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. +### Conformance Class Table -| **Name** | **API** | **Conformance URI** | **Description** | -|---------------------------|--------|----------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| -| STAC API Core | STAC | | Specifies the STAC Landing page `/`, communicating conformance and available endpoints. | -| STAC Search | STAC | | Enables search of all STAC Items on the server, with the STAC `[/search](#stac-api-endpoints)` endpoint. | -| OACommon Collections | OACommon | | Provides listing of OGC API Collections ([reference](http://docs.opengeospatial.org/DRAFTS/20-024.html#rc_collections-section)) | -| STAC Response | STAC | | 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 | | 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 | | Describes the API as OpenAPI 3.0 ([reference](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_oas30)) | -| GeoJSON | OAFeat | | Requires OGC API - Features responses to be in GeoJSON ([reference](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_requirements_class_geojson)) | | +| **Name** | **Specified in** | **Conformance URI** | **Description** | +|---------------------------|----------------------------|------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| STAC Core | [Core](core) | | Specifies the STAC Landing page `/`, communicating conformance and available endpoints. | +| Item Search | [Item Search](item-search) | | Enables search of all STAC Items on the server, with the STAC `[/search](#stac-api-endpoints)` endpoint. | +| STAC Features | [OAFeat](ogcapi-features) | | Specifies the use of OGC API - Features to serve STAC Items and Collections | -Additional conformance classes are specified in the [STAC Extensions](extensions.md). +Additional conformance classes are specified in the [STAC Extensions](extensions.md#Conformance-classes-of-extensions).