Are there guidelines/best practices for using Readium Locators with OPDS?

[xayhewalo]

For some context: I'm developing an e-paper based eReader and I'm exploring methods to sync reading progression on the physical device to a remote server. Ideally, the reading progression on my custom eReader could sync with other OPDS compatible clients like Thorium Reader, Aldiko, etc. It looks like I can do this with OPDS but I have questions.

I've read the discussions on the proposed synchronization service in this repo and the related discussions in the readium repo and OPDS-PSE repo as well. It sounds like ODPS 2.0 will do what OPDS-PSE did for OPDS 1.X, and more.

I'm new to the world of publication distribution, but I read the OPDS 1.2 spec, the OPDS 2.0 spec, the Readium Web Publication Manifest, and read through the Readium Architecture docs and found (very brief) reference to Locator Objects in the Navigator Docs , the Positions List docs, and, indirectly, in the Publication Server docs since that references the Position List API. If I'm reading the docs correctly, Locator Objects should only be used in Positions Lists and must be implemented by "Level 2" Publication Servers.

I can think of several ways to use Locator Objects to sync reading progression between my custom eReader and a remote server, but I'm unsure if there is canonical way to do this so that other OPDS 2.0 compliant clients can also be aware of that reading progress.

Also there appears to be no locations in the 2.0 schema I've stumbled on.

[mickael-menu]

We don't have any official document for synchronizing a publication's reading position through OPDS yet.

However, we implemented just that in Aldiko, using Locator objects as you suggested, using the following in-house spec.

This works with a dedicated web service, discoverable as a link in an OPDS publication.

---

Progression API

The progression API is meant to synchronize the current progression in a publication between reading apps and an OPDS catalog.

Progression Document

This API is built on top of the Locator model, as defined in the Readium Architecture: https://readium.org/architecture/models/locators/

Both the reading app (client) and OPDS catalog (server) exchange a single Progression Object at a time that represents the current progression in a publication.

Progression Object

Key	Definition	Format	Required
modified	Last known modification timestamp of the progression in a publication.	ISO 8601 time and date	Yes
device	Describes the device that transmitted the last known progression.	Device Object	Yes
Locator	Locator for the last known progression.	Locator Object (as defined in Readium)	Yes

Device Object

Key	Definition	Format	Required
id	A unique identifier for the device that transmitted the last known progression.	String	Yes
name	A name for the device that transmitted the last known progression.	String	Yes

Examples

Example 1: Progression document for an EPUB

{
  "modified": "2022-02-08T17:00:00Z",
  "device": {
    "id": "6288f156-3c2d-41de-83f4-b085e40361e7",
    "name": "Pixel 5"
  },
  "locator": {
    "title": "Chapter 1",
    "href": "chapter_1.xhtml",
    "type": "application/xhtml+xml",
    "locations": {
      "position": 4,
      "progression": 0.03401,
      "totalProgression": 0.01349
    }
  }
}

Example 2: Progression document for a PDF

{
  "modified": "2022-02-08T17:00:00Z",
  "device": {
    "id": "6288f156-3c2d-41de-83f4-b085e40361e7",
    "name": "Pixel 5"
  },
  "locator": {
    "title": "Chapter 1",
    "href": "book.pdf",
    "type": "application/pdf",
    "locations": {
      "fragments": ["page=4"],
      "position": 4,
      "progression": 0.01349,
      "totalProgression": 0.01349
    }
  }
}

Example 3: Progression document for an audiobook

{
  "modified": "2022-01-28T15:00:00Z",
  "device": {
    "id": "96492da5-53c2-42dc-9c27-bc17d2b2cb7c",
    "name": "Connected Tea Kettle"
  },
  "locator": {
    "title": "Chapter 5",
    "href": "track6.mp3",
    "type": "audio/mpeg",
    "locations": {
      "fragments": ["t=389.84"],
      "progression": 0.607379,
      "totalProgression": 0.50678
    }
  }
}

Service Discovery

The Progression API can be identified through the links of an OPDS 2.0 publication:

{
  "href": "https://example.com/publication/1/position",
  "type": "application/vnd.readium.progression+json",
  "rel": "http://www.cantook.com/api/progression"
}

Since interacting with the Progression API will always require authentication, it is highly recommended to include the authenticate property in order to avoid additional network roundtrips:

{
  "href": "https://example.com/publication/1/position",
  "type": "application/vnd.readium.progression+json",
  "rel": "http://www.cantook.com/api/progression",
  "properties": {
    "authenticate": {
      "href": "https://example.com/authentication.json",
      "type": "application/opds-authentication+json"
    }
  }
}

Interactions

Requesting the last-known progression

HTTP Verb	Expected behavior
GET	The client requests the last known progression from the server. If the progression transmitted by the server is more up to date than the one known by the client, the new progression is saved.

Successful response

HTTP Status Code	Payload
200	Progression Document
204	No payload

Updating the last-known progression

HTTP Verb	Expected behavior
PUT	The client transmits the last known progression to the server. If the progression transmitted by the client is more up to date than the one known by the server, the new progression is saved by the client.

Successful response

HTTP Status Code	Payload
200	Progression Document

Failure modes

For all failure modes, the payload will return a Problem Details JSON object along with title and type keys to identify the nature of the error.

HTTP Status Code	Title	Type
400	The Progression Document could not be processed properly.	http://www.cantook.com/api/progression/error/document
409	The last known position stored by the server is more up to date.	http://www.cantook.com/api/progression/error/date

Appendix A - JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Progression API",
  "properties": {
    "modified": {
      "type": "string",
      "format": "date-time"
    },
    "device": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "locator": {
      "$ref": "https://readium.org/architecture/schema/locator.schema.json"
    }
  },
  "required": [
    "modified",
    "device",
    "locator"
  ]
}

[xayhewalo]

Thanks for the detailed reply!

We don't have any official document for synchronizing a publication's reading position through OPDS yet.

Are there plans to add it to OPDS when 2.0 eventually releases? Or in a later 2.X spec? Enabling end users to keep reading progression across clients would fulfill OPDS' promise to be decentralized. It would also combat the walled-gardens current commercial distributors promote.

Also the links to cantook.com seem to redirect to a demarque .com 404 page.

[mickael-menu]

At present, there is no plan to add it to OPDS, but that could change if there is sufficient interest from stakeholders.

This is an internal specification, so we used the cantook.com domain. Even though the page is a 404, it doesn't matter; it simply serves as a unique identifier for the error type.

[gotson]

The anansi community would definitely be very interested in a common opds specification for read progress. So far we all maintain our own api, but it's not sustainable for clients.

[xayhewalo]

Thanks for the information @mickael-menu. I'll mark your response as the answer, but I'll second @gotson 's request for a common OPDS read progression spec. Even if it's not as detailed as Aldiko's.

[Shazib]

+1 from me for progressiong sync!