From 4f0078caecf2659838fb0110c8e1c0fb3921fcf7 Mon Sep 17 00:00:00 2001 From: Francis Charette Migneault Date: Thu, 21 May 2026 10:12:57 -0400 Subject: [PATCH 1/4] replace ... by ** to clarify the 'any depth' capability of the endpoint --- CHANGELOG.md | 1 + README.md | 37 +++++++++++++++++++------------------ 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 51f6ea1..5cb6b46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Updated examples and (STAC) version numbers - Clarifications and chore changes +- Replace `...` by `**` in `README.md` to clarify the 'any depth' capability of the endpoint. ## [v1.0.0-rc.2] - 2022-11-01 diff --git a/README.md b/README.md index 0c339ee..d21e380 100644 --- a/README.md +++ b/README.md @@ -24,20 +24,20 @@ A STAC API, including its Landing Page, can have links with relation type `child Catalogs and Collections. This can be used to create arbitrarily complex hierarchies similar to [static STAC catalogs](https://github.com/radiantearth/stac-spec). If APIs implement such behavior, it often also implements the [Browsable Extension](https://github.com/stac-api-extensions/browseable). -The drawback of static catalogs is, that catalogs have to be traversed and a lot of requests for the +The drawback of static catalogs is, that catalogs have to be traversed and a lot of requests for the children have to be executed. -This STAC API extension specifies an endpoint that returns a list of all Catalogs and Collections -that are referenced from a Catalog or Collection with the relation type `child`. -For this, it contains a link with relation type `children` which points to an endpoint `/children`. -The `/children` endpoint returns *all* the Catalog and Collection objects referenced by these -`child` links. +This STAC API extension specifies an endpoint that returns a list of all children Catalogs and Collections +that are referenced by the relation type `child` within a parent Catalog or Collection. +For this, it contains a link with relation type `children` which points to an endpoint `**/children` +relative to the location of the parent containing them. The parent Catalog or Collection can at any depth. +The `**/children` endpoint returns *all* the Catalog and Collection objects referenced by these `child` links. The purpose is to provide a single resource from which clients can retrieve the *immediate* children of a Catalog or Collection in an efficient way, similar to STAC API - Collections. While the `child` link relation already allows for describing these relationships, this scheme requires a client to retrieve each resource URL to find any information about -the children (e.g., title, description), which can cause significant performance issues in user-facing +the children (e.g., `title`, `description`), which can cause significant performance issues in user-facing applications. Implementers may choose to return only a subset of fields for each Catalog or Collection, but the objects must still be valid Catalogs and Collections. @@ -49,26 +49,27 @@ The following Link relations must exist in a Catalog or Collection with link rel | ---------- | ------------------ | ------------------- | --------------------------------------------------- | | `children` | `application/json` | STAC API - Children | List of children of this STAC Catalog or Collection | -The following Link relations must exist in the `/children` endpoint response: +The following Link relations must exist in the `**/children` endpoint response: | rel | From | Description | -| -------- | ------------------- | -------------------------------------------------------------- | +| -------- | ------------------- | -------------------------------------------------------------- | | `root` | STAC Core | The landing page (root) URI | | `parent` | STAC Core | The (parent) URI of the entity containing the `children` link. | -| `self` | STAC API - Children | Self reference, i.e. the URI to the `.../children` endpoint. | +| `self` | STAC API - Children | Self reference, i.e. the URI to the `**/children` endpoint. | ## Endpoints | Endpoint | Media Type | Description | | ------------------ | ---------------- | ------------------------------------------------------------------- | -| `GET .../children` | application/json | Object with a list of Catalogs and Collections and a list of Links. | +| `GET **/children` | application/json | Object with a list of Catalogs and Collections and a list of Links. | -The response of `GET .../children` must be a JSON object with at least two properties: +The response of `GET **/children` must be a JSON object with at least two properties: - `children`: An array of all child Catalogs and Collections - `links`: An array of Link Objects -The children endpoint can occur at any depth, for example: +The children endpoint can occur at any depth, but is contextually relative to its parent (i.e.: `./children`). +For example: - for a landing page (`GET /`), the children endpoint would be available at `GET /children` - for a collection available at `GET /missions/sentinel-2`, @@ -79,12 +80,12 @@ The children endpoint can occur at any depth, for example: Note that although the endpoint in general allows to return both Catalogs and Collections, implementations may only return a single type if the children only consist of a single type. -It is considered a best practice to structure the hierarchy in a way that the children for each +It is considered a best practice to structure the hierarchy in a way that the children for each individual request only consist of a single type. ## Pagination -The `/children` endpoint supports a pagination mechanism that aligns with +The `**/children` endpoint supports a pagination mechanism that aligns with the STAC API - Collections and Features Specification, section [Collection Pagination](https://github.com/radiantearth/stac-api-spec/blob/v1.0.0/ogcapi-features/README.md#collection-pagination). @@ -101,8 +102,8 @@ Because the `children` array is polymorphic (containing both `Catalog` and `Coll implementations MAY support a `type` query parameter to allow clients to filter the response to a specific resource type. Results SHALL be *filtered*, a conversion between Catalog and Collection is not foreseen. -- `GET .../children?type=Catalog` - Returns only child Catalogs. -- `GET .../children?type=Collection` - Returns only child Collections. +- `GET **/children?type=Catalog` - Returns only child Catalogs. +- `GET **/children?type=Collection` - Returns only child Collections. This is recommended for implementations where backend storage (e.g., Elasticsearch indices) or client logic benefits from strict typing. @@ -167,7 +168,7 @@ Please note the `child` and `children` link relations: } ``` -The `GET /children` endpoint response object could look as follows: +The `GET **/children` endpoint response object could look as follows: ```json { From 6e8aac012d5f5f033e333e4cfae85137acf45fae Mon Sep 17 00:00:00 2001 From: Francis Charette-Migneault Date: Mon, 3 Aug 2026 10:35:46 -0400 Subject: [PATCH 2/4] Update README.md Co-authored-by: Matthias Mohr --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d21e380..9af709f 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ children have to be executed. This STAC API extension specifies an endpoint that returns a list of all children Catalogs and Collections that are referenced by the relation type `child` within a parent Catalog or Collection. For this, it contains a link with relation type `children` which points to an endpoint `**/children` -relative to the location of the parent containing them. The parent Catalog or Collection can at any depth. +relative to the location of the parent containing them. The Catalog or Collection can be provided at any level of the STAC catalog hierarchy. The `**/children` endpoint returns *all* the Catalog and Collection objects referenced by these `child` links. The purpose is to provide a single resource from which clients can retrieve From be1c9d66513791010d35dcb09abf1ebe0b243b5d Mon Sep 17 00:00:00 2001 From: Francis Charette-Migneault Date: Mon, 3 Aug 2026 10:39:47 -0400 Subject: [PATCH 3/4] Update README.md Co-authored-by: Matthias Mohr --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9af709f..3b2eec5 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ The drawback of static catalogs is, that catalogs have to be traversed and a lot children have to be executed. This STAC API extension specifies an endpoint that returns a list of all children Catalogs and Collections -that are referenced by the relation type `child` within a parent Catalog or Collection. +that are referenced by the relation type `child` within the corresponding Catalog or Collection that links to the endpoint. For this, it contains a link with relation type `children` which points to an endpoint `**/children` relative to the location of the parent containing them. The Catalog or Collection can be provided at any level of the STAC catalog hierarchy. The `**/children` endpoint returns *all* the Catalog and Collection objects referenced by these `child` links. From 4ff434e21aa70867babe5347447e81f3d383a761 Mon Sep 17 00:00:00 2001 From: Francis Charette-Migneault Date: Tue, 4 Aug 2026 22:48:45 -0400 Subject: [PATCH 4/4] fix cell format --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3b2eec5..47dcda5 100644 --- a/README.md +++ b/README.md @@ -59,9 +59,9 @@ The following Link relations must exist in the `**/children` endpoint response: ## Endpoints -| Endpoint | Media Type | Description | -| ------------------ | ---------------- | ------------------------------------------------------------------- | -| `GET **/children` | application/json | Object with a list of Catalogs and Collections and a list of Links. | +| Endpoint | Media Type | Description | +| ----------------- | ---------------- | ------------------------------------------------------------------- | +| `GET **/children` | application/json | Object with a list of Catalogs and Collections and a list of Links. | The response of `GET **/children` must be a JSON object with at least two properties: