Navigation Endpoint Objects should have a type

[PonteIneptique]

They current have none. I would propose Reference ?

[PonteIneptique]

Types that are currently available:

• Collection (https://w3id.org/dts/api#Collection)
• Resource (https://w3id.org/dts/api#Resource) for readable Collection

Proposed type:

• Reference (https://w3id.org/dts/api#Reference) for object under the Navigation endpoint
• Passage or Document (https://w3id.org/dts/api#Document) for element in the Document endpoint

Argument:

1. Reference is broad and precise enough: elements in the Navigation are neither textual content nor Collection in the same sense as the Collection endpoint. The required information of this object being the couple start/end or ref, it makes sense to call it what it is, a Reference.
   • Alternatives I thought about: Passage (more or less introduces doubt about Navigation vs Document), Citation/CitationUnit (introduces doubt about the items described in the "dts:citeStructure" property in the Collection endpoint)
2. It feels to me having a distinction between Document (full text of a Collection) and a Passage (a partial representation of a Collection) could be useful, but I am not sure about it. It's also not really the subject of this issue, but it feels like it's useful to address both as the same time.
   • Alternative I though about: "TextualNode". It's broad but might be weird. I used it in MyCapytain as the main name of my prototypes.

[balmas]

I agree navigation objects need their own type. I don't really like the term "Reference" even though I know we have used it through the Capitains codebase. I like "CitableUnit" -- @PonteIneptique can you clarify what you mean by "doubt about the items described in the dts:citeStructure property" ?

I am not convinced we need to distinguish Document and Passage or Fragment on the Document endpoint. What is the argument for that?

[monotasker]

If a single passage has the type "CitableUnit" then should ranges have a distinct type "CitableRange" or is a range of passages also considered a "CitableUnit"?

[monotasker]

Also, I'm a bit fuzzy on which object would have this type: the Navigation response object as a whole, or the objects listed in the member property.

[PonteIneptique]

The navigation object as whole, but de facto, members as well...

[monotasker]

Okay, but why would the response object be a "CitableUnit" if it's returning a list of "CitableUnit" objects as members? These CitableUnit members don't have the same required properties as the response object does.

[jonathanrobie]

Why not call it a Citable?

[PonteIneptique]

Decided in 21/12/03 meeting: Ian and I to redesign the root object to be in accordance with its members.

[monotasker]

@PonteIneptique and @monotasker propose a new CitableUnit type to be used for both the root Navigation return object and for each object in the array of members. An example would look like this (with explanatory comments):

{
    "@context": {},
    "@id":"/api/dts/navigation/?id=http://data.bnf.fr/ark:/12148/cb11936111v",
         // EXISTING on root object only (won't add to members because same value applies) 
    "@type": "CitableUnit",  
        // NEW type on root object and members
    "dts:ref": "12" 
        // EXISTING on members; 
        // NEW proposal to add it on root object as well (required? optional?)
        // NB the "dts:start" and "dts:end" properties would be used in a sister type CitableRange
    "dts:citeDepth" : 3, 
        // EXISTING on root object (Required only on root object, not members, so no change here)
    "dts:level": 1 
        // EXISTING on root object only, giving the level of the *members* relative to the root; 
 	// NEW proposal is to 
        // (a) make it the level of the dts:ref passage/node and 
        // (b) include this property on member objects as well
    "dts:passage": "/dts/api/documents/?id=http://data.bnf.fr/ark:/12148/cb11936111v{&ref}{&start}{&end}",
  	// EXISTING on root object only; unecessary in members because same value applies to all (so no change)
    "dts:parent": null
	// EXISTING on root object only
        // NEW proposal is to add it to members as well (but redundant?)
    "dts:dublincore": {},
        // EXISTING on members only (optional)
        // NEW proposal is to add it (optional) to root object
    "dts:extensions": {}
        // EXISTING on members only (optional)
        // NEW proposal is to add it (optional) to root object

    "member": [  
     // EXISTING on root object (should it be optional?); 
     // NEW proposal (?) to allow (optional) on member objects as well
      {
        "dts:ref": "Av",
	    "dts:level": 1,  // Mandatory here !
        "dts:dublincore": {
        	"dc:title": "Avertissement de l'Éditeur"
        },
      },
      {
        "dts:ref": "Pr",
        "dts:dublincore": {
          "dc:title": "Préface"
        }
      },
      // And so on
    ],
}

Ranges would be represented by the type CitableRange, whether the root object or a member. Type has the same properties as CitableUnit except:

• uses dts:start and dts:end (defining range) instead of dts:ref
• no parents
• no metadata
• no level

Defining ranges also raises the issue of how to handle dts:level, especially if the start and end are at different document levels. Here are the options we considered, in our ranked order of preference:

1. "dts:level": null, at least for uneven-leveled ranges. Allows for consistent parsing and is consistent with "dts:parent" handling. Should it be allowed (optional?) with even-leveled ranges? Instinctive choice: specify it for even leveled range. But then it becomes inconsistent with handling of dts:parent
2. No dts:level, but parsing becomes inconsistent
3. "dts:level": {"start": 1, "end": 2} (object as value) Objection: we "complexify" the simple type of the level value by making it an object and it's not in accordance with how we handled dts:parents
4. "dts:level": [1, 2] (array as value), Objection: Not as semantically clear as the object
5. use lower or higher of the two (start/end) levels Objection: semantically confusing because it's not applying to both ends of the range

[PonteIneptique]

Forgotten in proposal: citeDepth which would now be mandatory for each member (?) and the CitableUnit.

After today's meeting:

• Keep the old ?level despite Rename level query parameter on Navigation endpoint #196
• Change dts:level to dts:citeDepth in order to keep the information about the level of the current element and disambiguate the use of the word "level"
• Change dts:citeDepth to dts:citeMaxDepth or something alike (dts:maxDepth might be something as well). Keep depth and maxDepth relative to the root (?).

[PonteIneptique]

Meeting of 22-04-2022

The situation was a bit more complex than renaming the main object, as we agreed on the fact that there are different things mixed together here. The Navigation endpoint is closer to a query endpoint than an "object" endpoint (like the Collection endpoint) which makes the current returned object a mix of:

• Informations about the results
• Results items
• Information about the "reference node" in the query

To deal with that, we agreed to move information about the "reference node" in a new dts:referenceNode property. Only the information about the "result set" are given at the root of the returned object. Finally, members do not change at all.

This change will allow for using the same client-side parser for dts:referenceNode and hydra:members.

Finally, we renamed the returned object Citations.

Here is a somewhat documented example that served the discussion:

{
    "@context": {
        "@vocab": "https://www.w3.org/ns/hydra/core#",
        "dc": "http://purl.org/dc/terms/",
        "dts": "https://w3id.org/dts/api#"
    },

    // These properties are about the result set
    "@id":"/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc&ref=1&down=1",
    "@type": "Citations",
    "dts:passage": "/dts/api/documents/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc{&ref}{&start}{&end}",

    // Needs to be added
    "dts:references": "/dts/api/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc{&ref}{&start}{&end}",

    "dts:citeType": "letter",

    // This is the "center" of the request
    "referenceNode": {
        "@id": "urn:cts:greekLit:tlg0012.tlg001.opp-grc",
        "ref": null,
        "dts:maxCiteDepth" : 2,
        "dts:level": 0,
        "dts:extensions": {},
        "dts:parent": null
    },

    // These are the members resulting from the request
    "member": [
      {"dts:ref": "1.1", "dts:level": 1, "dts:citeType": "preface"},
      {"dts:ref": "1.2", "dts:level": 1},
      {
        "dts:ref": "1.3", "dts:level": 1,
        "dts:dublincore": {
          "dc:title": "Lettre 3"
        },
        "dts:extensions": {
          "foo:fictionalSender": "Cécile Volanges",
          "foo:fictionalRecipient": "Sophie Carnay"
        }
      }
    ],
}

Needs to be implemented in the doc

[PonteIneptique]

@monotasker @jonathanrobie @hcayless If you give it a go written like that, I can try to fit the modifications in my schedule.

[monotasker]

That looks good to me. Thanks Thibault. Ian

…

On Fri., Apr. 22, 2022, 10:59 a.m. Thibault Clérice, < ***@***.***> wrote: @monotasker <https://github.com/monotasker> @jonathanrobie <https://github.com/jonathanrobie> @hcayless <https://github.com/hcayless> If you give it a go written like that, I can try to fit the modifications in my schedule. — Reply to this email directly, view it on GitHub <#184 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFEPH4BHEJE7XBVOPQZFPLVGK5GDANCNFSM4OIBTIEQ> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[geoffroy-noel-ddh]

(Feel free to ignore this comment, if not appropriate)

In that proposal, is the @type of the nodes still a "CitableUnit"?

From a user perspective, it seems the "reference" term is quite ambiguous. I have the impression the spec and documentation use that term for both the "centre" of the Navigation request and, more generally, for the descendent members returned in the response. So they are all references (and CitableUnits) but one is also the reference (or pivot) of the request. That's why I find "referenceNode" slightly confusing as, in essence, all members are also reference nodes in the citation tree. Have I misunderstood something?

[PonteIneptique]

Good point @geoffroy-noel-ddh , I missed your comment.

[PonteIneptique]

During the Durham RC workshop, we reworked heavily this part of the specifications.

References are now CitableUnit which are defined by a required identifier property.
Ranges are basically a couple of CitableUnit described by the Navigation.start and Navigation.end properties.

See the new version to get a clearer list of the effect of what we did in the PR #228