Add Deep Traversal & Routing section to README

[jonhealy1]

This PR updates the specification documentation to explicitly address two architectural ambiguity points that arise when implementing this extension for large, nested archives: Deep Traversal and Polymorphism.

Related Issue(s):

• Explicit support for Relative Traversal (Deep Nesting) on any Resource #3

Motivation.

Currently, the specification explicitly defines GET /children at the API Root. However, for deep hierarchies (e.g., Sub-Catalogs or "Collection of Collections"), the behavior for traversing beyond the first level is implicit.

This creates a potential "Dead End" for generic clients: if a client discovers a sub-catalog in the root list, there is currently no standardized URL pattern to request that sub-catalog's children without scraping links.

Proposed Changes.

1. Added "Deep Traversal & Routing" Section:

   • Explicitly standardizes the pattern of appending /children to sub-resource URLs (e.g., /catalogs/{id}/children).
   • This formalizes the "Graph Traversal" pattern (similar to a file system ls command) for nested structures.

2. Added "Filtering by Type" Recommendation:

   • Suggests the standard usage of ?type=Catalog or ?type=Collection.
   • This addresses the difficulty of performing operations on polymorphic lists (mixed types) and aligns with backend optimization strategies (e.g., filtering by type in Elasticsearch/Postgres).

These changes make the extension significantly more robust for building "File Browser" style clients that need to navigate infinite depth.

PR Checklist:

• This PR has no breaking changes.
• I have added my changes to the CHANGELOG or a CHANGELOG entry is not required.

[m-mohr]

Thanks for this. As promised in another issue, I drafted also a PR in #6 which updates the whole README to fully cater for the new approach where the endpoint can be provided at any level/depth. I think it's less confusing if the README doesn't scope it for the landing page and then liberating the requirement in a separate section at the end. Would you also be happy with #6? It only covers your first proposed change (but solves issues #2 and #3), not the query parameter yet.

I think we should add that separately in a new PR, which introduces it as a new conformance class. I think that's important as othrwise clients don't know whether the filter would be available in an API as it is only recommended here. The other question is, whether this is actually needed. As the server implementor can make sure that, if needed, no mixing happens, I don't get the reasoning around the server optimizations. I get it for the client side, but I'm not sure whether it's actually neede there.

[jonhealy1]

@m-mohr I added a pr to #6 I think it's worth mentioning ?types as a suggestion. Asking orgs to have children only be one type is seriously restricting the freedom that this idea is trying to implement. Static STAC catalogs don't have this limitation.

[m-mohr]

I've commented in #7 directly, it's generally fine to add.

Asking orgs to have children only be one type is seriously restricting the freedom that this idea is trying to implement.

It recommends(!) one type per level so that the children response is not polymorphic. I added this based on your feedback, you said it would help with implementation. I can remove that sentence, if you don't need it anymore.

Static STAC catalogs don't have this limitation.

No, but they have the same recommendation in the best practices, I think. So in that sense Children and static STAC is aligned.

Edit: Sorry, I accidentally edited your response instead of adding a reply. Not sure how that happened, I restored your original post.

[jonhealy1]

@m-mohr Would it be better to add your changes to this pr instead of creating a new pr? These are my ideas ultimately.

[m-mohr]

Who had this idea initially is debatable, see also stac-utils/stac-fastapi-elasticsearch-opensearch#308. My PR was not based on this PR, it was started from scratch.
Anyway, let's keep it simple. I've added you as co-author in #6. After the squash the history would now show these commits indivdually anyway.
Closing in favor of #6