Request: mutliple navigations trees

[geoffroy-noel-ddh]

Hi,

Is it possible to expose multiple 'independent' citation trees via the Navigation endpoint? Typical use case: pagination and chapterisation. Or support for multiple pagination/foliation systems.

I guess this could be done in a roundabout way by using the top level to distinguish the different units (page.1, page.2, ..., chapter.1, chapter.2, ...). Although I think the spec says that the items at each level are continuous in the order of the text, so that approach would go against that rule.

Also I didn't see a way to declare the type of the units at each level in the tree. Did I overlook that feature or is it deliberately absent? How does an API client interprets the nature of the levels and units in '1.2.1'? Is that information supposed to be known by the client application?

Once multiple trees are available, a very common requirement is to be able to move from one to the other (e.g. Chapter 2 starts at page 10, or folio 10r is 11r in alternative system) or align them. How could that be achieved with DTS?

Thanks

[geoffroy-noel-ddh]

Ok, now I see that you can label the citation units at each level in the dts:citeStructure of the Collection response. Sorry I missed that.

But the first question still stands: how to achieve "competing hierachies"? such as multiple paginations or pagination and chapterisation for instance.

Also is it possible to declare the units at the navigation level (i.e. per document) rather than the collection level? Or do all the documents within a collection have to support the same types of navigational units? (although I realise it's less of a constraint since collections can be nested).

[PonteIneptique]

First of all, thank you for challenging the API. We are still in the process of cleaning things up, and these question are very helpful toward the definitive release of V1.

I guess this could be done in a roundabout way by using the top level to distinguish the different units (page.1, page.2, ..., chapter.1, chapter.2, ...). Although I think the spec says that the items at each level are continuous in the order of the text, so that approach would go against that rule.

I don't think it's against the rule, but we already discussed that internally I believe, and I think the decision was: if you have a different approach to the document with competing identifier (ie 1 can be page 1 or folio 1 or chapter 1), you should have different documents. Now, as far as I can remember, this does not prevent using page1 and folio1 as identifiers, but I could be wrong.

Also I didn't see a way to declare the type of the units at each level in the tree. Did I overlook that feature or is it deliberately absent? How does an API client interprets the nature of the levels and units in '1.2.1'? Is that information supposed to be known by the client application?

I think you are want to be looking at this https://distributed-text-services.github.io/specifications/Navigation-Endpoint.html#example-9-retrieval-of-typology-of-references if I understand your question well. You can use dts:citeType at the tree declaration step (in the Collection API) or/and at the Navigation retrieval step.

Once multiple trees are available, a very common requirement is to be able to move from one to the other (e.g. Chapter 2 starts at page 10, or folio 10r is 11r in alternative system) or align them. How could that be achieved with DTS?

That is the thoughest question of all... I think for this kind of approaches, I'd annotate the Navigation items using the extended metadata or DublinCore capacities, such as :\

"member": [
      {
        "dts:ref": "Av",
        "dts:level": 1,
        "dts:dublincore": {
        "dc:hasVersion": "OTHER ID"
        }
      },

But I don't think it's completely satisfying. We'll need to rediscuss that internally after other questions are replied to.

[geoffroy-noel-ddh]

Thanks a lot for the useful information!

The alignment feature is a tricky one. I don't see it as core requirement in my case although it often comes up in user interface. A typical use case would be for the user to jump to a chapter, then sequentially 'turn' the pages. One way I have approached that feature in other APIs is by returning a json response with the desired passage accompanied by the references of that passage in all parallel citation trees. I.e. user requests chapter 2, we return it with metadata saying chapter 2 and page 10. However DTS Documents endpoint returns a TEI file directly, so that sort of metadata is less easy to pass along.

Regarding the parallel citation tree per text...

I don't think it's against the rule, but we already discussed that internally I believe, and I think the decision was: if you have a different approach to the document with competing identifier (ie 1 can be page 1 or folio 1 or chapter 1), you should have different documents. Now, as far as I can remember, this does not prevent using page1 and folio1 as identifiers, but I could be wrong.

Using one sibling document per citation tree is a possibility. It is similar to what you also suggested for 'views'. I see how it keeps the spec simpler, but it may complicate the client app. For instance, an edition of a text with two views (semi-diplo, and interpretive) and two citation trees (chapterisation and foliation) would generate four DTS navigations and DTS documents and the client would have to move around them each time the user change the view or the unit of citation.

In my case I was thinking of using something like this to have competing trees in the same navigation response:

"member": [
    {
      "dts:ref": "f.1",
      "dts:level": 1,
    },
    {
      "dts:ref": "f.2",
      "dts:level": 1,
    },
    [...]
    {
      "dts:ref": "f.512",
      "dts:level": 1,
    },
    {
      "dts:ref": "ch.1",
      "dts:level": 1,     
    },
    {
      "dts:ref": "ch.2",
      "dts:level": 1,
    },
    [...]
]

Or, alternatively:

"member": [
    {
        "dts:ref": "p",
        "dts:level": 1,
    },
    {
        "dts:ref": "ch",
        "dts:level": 1,
    },
]

Then level 2 under p: p.1, p.2, ... and under ch: ch.1, ch.2, ...

But in both cases I don't see how a client app can rely on the DTS spec to determine that a level 1 some units are sequential rather than alternative (nothing says that ch doesn't appear after p, it's a matter of a project-specific convention).

[geoffroy-noel-ddh]

Please feel free to ignore my comments if unwelcome. I'm currently developing tools based on DTS for a few projects so I've got my head deep down this kind of issues while I'm trying to find practical solution to them but I won't be offended if ignored.

Here's a suggestion in case there was interest in supporting alternative/parallel/competing (sub)trees of citations per document. Each reference in the tree could express via a standard DTS property the more precise nature of its containment wrt direct children, by borrowing from RDFS vocabulary. For backward compatibility, in the absence of such property the assumed value would be rdf:Seq. Whereas alternative could be expressed with rdf:Alt.

"member": [
    {
        "dts:ref": "p",
        "dts:level": 1,
    },
    {
        "dts:ref": "ch",
        "dts:level": 1,
    },
]

In the last example above the "referenceNode" at the top of the tree would be Alt rather than Seq. Allowing the client app to know that p and ch are not in the same sequence but alternative sub-trees.

However this would also require that a Navigation request without a supplied ref has a referenceNode representing the root of the citation tree rather than being absent. The spec seem to introduce that distinction with the type of the [dts:parent being the whole Resource)](https://github.com/distributed-text-services/specifications/blob/master/Navigation-Endpoint.md#example-3-requesting-children-of-one-top-level-structural-division-of-a-resource as if there was no root or containing node above member 1 level.

[PonteIneptique]

During the RC Workshop in Durham, it was decided to supported multiple citation trees, while having a silent default one.

From an object perspective, CitationTree are found in the citationTrees property of a Resource (in the Collection and Navigation endpoint), which is an Array of CitationTree object. CitationTree objects contain both a maxCiteDepth (which was moved from the Resource to the CitationTree) and citeStructure property an Array of CiteStructure objects.

The first CitationTree found in the array at the citationTrees property is the default one, and must not bear an identifier.

From a query parameter standpoint, ?tree is used both in Document and Navigation endpoint. CitableUnit may have an identifier that can be found in two different CitationTree, but each CitableUnity identifier must be unique within a CitationTree.

?tree must not be used to access the default CitationTree

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!