From 8cbad5e0da2547dd5973da1d2c391aedf2b4d9d4 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Sun, 7 Dec 2025 16:23:10 +0100 Subject: [PATCH 01/12] Generalize /children endpoints to be usable outside of landing page #3, general rewrite/update #2 --- README.md | 171 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 100 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 9b45d7d..7fb44e4 100644 --- a/README.md +++ b/README.md @@ -19,70 +19,87 @@ - [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 -| Endpoint | Returns | Description | -| ----------- | ------- | ---------------------------------------------------- | -| `/children` | JSON | Object with a list of child Catalogs and Collections | +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` -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`. +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. ## 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", @@ -96,55 +113,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", @@ -159,26 +176,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", @@ -190,10 +197,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" } ] } @@ -204,6 +228,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", From a0a019b1a01a67a46e8e1677f906849df8bc8825 Mon Sep 17 00:00:00 2001 From: Jonathan Healy Date: Mon, 8 Dec 2025 15:18:30 +0800 Subject: [PATCH 02/12] Document filtering by type for children endpoint This PR proposes adding an optional `type` query parameter to the `/children` endpoint to support filtering results by resource type (e.g., `Catalog` or `Collection`). ### Motivation While the specification recommends separating different types into different hierarchy branches as a best practice, real-world data organization often results in "mixed content" folders (e.g., a Project Catalog containing both sub-project Catalogs and direct Dataset Collections). In dynamic, database-backed APIs (like those using Elasticsearch), retrieving and paginating mixed-type lists can be computationally expensive and complex to implement. Adding a standard `type` parameter allows: 1. **Backend Optimization:** Implementations can execute efficient, type-specific queries (e.g., `type: "Catalog"`) rather than fetching all children and filtering in memory. 2. **Client Flexibility:** Clients can request only the resource type they are interested in (e.g., "Show me sub-folders" vs. "Show me datasets") without receiving unwanted data. 3. **Standardization:** Prevents the proliferation of custom filter parameters (e.g., `?kind=`, `?filter=`) across different implementations. ### Proposed Change Add a section detailing the `type` parameter: #### Filtering by Type Implementations MAY support a `type` query parameter to allow clients to request a specific resource type. * `GET .../children?type=Catalog` * `GET .../children?type=Collection` --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index 7fb44e4..aaffa2b 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,15 @@ implementations may only return a single type if the children only consist of a 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 + +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. + +* `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 From 3d8dc99e290ad1af709be33cd799ba7f4e04250f Mon Sep 17 00:00:00 2001 From: Jonathan Healy Date: Mon, 8 Dec 2025 18:37:42 +0800 Subject: [PATCH 03/12] Update README.md Co-authored-by: Matthias Mohr --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index aaffa2b..13f4322 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,9 @@ individual request only consist of a single type. ### Filtering by Type -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. +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. * `GET .../children?type=Catalog` - Returns only child Catalogs. * `GET .../children?type=Collection` - Returns only child Collections. From 39ea48beaf4cc3dfaade4090c5ae35cebd673075 Mon Sep 17 00:00:00 2001 From: Jonathan Healy Date: Mon, 8 Dec 2025 18:42:52 +0800 Subject: [PATCH 04/12] Add conformance class for type filtering Co-authored-by: Matthias Mohr --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 13f4322..a209480 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,10 @@ individual request only consist of a single type. ### Filtering by Type +This section describes an OPTIONAL conformance class that adds a `type` query parameter for filtering: + +- **Conformance Classes:** + 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. From a24596232a83e7340fe185948c449a73f9c4a455 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 8 Dec 2025 13:43:21 +0100 Subject: [PATCH 05/12] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a209480..0e5ede6 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ individual request only consist of a single type. This section describes an OPTIONAL conformance class that adds a `type` query parameter for filtering: -- **Conformance Classes:** +- **Conformance Class:** 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. From f909a7f727f5e3440403f424c1c8ae80ba9e7b61 Mon Sep 17 00:00:00 2001 From: Jonathan Healy Date: Wed, 10 Dec 2025 11:12:49 +0800 Subject: [PATCH 06/12] Fix Markdown header for Filtering by Type section Updated the section header for 'Filtering by Type' to use proper Markdown formatting. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 99ec09c..55e67f4 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ - [Link Relations](#link-relations) - [Endpoints](#endpoints) - [Pagination](#pagination) +- [Filtering by Type](#filtering-by-type) - [Example](#example) ## Overview @@ -90,7 +91,7 @@ the STAC API - Collections and Features Specification, section 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. -### Filtering by Type +## Filtering by Type This section describes an OPTIONAL conformance class that adds a `type` query parameter for filtering: From cac84294e01b5300e2a66d1c34ab9cf17314af83 Mon Sep 17 00:00:00 2001 From: Jonathan Healy Date: Wed, 10 Dec 2025 11:16:44 +0800 Subject: [PATCH 07/12] Add 'type' query parameter to getChildren operation Added 'type' query parameter to filter catalogs or collections. --- openapi.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 2c73b03..da41fef 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -46,6 +46,7 @@ paths: conformsTo: - 'https://api.stacspec.org/v1.0.0/core' - 'https://api.stacspec.org/v1.0.0-rc.2/children' + - 'https://api.stacspec.org/v1.0.0-rc.2/children#type-filter' - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core' - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30' - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson' @@ -78,6 +79,14 @@ paths: description: |- A body of Catalogs and Collections that are immediate children of this root Catalog. operationId: getChildren + **parameters:** +        **- name: type** +          **in: query** +          **description: Filters the response to only include Catalogs or Collections.** +          **required: false** +          **schema:** +            **type: string** +            **enum: [Catalog, Collection]** responses: '200': $ref: '#/components/responses/Children' From b131e3950c0dac9720357c24a3829a0d250be843 Mon Sep 17 00:00:00 2001 From: Jonathan Healy Date: Wed, 10 Dec 2025 11:19:16 +0800 Subject: [PATCH 08/12] Fix syntax --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 55e67f4..374979b 100644 --- a/README.md +++ b/README.md @@ -101,8 +101,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. From 15407f0a2debcc09378f4e133cbd3980ba3bc161 Mon Sep 17 00:00:00 2001 From: Jonathan Healy Date: Wed, 10 Dec 2025 11:22:10 +0800 Subject: [PATCH 09/12] Refactor parameters section in openapi.yaml Formatted parameters section for consistency. --- openapi.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index da41fef..0966a65 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -79,14 +79,14 @@ paths: description: |- A body of Catalogs and Collections that are immediate children of this root Catalog. operationId: getChildren - **parameters:** -        **- name: type** -          **in: query** -          **description: Filters the response to only include Catalogs or Collections.** -          **required: false** -          **schema:** -            **type: string** -            **enum: [Catalog, Collection]** + parameters: +        - name: type +          in: query +          description: Filters the response to only include Catalogs or Collections. +          required: false +          schema: +            type: string +            enum: [Catalog, Collection] responses: '200': $ref: '#/components/responses/Children' From 358b4cc6fad4cb89af4d330a2f31286a89592b9f Mon Sep 17 00:00:00 2001 From: Jonathan Healy Date: Wed, 10 Dec 2025 11:30:41 +0800 Subject: [PATCH 10/12] Fix indentation in openapi.yaml parameters section --- openapi.yaml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 0966a65..22947cd 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -80,13 +80,13 @@ paths: A body of Catalogs and Collections that are immediate children of this root Catalog. operationId: getChildren parameters: -        - name: type -          in: query -          description: Filters the response to only include Catalogs or Collections. -          required: false -          schema: -            type: string -            enum: [Catalog, Collection] + - name: type + in: query + description: Filters the response to only include Catalogs or Collections. + required: false + schema: + type: string + enum: [Catalog, Collection] responses: '200': $ref: '#/components/responses/Children' From 1e6ab97d83930a5aa62691b68ca83954325f3543 Mon Sep 17 00:00:00 2001 From: Jonathan Healy Date: Thu, 11 Dec 2025 12:20:45 +0800 Subject: [PATCH 11/12] 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 374979b..03bb18b 100644 --- a/README.md +++ b/README.md @@ -269,7 +269,7 @@ The `GET /children` endpoint response object could look as follows: { "rel": "parent", "type": "application/json", - "href": "https://stac-api.example.com" + "href": "https://stac-api.example" }, { "rel": "self", From ed26e8c58b6b4d9b0e9d4646b90f270e005e3f2f Mon Sep 17 00:00:00 2001 From: Jonathan Healy Date: Thu, 11 Dec 2025 12:30:27 +0800 Subject: [PATCH 12/12] Fix typos and remove redundant links in README --- README.md | 28 +++------------------------- 1 file changed, 3 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 03bb18b..0c339ee 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ it often also implements the [Browsable Extension](https://github.com/stac-api-e 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 +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 @@ -38,7 +38,7 @@ the *immediate* children of a Catalog or Collection in an efficient way, similar 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, +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. ## Link Relations @@ -118,7 +118,7 @@ Please note the `child` and `children` link relations: "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", + "description": "This Catalog aims to demonstrate a simple landing page", "type": "Catalog", "conformsTo": [ "https://api.stacspec.org/v1.0.0/core", @@ -230,23 +230,6 @@ The `GET /children` endpoint response object could look as follows: "title": "Flight 2", "href": "https://stac-api.example/drones/flight-2" }, - { - "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", @@ -266,11 +249,6 @@ The `GET /children` endpoint response object could look as follows: "type": "application/json", "href": "https://stac-api.example" }, - { - "rel": "parent", - "type": "application/json", - "href": "https://stac-api.example" - }, { "rel": "self", "type": "application/json",