Readium License Status Document 1.0

Revision: 5

Latest version:

https://readium.org/lcp-specs/releases/lsd/latest

This version:

https://readium.org/lcp-specs/releases/lsd/latest

1. Overview

1.1 Purpose and Scope

This section is informative

This specification, License Status Document, defines a document for representing the status of a DRM license along with interactions that might affect its status. These interactions put additional responsibilities on both Content Providers and Reading Systems.

One of the primary objectives is to support lending in public libraries where a user may have the ability to renew a time-limited loan or return one before it expires.

1.2. Terminology

This specification uses the following EPUB and Licensed Content Protection [LCP] terms:

Publication: A logical document entity consisting of a set of interrelated resources and packaged in an EPUB Container, as defined by the EPUB 3 specifications.
User: An individual that consumes an EPUB Publication using an EPUB Reading System.
EPUB Reading System (or Reading System): A system that processes EPUB Publications for presentation to a User in a manner conformant with the EPUB 3 specifications.

Additionally, it uses the following terms:

Content Provider: The authority that grants the License Document and the Publication to the User, usually a Web Server.
License Document: Document that contains references to the various keys and restrictions that are applied by a specific DRM on a Publication.
Status Document: Document that contains information about the history of a License Document, along with its current status and available interactions.

1.3. Example

This section is informative

In the following example, the Status Document indicates that the License has been registered for a single device and may be renewed or returned.

{
  "id": "234-5435-3453-345354",
  "status": "active",
  "message": "Your license is currently active and has been used on one device.",

  "updated": {
    "license": "2016-08-05T00:00:00Z",
    "status": "2016-08-08T00:00:00Z"
  },

  "links": [
    {
      "rel": "license",
      "href": "https://example.org/license/35d9b2d6",
      "type": "application/vnd.readium.lcp.license.v1.0+json",
      "profile": "http://readium.org/lcp/basic-profile"
    },
    {
      "rel": "register",
      "href": "https://example.org/license/35d9b2d6/register{?id,name}",
      "type": "application/vnd.readium.license.status.v1.0+json",
      "templated": true
    },
    {
      "rel": "return", 
      "href": "https://example.org/license/35d9b2d6/return{?id,name}",
      "type": "application/vnd.readium.license.status.v1.0+json",
      "templated": true
    },
    {
      "rel": "renew",
      "href": "https://example.org/license/35d9b2d6/renew{?end,id,name}",
      "type": "application/vnd.readium.license.status.v1.0+json",
      "templated": true
    }
  ],
  
  "potential_rights": {
    "end": "2014-09-13T00:00:00Z"
  },
  
  "events": [
    {
      "type": "register", 
      "name": "eBook App (Android)", 
      "timestamp": "2016-07-14T00:00:00Z", 
      "id": "709e1380-3528-11e5-a2cb-0800200c9a66"
    }
  ]
}

1.4 Conformance Statements

The keywords must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in [RFC2119].

All sections of this specification are normative except where identified by the informative status label “This section is informative”. The application of informative status to sections and appendices applies to all child content and subsections they may contain.

All examples in this specification are informative.

2. Status Document

2.1. Content Conformance

A Status Document must meet all of the following criteria:

It must meet the conformance constraints for JSON documents as defined in JSON.
It must parse as a single JSON object.
It must be encoded using UTF-8.

Access to a Status Document must not require any form of authentication.

A Status Document should not be served over an insecure connection.

The MIME media type for a Status Document is application/vnd.readium.license.status.v1.0+json and HTTP servers must set the “Content-Type” header appropriately.

2.2. Core Information

A Status Document must include the following information:

Key	Semantics	Format
`id`	Unique identifier for the License Document associated to the Status Document	String
`status`	Current status of the License	Controlled vocabulary, as defined in section 2.3
`message`	A message meant to be displayed to the User regarding the current status of the license	String

All messages provided in the message key should be localized based on the HTTP Accept-Language header included in the request for the Status Document.

2.3. Status of a License

The status field succinctly describes the current status of the license. The following values are allowed:

Value	Semantics
`ready`	The License Document is available, but the user hasn’t accessed the License and/or Status Document yet.
`active`	The license is active, and a device has been successfully registered for this license. This is the default value if the License Document does not contain a registration link, or a registration mechanism through the license itself.
`revoked`	The license is no longer active, it has been invalidated by the Issuer.
`returned`	The license is no longer active, it has been invalidated by the User.
`cancelled`	The license is no longer active because it was cancelled prior to activation.
`expired`	The license is no longer active because it has expired.

2.4. Timestamps

A Status Document must include an updated object where the following keys and associated timestamps are provided:

Key	Semantics	Format
`license`	Time and Date when the License Document was last updated.	ISO 8601
`status`	Time and Date when the Status Document was last updated.	ISO 8601

2.5. Links

A Status Document must include a links object. It contains an array of Link Objects where each object may contain the following keys:

Key	Semantics	Format	Required?
`href`	Link location.	URI or URI Template	Yes
`rel`	Link relationship to the document.	List of well-known relation values, URIs for extensions	Yes
`title`	Title of the link.	String	No
`type`	Expected MIME media type value for the external resources.	MIME media type	No, but highly recommended
`templated`	Indicates that the href is a URI Template.	Boolean	No, default value is `false`
`profile`	Expected profile used to identify the external resource.	URI	No

A Status Document must include at least one link where the relation is set to license.

Relation	Semantics	Templated?	Required?	HTTP Verb
`license`	Location of the License Document associated to the Status Document.	No	Yes	GET

2.6. Potential Rights

A Status Document may provide a list of potential changes allowed for a License Document using the potential_rights object.

This specification defines the following expression of potential rights:

Key	Semantics	Format
`end`	Time and Date when the license ends.	ISO 8601

2.7. Events

A Status Document may provide an ordered list of events related to the change in status of a License Document.

These events are documented in an events object where the following keys are used to describe an event:

Key	Semantics	Format
`type`	Identifies the type of event.	See the enumeration below.
`name`	Name of the client, as provided by the client during an interaction.	String
`id`	Identifies the client, as provided by the client during an interaction.	String
`timestamp`	Time and date when the event occurred.	ISO 8601

The following type values are allowed:

Value	Semantics
`register`	Signals a successful registration event by a device.
`renew`	Signals a successful renew event.
`return`	Signals a successful return event.
`revoke`	Signals a revocation event.
`cancel`	Signals a cancellation event.

3. Interactions

In addition to a standardized document, the LSD Specifications also defines a number of interactions that are all exposed through the links object.

3.1. Handling Errors

To provide a consistent behavior for both clients and end users, all servers must handle errors using the Problem Details JSON object as defined in [RFC7807] with the following additional requirements:

The server must return a title and a type in the Problem Details JSON object
The server should attempt to localize both title and detail based on the Accept-Language header sent by the client

Each interaction in this specification provides a number of Failure Types that are returned to the client if the interaction fails.

3.2. Checking the Status of a License

A client should on a regular basis retrieve a Status Document in order to update a License Document.

If the license timestamp in the updated object of the Status Document is more recent than the timestamp contained in the local copy of the License Document, the client must download the License Document again and replace its previous copy with the new one.

If the links object contains more than one link with a relation set to license, the client must select one of the Link Objects based on the value of their profile property. The selected Link Object must correspond to the highest profile value the client can handle. The order of the links is of no importance.

If the client does not find a profile it can handle in the previous set, it must consider that no updated license is available.

If the status value of a Status Document contradicts the corresponding up-to-date License Document, the License Document takes precedence.

If the Status Document is unavailable or if the client is unable to obtain an internet connection, it must not block the user from accessing the Publication tied to the License Document.

3.3. Registering a Device

Registration is meant to provide the server with a hint of how many clients have interacted with a License Document.

When a client opens a License Document for the first time and gets access to its associated Status Document:

It must attempt to register itself using the link exposed in the Status Document
It must not block the user from accessing the Publication associated to the License Document if the registration fails
It must attempt to register itself again if it couldn’t do so the first time that the License Document was opened

During the registration, the client must always try to send the same unique identifier for a specific device, no matter which Status Document it interacts with. Any further interaction with a provider should use the same identifier/name. The client should consider user privacy when generating a unique identifier, for example by generating a random string during software installation. To prevent user tracking across providers, the client may generate device unique ids for each provider.

If a provider uses registration to monitor license abuse, the provider should take care to prevent forged registrations.

Relation	Semantics	Templated?	Required?	HTTP Verb
`register`	Associate a new device with the License	Yes	No	POST

Parameter	Format	Semantics	Required?
`id`	String	A unique identifier for the device.	Yes
`name`	String	Human readable name for the device.	Yes

Expected Behavior

Server side behavior	HTTP Status Code	Client side behavior
The server registers the device identified by `id` and returns an updated Status Document. The server must update the timestamp of the Status Document contained in the status key of the `updated` object. If the status was previously set to ready, it must be updated by the server to active instead. The server may also add a new event in the `events` object of the Status Document.	200	The client must not attempt to register the device again.

Failure Modes

Type	HTTP Status Code	Title
http://readium.org/license-status-document/error/registration	400	Your device could not be registered properly.
http://readium.org/license-status-document/error/server	5xx	An unexpected error has occurred.

An example of a simple activation link.

{
  "links": [
    {
      "rel": "register", 
      "href": "https://example.org/license/aaa-bbbb-ccc/register{?id,name}",
      "type": "application/vnd.readium.license.status.v1.0+json",
      "templated": true
    }
  ]
}

3.4. Returning a Publication

Returning a publication is meant primarily for library use cases, where a patron can return a publication early in order to get access to a new loan.

If returning is unsuccessful, the client should attempt to return the License again at a later time without necessarily asking the user again.

Relation	Semantics	Templated?	Required?	HTTP Verb
`return`	Ask for the License to be immediately invalidated.	Yes	No	PUT

Parameter	Format	Semantics	Required?
`id`	String	A unique identifier for the device.	No
`name`	String	Human readable name for the device.	No

Expected Behavior

Server side behavior	HTTP Status Code	Client side behavior
The server must ensure that the `end` date and time of the license is set to the current date and time, so that the license expires. The server must return an updated Status Document. The Status Document must contain a `status` with its value set to “returned” if the status was previously set to “active”, “cancelled” if the status was previously set to “ready”. The server must update the timestamp of both License and Status Document contained in the `status` and `license` keys of the `updated` object. The server may also add a new event in the `events` object of the Status Document.	200	The client must process the updated Status Document. The client must download the updated License Document. The client must not allow the user to open the publication anymore. The client should not attempt to return the License anymore.

Failure Modes

Type	HTTP Status Code	Title
http://readium.org/license-status-document/error/return	400	Your publication could not be returned properly.
http://readium.org/license-status-document/error/return/already	403	Your publication has already been returned before.
http://readium.org/license-status-document/error/return/expired	403	Your publication has already expired.
http://readium.org/license-status-document/error/server	5xx	An unexpected error has occurred.

An example of a simple return link.

{
  "links": [
    {
      "rel": "return",
      "href": "https://example.org/license/aaa-bbbb-ccc/return{?id,name}",
      "type": "application/vnd.readium.license.status.v1.0+json",
      "templated": true
    }
  ]
}

3.5. Renewing a License

Renewing a License is also meant primarily for library use cases, where a patron can renew a loan for an extended period of time.

Relation	Semantics	Required?
`renew`	Extends the expiration date of a license into the future	No

The HTTP verb used for such request and the media type of the response payload both depend on the expected interaction between the device and the library server:

HTTP Verb	Media Type	Semantics	Templated?
PUT	`application/vnd.readium.` `license.status.v1.0+json`	A URL where the License Document can be programmatically renewed. Returns a Status Document.	Yes
GET	`text/html`	A URL where human interactions will be required. Returns an HTML page. These interactions should ultimately result in the extension of the term of a License Document.	No

These parameters are strictly for the case where the License Document is programmatically renewed:

Parameter	Format	Semantics	Required?
`id`	String	A unique identifier for the device.	No
`name`	String	Human readable name for the device.	No
`end`	ISO 8601	A new expiration date for the license.	No

Expected Behavior

Server side behavior	HTTP Status Code	Client side behavior
The server must ensure that the `end` date and time of the license is updated. The `end` date and time may be set to the new expiration date for the license, or it may correspond to an extension period controlled by the server. The server must return an updated Status Document. The server must update the timestamp of both License and Status Document contained in the `status` and `license` keys of the `updated` object. The server may also add a new event in the `events` object of the Status Document.	200	The client must process the updated Status Document. The client must download the updated License Document. The client may attempt to renew the License again later.

Failure Modes

Type	HTTP Status Code	Title
http://readium.org/license-status-document/error/renew	4xx	Your publication could not be renewed properly.
http://readium.org/license-status-document/error/renew/date	403	Incorrect renewal period, your publication could not be renewed.
http://readium.org/license-status-document/error/server	5xx	An unexpected error has occurred.

An example of programmatic renewal.

{
  "links": [
    {
      "rel": "renew",
      "href": "https://example.org/license/aaa-bbbb-ccc/renew{?end,id,name}",
      "type": "application/vnd.readium.license.status.v1.0+json",
      "templated": true
    }
  ]
}

An example of interactive renewal: the mechanisms of the library web portal can be reused for handling lending queues, novelties vs long tail etc.

{
  "links": [
    {
      "rel": "renew",
      "href": "https://example.org/renew.html?license=aaa-bbbb-ccc&user=dddd-eeee-ffff&token=gggg-hhhh-iiii",
      "type": "text/html"
    }
  ]
}

4. Relationship to Readium Licensed Content Protection 1.0

4.1. Introduction

This section is informative

This specification defines a way for a Content Provider to connect an LCP License Document LCP] to a Status Document describing the current status of the underlying license.

It does not add any structural elements to the LCP License Document, but the link relations it defines and the potential rights it enumerates may appear in an LCP License Document.

4.2. The `status` Relation

This specification defines one new link relation which may be used in the links object of an LCP License Document.

Relation	Semantics	Required?
`status`	Location of the Status Document associated with this License Document.	No

If a link with the relation status is not present in the links object, the client must process the LCP License Document according to the core LCP specification.

If a link with the relation status is present in the links object, the client must process the Status Document according to the extended rules listed in section 3 of this specification.

The representation of the URI mentioned in the status link must be a valid Status Document.

Normative references

[JSON] The application/json Media Type for JavaScript Object Notation (JSON).
[LCP] Readium Licensed Content Protection.
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels.
[RFC78707] JSON Problem Details.
[URI-Template] URI Template.

Apendix A. JSON Schema

A JSON Schema for LSD 1.0 is available under version control at https://github.com/readium/lcp-specs/tree/master/schema

For the purpose of validating a status document, use the following JSON Schema resource: https://readium.org/lcp-specs/schema/status.schema.json

Readium License Status Document 1.0

1. Overview

1.1 Purpose and Scope

1.2. Terminology

1.3. Example

1.4 Conformance Statements

2. Status Document

2.1. Content Conformance

2.2. Core Information

2.3. Status of a License

2.4. Timestamps

2.5. Links

2.6. Potential Rights

2.7. Events

3. Interactions

3.1. Handling Errors

3.2. Checking the Status of a License

3.3. Registering a Device

3.4. Returning a Publication

3.5. Renewing a License

4. Relationship to Readium Licensed Content Protection 1.0

4.1. Introduction

4.2. The status Relation

Normative references

Apendix A. JSON Schema

4.2. The `status` Relation