Resolve #10 (self link), #11 (completeness), #12 (/collections)

CHANGELOG.md

@@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- Each Catalog and Collection listed in the `children` array must include a `self` link ([#10](https://github.com/stac-api-extensions/children/issues/10))
+- Catalogs and Collections in the `children` array must be complete and valid; reduced entities are not allowed ([#11](https://github.com/stac-api-extensions/children/issues/11))
+- Clarified that the Collections listed at the `/collections` endpoint are not implicitly part of the `/children` response; only entities referenced via `child` links are included ([#12](https://github.com/stac-api-extensions/children/issues/12))
 - Updated examples and (STAC) version numbers
 - Clarifications and chore changes
 

README.md

@@ -33,13 +33,22 @@ For this, it contains a link with relation type `children` which points to an en
 The `/children` endpoint returns *all* the Catalog and Collection objects referenced by these
 `child` links.
 
+The `/children` endpoint is scoped to the `child` link relations only.
+The Collections listed at the `/collections` endpoint (referenced from the Landing Page via the `data`
+link relation, as defined by STAC API - Collections) are **not** implicitly part of the `/children`
+response. A Collection is only included in `/children` if it is explicitly referenced through a `child`
+link. Conversely, a Collection may be exposed via both endpoints if it is referenced by both a `data`
+(indirectly) and a `child` link.
+
 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 return only a subset of fields for each Catalog or Collection,
-but the objects must still be valid Catalogs and Collections.
+applications. Each Catalog and Collection returned in the `children` array must be a complete and valid
+Catalog or Collection. Unlike the STAC API - Collections endpoint, implementations must not return reduced
+entities (i.e., a subset of the fields); clients can rely on the returned objects being complete and do not
+need to request the full entity from its `self` location.
 
 ## Link Relations
 
@@ -57,6 +66,16 @@ The following Link relations must exist in the `/children` endpoint response:
 | `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.   |
 
+The following Link relations must exist in each Catalog and Collection listed in the `children` array:
+
+| rel    | From      | Description                                                                                     |
+| ------ | --------- | ----------------------------------------------------------------------------------------------- |
+| `self` | STAC Core | Self reference, i.e. the absolute URI at which the individual Catalog or Collection is located. |
+
+The `self` link is required so that clients can unambiguously determine the location of each entity and
+correlate the entities returned by the `/children` endpoint with the corresponding STAC entities (e.g., the
+resources referenced by the `child` link relations of the parent).
+
 ## Endpoints
 
 | Endpoint           | Media Type       | Description                                                         |