How to exchange/represent a collection of Locator objects?

[m-abs]

Hi,

We need to add a bookmark/locators sync API to our streaming service.

I found Position List in this repo. It has no outside references, so it isn't be found via readium.org/architecture/models/locators.

It looks to be what we need for loading bookmarks from the service, but since there isn't a schema or links to it, I'm wondering if it is still relevant?

A schema could be something like this:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://readium.org/architecture/schema/position-list.schema.json",
  "type": "object",
  "properties": {
    "total": {
      "type": "integer"
    },
    "positions": {
      "type": "array",
      "items": [
         {  "$ref": "https://readium.org/architecture/schema/locator.schema.json" }
      ]
    }
  },
  "required": [
    "total",
    "positions"
  ]
}

[mickael-menu]

The Positions List is currently used in the various Readium toolkits to provide a discrete list of locations throughout a publications (akin to page numbers). So it's pretty specific and wouldn't be useful for your use case.

But a generic Locator collections is indeed useful in other cases, like your synchronisation service or the list of results from a publication search. We don't have any official schema/specification for such locator collections, but this would be worth discussing it.

On the Kotlin toolkit I added an ad-hoc LocatorCollection structure, which is pretty similar to the one used for the positions list (in fact, the positions list is just a specialization of a locator collection and could be based on the same schema): https://github.com/readium/kotlin-toolkit/blob/5234c25e2a5e922e0373f743034256f7d18597c7/readium/shared/src/main/java/org/readium/r2/shared/publication/Locator.kt#L216-L283

Some additional features could be embedded in this structure in a networking context, such as pagination.