Do we need to specify the 'result' of selections?

[iherman]

What the Locator draft defines is a way to express various types of locations. However, do we need to formally define a data structure (using, e.g., IDL) that should be return when acting on those locations?

[iherman]

What the Locator draft defines is a way to express various types of locations. This is in line with what (afaik) EPUBCFI does, but is also in line with the Annotation Spec; after all, what the Annotation Spec defines is a data format aimed at interchange among annotation systems, and the selectors/locators are part of that.

However, if we consider the Locator spec in the setting of Web Publications, we may want to have a world where a WP implementation consists of a number of interrelated items, javascript programs, polyfills, whatever; the question whether we want to, or whether we have to, define some level of interoperability of such possible modules. Would there be a "locate" function that would return… return what, in fact? A data structure referring to URL-s and references to DOM nodes? If so, how would that look? More importantly, do we need to formally define the return structure?

I guess those of you who have been part of Annotation implementations have more idea on how selectors were implemented internally, and may have, therefore, a better idea. Similarly, those of you who have implemented EPUBCFI even for internal reasons may have a better idea, too...

[BigBlueHat]

This one's super dependent on the thing being annotated. If there's a DOM, it likely returns one or more Ranges (depending on whether you cross element boundaries, etc). @tilgovi and @Treora can say more on this one from their work on Apache Annotator. Setting that return expectation for the DOM would likely have value.

However, what's return if a reading system provides image-based annotation (outside of an HTML context)? There's no DOM there. You can certainly get the selector returned, but if you're looking for a "DOM-like", WebIDL definable something, I'm not sure what that would be--especially if the hope is that it might be cross format. Thoughts?

[Treora]

I have been pondering about this too. I have the feeling that since each Selector specification is specific to a document type (or multiple, but defines the meaning for each type), it could also specify the 'document type' of the match it returns.

I am by the way mainly thinking about whether/how the match of a selection can always be treated as a document itself when passed to the selector given in the refinedBy attribute. And how, subsequently, the match and the match within that can be treated as a single composed match. I only tried this with strings, which is easy, as you can just sum the indexes of the match locations (see here).

[tilgovi]

Forgive me if I misuse terminology. I'm not familiar with Locators yet, but I'll speak in terms of annotation selectors.

I think it is okay to specify, at a level like IDL, to inform APIs. While it is true that some things vary across media types, a general result shape may be specifiable in a useful way.

Consider the regular expression API in JavaScript. The RegExp.prototype.exec() function returns a result array augmented with properties index and input. The first item of the array is the substring that matched.

Generalizing from RegExp, a "result" might have one or more of these things:

• What was located (media type dependent)
• What was searched (media type dependent)
• Where it was found (selector / locator / media type dependent? — I'm not sure)
• What was asked for (the original selector / locator)

At a high level, I imagine an API where a bag of search functions are executed and I get back results like the above. It's nice not to assume that the code receiving a result knows which function was executed.

I think it is potentially useful to specify a result. While it's not really possible to specify the type of the data, I think a result that unifies the input and output of a search into a common shape is what we should think of as a result. A result captures a whole search interaction rather than just the located data.

[tilgovi]

In case the correspondence between the generalization and the RegExp result was not clear:

• What was located (result[0])
• What was search (result.input)
• Where was it found (result.index)
• What was asked for

The last of these is absent from the result; it is the RegExp object itself. Arguably, it's excessive to put it on the result object, but I think it might have been a nice convenience.

[tcole3]

We also may want to look at examples of ways that results and processing of locators (and the like) are handled in different specifications, for instance:

From 27 Nov WG call, here is a link offered during the call as to how the WhatWG HTML standard currently (as of 27 Nov) describes what a UA is supposed to when encountering a fragment identifier appended to a URL, with full details about how to process fragment identifiers appended to the URL of an HTML document (and all HTML MIME types). This section of the WhatWG HTML standard also notes (by way of example for other media types) that, "the processing of fragments for XML MIME types is the responsibility of RFC7303". Note that RFC 7303 in turn points to XPointer specs.