Document filtering by type for children endpoint

README.md

@@ -4,6 +4,7 @@
 - [Link Relations](#link-relations)
 - [Endpoints](#endpoints)
 - [Pagination](#pagination)
+- [Filtering by Type](#filtering-by-type)
 - [Example](#example)
 
 ## Overview
@@ -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.
@@ -214,6 +230,23 @@ 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",
@@ -233,6 +266,11 @@ 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.com"
+    },
     {
       "rel": "self",
       "type": "application/json",

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'