Skip to content

Document filtering by type for children endpoint #8

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 13 commits into from
Dec 11, 2025
Merged

Document filtering by type for children endpoint #8

Changes from 3 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
8cbad5e
Generalize /children endpoints to be usable outside of landing page #…
m-mohr Dec 7, 2025
a0a019b
Document filtering by type for children endpoint
jonhealy1 Dec 8, 2025
3d8dc99
Update README.md
jonhealy1 Dec 8, 2025
39ea48b
Add conformance class for type filtering
jonhealy1 Dec 8, 2025
a245962
Update README.md
m-mohr Dec 8, 2025
2511b84
Merge branch 'main' into patch-2
m-mohr Dec 9, 2025
f909a7f
Fix Markdown header for Filtering by Type section
jonhealy1 Dec 10, 2025
cac8429
Add 'type' query parameter to getChildren operation
jonhealy1 Dec 10, 2025
b131e39
Fix syntax
jonhealy1 Dec 10, 2025
15407f0
Refactor parameters section in openapi.yaml
jonhealy1 Dec 10, 2025
358b4cc
Fix indentation in openapi.yaml parameters section
jonhealy1 Dec 10, 2025
1e6ab97
Update README.md
jonhealy1 Dec 11, 2025
ed26e8c
Fix typos and remove redundant links in README
jonhealy1 Dec 11, 2025
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
182 changes: 111 additions & 71 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,70 +19,98 @@
- [STAC API - Core](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/core) or any later 1.x.x version
- **Owner**: @m-mohr

A STAC API Landing Page (a Catalog) can return information about the Catalog and Collection child objects
it contains using the link relation `children` to an endpoint `/children`. The `/children` endpoint must
return the all the Catalog and Collection objects referenced by these `child` link relations.

The purpose of this endpoint is to present a single resource from which clients can retrieve
the immediate children of a Catalog, which may be Catalog or Collection objects.
While the `child` link relations in a Catalog already allow for describing these
relationships, this scheme requires a client to retrieve each resource URL to find any information about
A STAC API, including its Landing Page, can have links with relation type `child` that point to
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
children have to be executed.

This STAC API extension, specifies an endpoint that returns a list of all Catalog and Collection
that are referenced from a Catalog or Collection with the relation type `child`.
For this, it contains using the link with relation type `children` to an endpoint `/children`.
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
applications. Implementers may choose to to return only a subset of fields for each Catalog or Collection,
but the objects must still be valid Catalogs and Collections.

## Link Relations

This conformance class also requires implementation of the link relations in the
[STAC API - Core](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/core) conformance class.
The following Link relations must exist in a Catalog or Collection with link relation type `child`:

The following Link relations must exist in the Landing Page (root).
| rel | Media Type | From | Description |
| ---------- | ------------------ | ------------------- | --------------------------------------------------- |
| `children` | `application/json` | STAC API - Children | List of children of this STAC Catalog or Collection |

| **rel** | **href** | **From** | **Description** |
| ---------- | ----------- | ------------------- | -------------------------------- |
| `children` | `/children` | STAC API - Children | List of children of this catalog |
The following Link relations must exist in the `/children` endpoint response:

The following Link relations must exist in the `/children` endpoint response.

| **rel** | **href** | **From** | **Description** |
| ------- | ----------- | ------------------- | --------------- |
| `root` | `/` | STAC Core | The root URI |
| `self` | `/children` | STAC API - Children | Self reference |
| rel | From | Description |
| -------- | ------------------- | -------------------------------------------------------------- |
| `root` | STAC Core | The langding pag (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. |

## Endpoints

This conformance class also requires for the endpoints in the
[STAC API - Core](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/core) conformance class to be implemented.
| 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:

- `children`: An array of all child Catalogs and Collections
- `link`: An array of Link Objects

The children endpoint can occur at any depth, 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`,
the children endpoint would be available at `GET /missions/sentinel-2/children`
- for a catalog available at `GET /catalogs/{id}`,
the children endpoint would be available at `GET /catalogs/{id}/children`

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
individual request only consist of a single type.

### Filtering by Type

| Endpoint | Returns | Description |
| ----------- | ------- | ---------------------------------------------------- |
| `/children` | JSON | Object with a list of child Catalogs and Collections |
Because the `children` array is polymorphic (containing both `Catalog` and `Collection` objects),
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.

STAC APIs implementing the *STAC API - Children* conformance class must support HTTP GET operation at
`/children`, with the return JSON document consisting of an array of all child Catalogs and Collections in a field `children` and an
array of Links in a field `links`.
* `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.

## Pagination

The `/children` endpoint supports a pagination mechanism that aligns with pagination as described in the
OGC API - Common - Part 2: Geospatial Data specification. This is described in detail in
the [STAC - Features Collection Pagination section](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0/ogcapi-features/README.md#collection-pagination).
To the greatest extent possible, the catalog should be structured such that all children can be
retrieved from the endpoint in a single call.
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).

To the greatest extent possible, the hierarchy should be structured such that all children can be
retrieved from the endpoint in a single call without pagination.

## Example

Below is a minimal example, but captures the essence. Each object in the `children` array
must be a valid STAC [Collection](https://github.com/radiantearth/stac-spec/blob/v1.0.0/collection-spec/README.md) or [Catalog](https://github.com/radiantearth/stac-spec/blob/v1.0.0/catalog-spec/README.md),
and each must have a `self` link that communicates its canonical location. And then
the links section must include a `self` link, and it must also link to alternate representations
(like html) of the collection.
Below is a minimal example, but captures the essence.

The STAC API Landing Page should look like the following (note the `child` link relations):
A STAC API Landing Page (`GET /`) could look like the following.
Please note the `child` and `children` link relations:

```json
{
"stac_version": "1.0.0",
"stac_version": "1.1.0",
"id": "example-stac",
"title": "A simple STAC API Example, implementing STAC API - Children",
"description": "This Catalog aims to demonstrate the a simple landing page",
Expand All @@ -96,55 +124,55 @@ The STAC API Landing Page should look like the following (note the `child` link
{
"rel": "self",
"type": "application/json",
"href": "https://stac-api.example.com"
"href": "https://stac-api.example"
},
{
"rel": "root",
"type": "application/json",
"href": "https://stac-api.example.com"
"href": "https://stac-api.example"
},
{
"rel": "service-desc",
"type": "application/vnd.oai.openapi+json;version=3.0",
"href": "https://stac-api.example.com/api"
"href": "https://stac-api.example/api"
},
{
"rel": "service-doc",
"type": "text/html",
"href": "https://stac-api.example.com/api.html"
"href": "https://stac-api.example/api.html"
},
{
"rel": "children",
"type": "application/json",
"href": "https://stac-api.example.com/children"
"href": "https://stac-api.example/children"
},
{
"rel": "child",
"type": "application/json",
"href": "https://stac-api.example.com/catalogs/cool-data"
"title": "Satellite Imagery",
"href": "https://stac-api.example/satellites"
},
{
"rel": "child",
"type": "application/json",
"href": "https://stac-api.example.com/catalogs/some-other-data"
"title": "Drone Imagery",
"href": "https://stac-api.example/drones"
}
]
}
```

The `/children` endpoint response object should look as follows:
The `GET /children` endpoint response object could look as follows:

```json
{
"children": [
{
"stac_version": "1.0.0",
"stac_extensions": [ ],
"id": "cool-data",
"title": "Cool Data from X Satellite",
"description": "A lot of awesome words describing the data",
"stac_version": "1.1.0",
"id": "satellites",
"title": "Satellite Imagery",
"description": "This category contains data captured by satellites (currently empty).",
"type": "Catalog",
"license": "CC-BY",
"links": [
{
"rel": "root",
Expand All @@ -159,26 +187,16 @@ The `/children` endpoint response object should look as follows:
{
"rel": "self",
"type": "application/json",
"href": "https://stac-api.example.com/catalogs/cool-data"
"href": "https://stac-api.example.com/satellites"
}
]
},
{
"stac_version": "1.0.0",
"stac_extensions": [ ],
"id": "some-other-data",
"title": "Some Other Data from Y Satellite",
"description": "More awesome words describing the data",
"type": "Collection",
"license": "CC-BY",
"extent": {
"spatial": {
"bbox": [[-135.17, 36.83, -51.24, 62.25]]
},
"temporal": {
"interval": [["2009-01-01T00:00:00Z", null]]
}
},
"stac_version": "1.1.0",
"id": "drones",
"title": "Drone Imagery",
"description": "This category contains data captured by drones and other airbone vehicles (from two flights).",
"type": "Catalog",
"links": [
{
"rel": "root",
Expand All @@ -190,10 +208,27 @@ The `/children` endpoint response object should look as follows:
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "children",
"type": "application/json",
"href": "https://stac-api.example/drones/children"
},
{
"rel": "child",
"type": "application/json",
"title": "Flight 1",
"href": "https://stac-api.example/drones/filght-1"
},
{
"rel": "child",
"type": "application/json",
"title": "Flight 2",
"href": "https://stac-api.example/drones/flight-2"
},
{
"rel": "self",
"type": "application/json",
"href": "https://stac-api.example.com/collections/some-other-data"
"href": "https://stac-api.example.com/drones"
}
]
}
Expand All @@ -204,6 +239,11 @@ The `/children` endpoint response object should look as follows:
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "parent",
"type": "application/json",
"href": "https://stac-api.example.com"
},
{
"rel": "self",
"type": "application/json",
Expand Down