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

Filter Extension #128

Merged
merged 28 commits into from
May 26, 2021
Merged

Filter Extension #128

Show file tree
Hide file tree
Changes from 27 commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
6d51718
initial draft for Filter extension
philvarner May 10, 2021
3f51664
filter extension: update text with a few missing details
philvarner May 11, 2021
1d32f24
add more details around implementation requirements
philvarner May 11, 2021
ae9db54
draft openapi spec
philvarner May 11, 2021
26d22ce
update examples, and implementation section
philvarner May 12, 2021
facfd04
remove stray comma
philvarner May 12, 2021
e5031e8
wordsmith text
philvarner May 12, 2021
d22cda2
wordsmith text
philvarner May 12, 2021
c810d2c
wordsmith text
philvarner May 12, 2021
7edc330
improve openapi definition
philvarner May 12, 2021
eba4135
add text about synthetic queryables
philvarner May 13, 2021
7913862
Merge branch 'dev' into filter-extension
philvarner May 14, 2021
e8490d9
add better example, fix linting error in markdown and schemas
philvarner May 14, 2021
518184f
fix ref to cql yml
philvarner May 14, 2021
2bdf845
minor fixes for filter openapi
philvarner May 14, 2021
0b115eb
Merge branch 'dev' into filter-extension
philvarner May 19, 2021
e372618
clarification on queryables, line breaks, wordsmithing
philvarner May 19, 2021
9f9a3dd
fix formatting
philvarner May 19, 2021
7265eb8
redefine conformance classes
philvarner May 20, 2021
820a18e
change conformance class names back to item-search#
philvarner May 20, 2021
c201898
tweak language around proprietary extensions in queryables, add note …
philvarner May 20, 2021
96696c4
update list of conformance class uris in extension page
philvarner May 20, 2021
90c88da
add conformance class field to each extension
philvarner May 20, 2021
61a1f36
fix formatting of filter conformance classes
philvarner May 20, 2021
1fb71cb
fix formatting typo
philvarner May 20, 2021
9acf92d
clarify queryables
philvarner May 20, 2021
b9b7c83
add a getting started section
philvarner May 20, 2021
8e08794
modify text based on comments from Rob
philvarner May 24, 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
21 changes: 9 additions & 12 deletions .circleci/rc.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,15 @@ plugins:
# Apply some recommended defaults for consistency
- remark-preset-lint-consistent
- remark-preset-lint-recommended
# No HTML for security - can't activate yet due to STAC logo in README.md
# - lint-no-html
- lint-no-html
# General formatting
# - - remark-lint-emphasis-marker
# - '*'
- - remark-lint-emphasis-marker
- '*'
- remark-lint-hard-break-spaces
- remark-lint-blockquote-indentation
- remark-lint-no-consecutive-blank-lines
# Detect overly long lines - be liberal for now and don't restrict to 80 yet
# - - remark-lint-maximum-line-length
# - 150
- - remark-lint-maximum-line-length
- 150
# Code
- remark-lint-fenced-code-flag
- remark-lint-fenced-code-marker
Expand All @@ -23,24 +21,23 @@ plugins:
- 'fenced'
# Headings
- remark-lint-heading-increment
- remark-lint-no-duplicate-headings
- remark-lint-no-multiple-toplevel-headings
- remark-lint-no-heading-punctuation
- - remark-lint-maximum-heading-length
- 70
- - remark-lint-heading-style
- atx
- - remark-lint-no-shortcut-reference-link
- false
# Lists
- remark-lint-list-item-bullet-indent
- remark-lint-ordered-list-marker-style
- remark-lint-ordered-list-marker-value
- remark-lint-checkbox-character-style
# - - remark-lint-unordered-list-marker-style
# - '-'
- - remark-lint-unordered-list-marker-style
- '-'
- - remark-lint-list-item-indent
- space
# Tables
- remark-lint-table-pipes
# - remark-lint-table-pipe-alignment # Wait for https://github.com/remarkjs/remark-lint/issues/226
# Urls
- remark-lint-no-literal-urls
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,10 +11,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added recommendation to enable CORS for public APIs

### Changed
- Added Filter extension to integrate OAFeat Part 3 CQL
- Passing the `ids` parameter to an item search does not deactivate other query parameters [#125](https://github.com/radiantearth/stac-api-spec/pull/125)
- The first extent in a Collection is always the overall extent, followed by more specific extents. [opengeospatial/ogcapi-features#520](https://github.com/opengeospatial/ogcapi-features/pull/520)

### Deprecated
- Query extension is now deprecated. Replaced by the Filter extension using OGC CQL

### Removed

Expand Down
20 changes: 11 additions & 9 deletions core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@
- **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
- **Dependencies**: None

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.
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.
This behavior in a RESTful API is known as
[Hypermedia as the Engine of Application State (HATEOAS)](https://en.wikipedia.org/wiki/HATEOAS).
STAC API relies heavily on hypermedia for API resource navigation.
Expand All @@ -29,7 +30,8 @@ client must inspect the the `rel` (relationship) to understand what capabilities
Note the `conformsTo` JSON object follows exactly the structure of OGC API - Features [declaration of conformance
classes](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_declaration_of_conformance_classes), except is available directly under
the landing page. This is a slight break from how OGC API does things, as STAC feels it is important for clients to be able to understand
conformance in a single request. Implementers choosing to also implement the OGC API - Features and/or STAC API - Features conformance classes must also implment the `/conformance` endpoint.
conformance in a single request. Implementers choosing to also implement the OGC API - Features and/or
STAC API - Features conformance classes must also implment the `/conformance` endpoint.

This particular catalog provides the ability to browse down to child STAC Collection objects through its `child` links, and also provides the search
endpoint to be able to search across items in its collections. Note though that none of those links are required, other servers may provide
Expand All @@ -47,13 +49,13 @@ API endpoints from OAFeat or STAC API to be implemented, so the following links

When implementing the STAC API Core conformance class, it it recommended to implement these Link relations.

| **`rel`** | **href to** | **From** | **Description** |
|-----------|--------------------------------------------|--------------------|------------------------------------------------------------------|
| `root` | The root URI | STAC Core | Reference to self URI |
| `self` | The root URI | OAFeat | Reference to self URI |
| `service-desc` | The OpenAPI service description | OAFeat OpenAPI | 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-doc` | An HTML service description | OAFeat OpenAPI | Uses the `text/html` media type to refer to a human-consumable description of the service |
| `child` | The child STAC Catalogs & Collections | STAC Core | Provides curated paths to get to STAC Collection and Item objects |
| **`rel`** | **href to** | **From** | **Description** |
| -------------- | ------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `root` | The root URI | STAC Core | Reference to self URI |
| `self` | The root URI | OAFeat | Reference to self URI |
| `service-desc` | The OpenAPI service description | OAFeat OpenAPI | 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-doc` | An HTML service description | OAFeat OpenAPI | Uses the `text/html` media type to refer to a human-consumable description of the service |
| `child` | The child STAC Catalogs & Collections | STAC Core | 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
Expand Down
27 changes: 15 additions & 12 deletions extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,28 +50,31 @@ are scoped against ogcapi-features*.

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* |
| 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* |
| [Filter](item-search/README.md#filter) | [Item Search](item-search/) and [STAC - Features API](ogcapi-features) `/items` requests | Adds parameter to search Item and Collection properties. | *Pilot* |
| [Context](item-search/README.md#context) | [Item Search](item-search/) response ([ItemCollection](fragments/itemcollection/README.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 Item objects. | *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 Collection and Item endpoints and provides semantics for a versioning scheme for Collection and Item objects. | *Proposal* |
| [Query](item-search/README.md#query) | [Item Search](item-search/) request | Adds parameter to search Item and Collection properties. | *Deprecated* |

### Conformance classes of extensions

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) | <https://api.stacspec.org/v1.0.0-beta.1/item-search#fields> |
| [Query](item-search/README.md#query) | <https://api.stacspec.org/v1.0.0-beta.1/item-search#query> |
| [Context](item-search/README.md#context) | <https://api.stacspec.org/v1.0.0-beta.1/item-search#context> |
| [Sort](item-search/README.md#sort) | <https://api.stacspec.org/v1.0.0-beta.1/item-search#sort> |
| [Transaction](ogcapi-features/extensions/transaction/README.md) | <https://api.stacspec.org/v1.0.0-beta.1/ogcapi-features/extensions/transaction> |
| [Items and Collections API Version](ogcapi-features/extensions/version/README.md) | <https://api.stacspec.org/v1.0.0-beta.1/ogcapi-features/extensions/version> |
| Extension Name | Conformance Class URIs |
|---------------|-------------------------|
| [Fields](item-search/README.md#fields) | <https://api.stacspec.org/v1.0.0-beta.1/item-search#fields> |
| [Filter](item-search/README.md#filter) | <https://api.stacspec.org/v1.0.0-beta.1/item-search#filter:filter><br/><https://api.stacspec.org/v1.0.0-beta.1/item-search#filter:simple-cql><br/><https://api.stacspec.org/v1.0.0-beta.1/item-search#filter:item-search-filter><br/><https://api.stacspec.org/v1.0.0-beta.1/item-search#filter:cql-text><br/><https://api.stacspec.org/v1.0.0-beta.1/item-search#filter:cql-json> |
| [Context](item-search/README.md#context) | <https://api.stacspec.org/v1.0.0-beta.1/item-search#context> |
| [Sort](item-search/README.md#sort) | <https://api.stacspec.org/v1.0.0-beta.1/item-search#sort> |
| [Transaction](ogcapi-features/extensions/transaction/README.md) | <https://api.stacspec.org/v1.0.0-beta.1/ogcapi-features/extensions/transaction> |
| [Items and Collections API Version](ogcapi-features/extensions/version/README.md) | <https://api.stacspec.org/v1.0.0-beta.1/ogcapi-features/extensions/version> |
| [Query](item-search/README.md#query) | <https://api.stacspec.org/v1.0.0-beta.1/item-search#query> |


## Third-party / vendor extensions

Expand Down
1 change: 1 addition & 0 deletions fragments/context/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# STAC API - Context Fragment

- **OpenAPI specification:** [openapi.yaml](openapi.yaml)
- **Conformance Class:** <https://api.stacspec.org/v1.0.0-beta.1/item-search#context>
- **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot
- **Dependents:**
- [Item Search](../../item-search)
Expand Down
1 change: 1 addition & 0 deletions fragments/fields/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# STAC API - Fields Fragment

- **OpenAPI specification:** [openapi.yaml](openapi.yaml)
- **Conformance Class:** <https://api.stacspec.org/v1.0.0-beta.1/item-search#fields>
- **Fragment [Maturity Classification](../../extensions.md#extension-maturity):** Pilot
- **Dependents:**
- [Item Search](../../item-search)
Expand Down
Loading