Naming of DTS endpoints and resources

[mromanello]

Here below some comments from a user perspective about the current naming of DTS endpoints and resources. We received them during the review process of the DTS paper we submitted to jTEI. It's very useful feedback that should be taken into consideration while revising/improving the specs.

The names adopted are confusing to this new reader. It starts off great. If I access an Apples Endpoint I expect Apples. So a Collections Endpoint returns Collections. Great. But then to get a Reference I would expect a References Endpoint. But it’s called Navigation. [...]
The third collection has other problems though. “Documents” has a specific meaning in XML, refering to a whole document node. Also, “Documents” implies that the other endpoints do not return documents, but a JSON file can be thought of as a document. “Passage” is not well defined in this article. Those places where it is used suggests it is a synonym of “division of text” or “one or more partial or complete units of text.” This in turn implies a tree fragment, which undercuts the “Document” term. Help! I’m confused.
If I were designing this I would call the third endpoint the Text Content Endpoint, which would retrieve instances of Text Content. I would avoid the term passage, and just specify that Text Content may be zero or more descendants of zero or more tei:bodys, specially wrapped. Or something with that level of specificity.