Request: Navigation response can return more than one level of the citation tree

[geoffroy-noel-ddh]

Am I correct in thinking that the Navigation API can only return a section of the tree at one single unique level at a time? That is, it cannot return any arbitrary subtree?

Say, if I want the complete 'table of content' of a book, with chapters and their sections, do I have to make at least two calls per document? In the trivial case where the identifiers use a dotted notation (e.g. 1.2), this may not be needed, as level 2 will expose level 1. Unless a chapter has no section. But in other cases (eg. level 2 identifiers based on sub-heading, rather than numeric system) it seems there is no single request that can return all available members of the tree.

In the worst case, a client trying to piece together the entire tree of a document may require two requests per level-1 passage (one for level 1, then one for its children), since the level-2 members don't declare their parents in the tree (unless I overlooked that feature?).

If my interpretation is correct, and there is interest in supporting arbitrary subtree requests in view of providing a table of content in a client user interface with a minimum amount of API requests, maybe the following ideas might be useful:

1. a new, optional, 'depth=D' parameter in the Navigation query, which would essentially work like 'down' but also impose that the response contains D levels going up (e.g.. ref=9&depth=2 would return level 3 and also level 2)
2. possibly add a specific way in the spec for members in the Navigation response to declare the identifier of their parent in the citation tree (so that relationship doesn't have to be interpreted from notational conventions in the identification system of the document units)
3. possibly add a specific way in the spec for members in the Navigation response to contain a title or label (e.g. a chapter heading)

Apologies if those features are already supported and I missed them.

[PonteIneptique]

Edit as the previous message replied to the wrong issue.

During the RC Workshop in Durham, it was decided to that ?down was a tree traversal operation. As such, ?down=2, from the root, would retrieve level 1 and level 2 element in the CitationTree.

?down=-1 allows for retrieving the whole tree or sub-tree of a Resource.

This enables Table of Content proxies.

See #228 for its implementation details and its apparition in the specs.

[monotasker]

We published the resolution of this issue during the tech committee meeting on 2024-03-08
commit a0db8ca
release https://github.com/distributed-text-services/specifications/releases/tag/1-alpha1

This is an alpha release and we are looking for feedback!