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

Proposal: add concestor link relation #378

Closed
wants to merge 2 commits into from
Closed

Proposal: add concestor link relation #378

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4133cd1
add concestor link relation
philvarner Jan 29, 2023
19bde24
Merge branch 'main' into pv/concestor
philvarner Jan 30, 2023
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
7 changes: 7 additions & 0 deletions .markdownlint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"no-duplicate-header": false,
"line-length": {
"line_length": 120,
"tables": false
}
}
65 changes: 39 additions & 26 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
<!-- markdownlint-disable MD013 -->
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
## [v1.0.0-rc.3] - TBD

## Added

Expand All @@ -14,7 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

- Item Search `limit` parameter semantics have been changed again to align with the current OAFeat definition, rather than the inconsistent definition in [version 1.0](http://www.opengis.net/doc/IS/ogcapi-features-1/1.0). The new behavior is that if a client requests a limit value above the maximum advertised by the server, that the server should treat the request as if the limit parameter were the maximum value. It must not respond with a error because the the limit value, and must respond with no more than that many items.

## [1.0.0-rc.2] - 2022-11-01
## [v1.0.0-rc.2] - 2022-11-01

### Added

Expand All @@ -24,29 +26,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Changed

- The Collections specification has been incorporated into the *Features* specification, but remains as
a separate conformance class.
a separate conformance class.
- The Browseable specification has been incorporated into the *Core* specification, but remains as
a separate conformance class.
- Extensions moved to standalone specification repositories:
- [Items and Collections API Version](https://github.com/stac-api-extensions/version)
- [Fields](https://github.com/stac-api-extensions/fields)
- [Filter](https://github.com/stac-api-extensions/filter)
- [Context](https://github.com/stac-api-extensions/context)
- [Sort](https://github.com/stac-api-extensions/sort)
- [Transaction](https://github.com/stac-api-extensions/transaction)
- [Query](https://github.com/stac-api-extensions/query)
- [Children](https://github.com/stac-api-extensions/children)
- [Items and Collections API Version](https://github.com/stac-api-extensions/version)
- [Fields](https://github.com/stac-api-extensions/fields)
- [Filter](https://github.com/stac-api-extensions/filter)
- [Context](https://github.com/stac-api-extensions/context)
- [Sort](https://github.com/stac-api-extensions/sort)
- [Transaction](https://github.com/stac-api-extensions/transaction)
- [Query](https://github.com/stac-api-extensions/query)
- [Children](https://github.com/stac-api-extensions/children)

### Fixed

- Item Search `limit` parameter semantics now align with OAFeat. The server must not return more Items than the limit and a limit value higher than advertised in the
service description must return a 400 Bad Request status code.
- Item Search `limit` parameter semantics now align with OAFeat. The server must not return more Items
than the limit and a limit value higher than advertised in the
service description must return a 400 Bad Request status code.

## [v1.0.0-rc.1] - 2022-03-17

### Added

- The CQL2 Accent and Case-insensitive Comparison
- The CQL2 Accent and Case-insensitive Comparison
(`http://www.opengis.net/spec/cql2/1.0/conf/accent-case-insensitive-comparison`) conformance class
adds the ACCENTI and CASEI functions for case-insensitive comparison. These replace the UPPER and
LOWER psuedo-functions that were previously part of the Advanced Comparison Operators class.
Expand All @@ -59,7 +62,7 @@ service description must return a 400 Bad Request status code.
- Clarified behavior of Transaction Extension endpoints:
- PUT and PATCH of a body that changes the `collection` or `id` is disallowed.
- POST, PUT, and PATCH do not need to include the `collection` attribute, as it should be derived from the URL.
- POST and PUT can be used with a body that is at least a GeoJSON Feature, but does not have to be an Item, but for which
- POST and PUT can be used with a body that is at least a GeoJSON Feature, but does not have to be an Item, but for which
the server can derive a valid Item, e.g., by populating the id and collection fields or adding links
- Likewise, POST can be used with a body of a FeatureCollection that contains features that meet the same constraints.
- Specifications now use the term "must" instead of "shall". The semantics of these words are identical.
Expand Down Expand Up @@ -165,53 +168,62 @@ service description must return a 400 Bad Request status code.
## [v1.0.0-beta.3] - 2021-08-06

### Added

- Added STAC API - Collections definition (subset of STAC API - Features)
- More thorough definitions for valid `datetime` and `bbox` query parameter values.

### Changed
- Query extension not deprecated; recommendation to use Filter (https://github.com/radiantearth/stac-api-spec/pull/157)

- Query extension not deprecated; recommendation to use Filter (<https://github.com/radiantearth/stac-api-spec/pull/157>)
- Filter Extension conformance classes refactored to better align with STAC API use cases.
- Renamed conformance class "Queryable First Operand"
(https://api.stacspec.org/v1.0.0-beta.3/item-search#filter:queryable-first-operand) to
(<https://api.stacspec.org/v1.0.0-beta.3/item-search#filter:queryable-first-operand>) to
"Queryable Second Operand"
(https://api.stacspec.org/v1.0.0-beta.3/item-search#filter:queryable-second-operand)
(<https://api.stacspec.org/v1.0.0-beta.3/item-search#filter:queryable-second-operand>)

### Deprecated

### Removed

- Remove stac_version and stac_extensions fields in ItemCollection

### Fixed

## [v1.0.0-beta.2] - 2021-06-01

### Added

- Added Filter extension to integrate OAFeat Part 3 CQL
- Catalog and Collection definitions now have required field "type"
- Added recommendation to enable CORS for public APIs

### Changed

- Updated all STAC versions to 1.0.0
- 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

### Fixed

- Updated text description of root ('/') endpoint (also called landing page) that the return type is a Catalog

## [v1.0.0-beta.1] - 2020-12-10

### 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.
Expand All @@ -229,6 +241,7 @@ service description must return a 400 Bad Request status code.
### Removed

### Fixed

- BBOX openapi yaml to only allow 4 or 6 element arrays
- Fixed invalid OpenAPI files

Expand All @@ -237,11 +250,11 @@ service description must return a 400 Bad Request status code.
See the [stac-spec CHANGELOG](https://github.com/radiantearth/stac-spec/blob/v0.9.0/CHANGELOG.md)
for STAC API releases prior to or equal to version 0.9.0.

[Unreleased]: <https://github.com/radiantearth/stac-api-spec/compare/v1.0.0-rc.2...main>
[v1.0.0-rc.2]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.2>
[v1.0.0-rc.1]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1>
[v1.0.0-beta.5]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.5>
[v1.0.0-beta.4]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.4>
[v1.0.0-beta.3]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.3>
[v1.0.0-beta.2]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.2>
[v1.0.0-beta.1]: <https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1>
[v1.0.0-rc.3]: <https://github.com/radiantearth/stac-api-spec/compare/v1.0.0-rc.2...v1.0.0-rc.3>
[v1.0.0-rc.2]: <https://github.com/radiantearth/stac-api-spec/compare/v1.0.0-rc.1...v1.0.0-rc.2>
[v1.0.0-rc.1]: <https://github.com/radiantearth/stac-api-spec/compare/v1.0.0-beta.5...v1.0.0-rc.1>
[v1.0.0-beta.5]: <https://github.com/radiantearth/stac-api-spec/compare/v1.0.0-beta.4...v1.0.0-beta.5>
[v1.0.0-beta.4]: <https://github.com/radiantearth/stac-api-spec/compare/v1.0.0-beta.3...v1.0.0-beta.4>
[v1.0.0-beta.3]: <https://github.com/radiantearth/stac-api-spec/compare/v1.0.0-beta.2...v1.0.0-beta.3>
[v1.0.0-beta.2]: <https://github.com/radiantearth/stac-api-spec/compare/v1.0.0-beta.1...v1.0.0-beta.2>
[v1.0.0-beta.1]: <https://github.com/radiantearth/stac-api-spec/compare/v0.9.0...v1.0.0-beta.1>
29 changes: 17 additions & 12 deletions core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ Recommendations for structuring Catalogs hierarchically can be found in

## Link Relations

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

| **rel** | **href** | **From** | **Description** |
| -------------- | -------- | --------- | ---------------------------------------------------- |
Expand All @@ -107,26 +107,31 @@ 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).

A `service-doc` endpoint is recommended, but not required. This commonly returns an HTML
The following Link relations may 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. |
| `concestor` | various | STAC API - Core | A link to the most distant ancestor catalog if this catalog is in a tree of sub-catalogs. |
| `child` | various | STAC Core | The child STAC Catalogs & Collections. |
| `item` | various | STAC Core | The child STAC Items. |

The `service-doc` link relation and 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
, 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`.

| **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. |
The `concestor` link is to the most distant ancestor catalog if this catalog is in a tree of sub-catalogs.
Copy link
Collaborator

@m-mohr m-mohr Jan 30, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

I'm not sure I understand. First of all, concestor I've never heard before but I'm also a non-native spreaker. Assuming I'm somewhat "average", this might not be as ituitive as the other relation types.

Also, from the description below I'm not sure what the difference between root and concestor is. Initially, I'd think that if I follow all parent links I'd get to the root. So this likely needs more explanation.

Would this be a good extension as it seems relatively niche?

PS: There are a lot of unrelated changes in this PR. Is this intentional? Makes the review pretty time-consuming.

This link is to the final URL that is reached when recursively following parent link relations. The word was
coined by Richard Dawkins to describe the genetic concepts of "most recent common ancestor" (MRCA) or
"last common ancestor" (LCA).

Additionally, `child` relations may exist to child Catalogs and Collections and `item` relations to Items. These
relations form a directed graph that enables traversal from a root catalog or collection to items.
The `child` relations may exist to child Catalogs and Collections and `item` relations to Items. These
relations form a directed graph that enables traversal from a root catalog or collection to items.

If all Items in a Catalog can be accessed by traversing these links, the browseable conformance class
<https://api.stacspec.org/v1.0.0-rc.2/browseable> should be advertised also.

| **rel** | **href** | **From** | **Description** |
| ------- | -------- | --------- | -------------------------------------- |
| `child` | various | STAC Core | The child STAC Catalogs & Collections. |
| `item` | various | STAC Core | The child STAC Items. |

While it is valid to have `item` links from the landing page, most STAC API implementations
serve large numbers of features, so they will typically use several layers of intermediate `child` links before
getting to Item objects. These relations form a directed graph
Expand Down