Locators are meant to provide a precise location in a publication in a format that can be stored and shared.

There are many different use cases for locators:

• reporting and saving the current progression
• bookmarks
• highlights & annotations
• search results
• human-readable (as-in shareable) references
• jumping to a location
• enhancing a table of contents

Each locator must contain a reference to a resource in a publication (href and type). href must not point to the fragment of a resource.

It may also contain:

• a title (title)
• one or more locations in a resource (grouped together in locations)
• one or more text references, if the resource is a document (text)

Additional locations may also be included in this object, using an extension officially registered on this repository or a URI.

The following extensions are currently registered:

A Locator Text Object contains multiple text fragments, useful to give a context to the Locator or for highlights.

Given the flexible nature of the Readium Web Publication Manifest, we need the ability to provide locations into all sorts of resources (text, audio, video, images).

Fragments are flexible enough to achieve that goal. They also provide a natural extension point for our locator model since any media-type can define its own fragment identifiers.

They're by nature media-specific and should always be understood in the context of the resource that the locator points to (by looking at href and type).

For this purpose, this document identifies the following specifications along with their scope:

Example 1: Pointing to the start of Pride and Prejudice

{
  "href": "http://example.com/chapter1",
  "type": "text/html",
  "title": "Chapter 1",
  "locations": {
    "position": 4,
    "progression": 0.03401,
    "totalProgression": 0.01349
  },
  "text": {
    "after": "It is a truth universally acknowledged, that a single man in possession of a good fortune, must be in want of a wife."
  }
}

Example 2: Pointing somewhere in the middle of an audiobook

{
  "href": "http://example.com/track6",
  "type": "audio/ogg",
  "title": "Chapter 5",
  "locations": {
    "fragments": ["t=389.84"],
    "progression": 0.607379,
    "totalProgression": 0.50678
  }
}

Example 3: Pointing to a rectangle in a page of a PDF

{
  "href": "http://example.com/document",
  "type": "application/pdf",
  "title": "Page 5",
  "locations": {
    "fragments": ["page=5", "viewrect=50,50,640,480"],
    "progression": 0.12703,
    "totalProgression": 0.12703
  }
}

In addition to defining the Locator model, the Readium community also strongly recommend all implementations to follow a number of best practices:

• Best practices for locators per format
• Best practices for calculating locations

A reference JSON Schema is available under version control at: https://github.com/readium/architecture/tree/master/schema/locator.schema.json