Document filtering by type for children endpoint (#8)

* Generalize /children endpoints to be usable outside of landing page #3, general rewrite/update #2

* 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`

* Update README.md

Co-authored-by: Matthias Mohr <[email protected]>

* Add conformance class for type filtering

Co-authored-by: Matthias Mohr <[email protected]>

* Update README.md

* Fix Markdown header for Filtering by Type section

Updated the section header for 'Filtering by Type' to use proper Markdown formatting.

* Add 'type' query parameter to getChildren operation

Added 'type' query parameter to filter catalogs or collections.

* Fix syntax

* Refactor parameters section in openapi.yaml

Formatted parameters section for consistency.

* Fix indentation in openapi.yaml parameters section

* Update README.md

Co-authored-by: Matthias Mohr <[email protected]>

* Fix typos and remove redundant links in README

---------

Co-authored-by: Matthias Mohr <[email protected]>

Author: jonhealy1

README.md

@@ -4,6 +4,7 @@
 - [Link Relations](#link-relations)
 - [Endpoints](#endpoints)
 - [Pagination](#pagination)
+- [Filtering by Type](#filtering-by-type)
 - [Example](#example)
 
 ## Overview
@@ -26,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
@@ -37,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
@@ -90,6 +91,21 @@ 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
+
+This section describes an OPTIONAL conformance class that adds a `type` query parameter for filtering:
+
+- **Conformance Class:** <https://api.stacspec.org/v1.0.0-rc.2/children#type-filter>
+
+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.
+
+This is recommended for implementations where backend storage (e.g., Elasticsearch indices) or client logic benefits from strict typing.
+
 ## Example
 
 Below is a minimal example, but captures the essence.
@@ -102,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",

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'