Skip to content

replace ... by ** to clarifiy any depth capability of the endpoint #9

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

Merged
m-mohr merged 4 commits into from
Aug 5, 2026
Merged

replace ... by ** to clarifiy any depth capability of the endpoint #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4f0078c
replace ... by ** to clarify the 'any depth' capability of the endpoint
fmigneault May 21, 2026
6e8aac0
Update README.md
fmigneault Aug 3, 2026
be1c9d6
Update README.md
fmigneault Aug 3, 2026
4ff434e
fix cell format
fmigneault Aug 5, 2026
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
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
41 changes: 21 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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.

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.

Expand All @@ -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. |
| 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:
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`,
Expand All @@ -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).

Expand All @@ -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.

Expand Down Expand Up @@ -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
{
Expand Down