Specification for the DAISY Online Delivery Protocol

Draft Specification for Trial Use
27 September 2009

This version:

This version as a zip archive:

Previous version:

Editors:

Matt Garrish , CNIB

Geoff Gilmour-Taylor , CNIB

Markus Gylling , DAISY Consortium

Kenny Johar , Vision Australia

Jelle Martijn Kok , Solutions Radio

Nick Williamson , RNIB


Abstract

The DAISY Online Delivery protocol is a web service API that facilitates the delivery of digital resources from service providers to end users. The protocol features a core set of operations that can be configured to enable a variety of different download models, making it a flexible and lightweight solution to the growing need for online delivery of published content.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current DAISY publications and the latest revision of this specification can be found in the DAISY projects index at http://www.daisy.org/projects/.

This document was developed by the DAISY Online Working Group as a part of its activities. For a complete list of members at the time of publication, please refer to Appendix B, Acknowledgments.

This document is a Working Group Draft. It completely supersedes the first draft of the specification that was released on April 15, 2009.

This document is considered by the Working Group members to be complete and stable for use in creating implementations of the protocol. It is anticipated that some aspects of the protocol may change before Recommendation status is given to the document, but substantive revisions to the core functionality outlined in this document are not anticipated.

Please report errors in this document and suggestions for the protocol to the Working Group through the public feedback form available on the DAISY site at http://www.daisy.org/contact.

The English version of this specification is the only normative version.

Table of Contents

1. Introduction
2. Terminology
3. Underlying Technologies
3.1. HTTP
3.1.1. HTTP Cookies
3.1.2. HTTPS
3.1.3. HTTP Basic Authentication
3.1.4. HTTP Range Headers
3.2. WS-I
3.2.1. Basic Profile 1.1
3.2.2. WSDL Binding Style
4. Protocol Fundamentals
4.1. Service Models
4.1.1. Lending Model
4.1.2. Acquisition Model
4.2. User Authentication and Session Management
4.2.1. Session Initialization
4.2.2. Session Duration
4.3. Content Selection Methods
4.3.1. Out-of-band Content Selection Method
4.3.2. Browse Content Selection Method
4.4. Issuing and Transfer of Content
4.4.1. Content Retrieval Sequence
4.4.2. Downloading and Streaming of Content
4.4.3. Publishing Updates and Installments
4.4.4. Rights management
4.5. Service Announcements
4.5.1. New Announcements
4.5.2. Read Announcements
4.6. Bookmarks / Last Reading Position
4.7. Dynamic Menus
4.7.1. Support
4.7.2. Root Question
4.7.3. Navigation
4.7.4. Question Types
4.7.5. End Points
4.7.6. Reserved IDs
5. API Reference
5.1. Required Operations
5.1.1. The logOn Operation
5.1.2. The logOff Operation
5.1.3. The setReadingSystemAttributes Operation
5.1.4. The issueContent Operation
5.1.5. The getContentMetadata Operation
5.1.6. The getContentResources Operation
5.1.7. The getServiceAttributes Operation
5.1.8. The getContentList Operation
5.2. Optional Operations
5.2.1. The getServiceAnnouncements Operation
5.2.2. The markAnnouncementsAsRead Operation
5.2.3. The returnContent Operation
5.2.4. The setBookmarks Operation
5.2.5. The getBookmarks Operation
5.2.6. The getQuestions Operation
5.2.7. The getKeyExchangeObject Operation
5.3. Faults
5.3.1. The internalServerError Fault
5.3.2. The invalidOperation Fault
5.3.3. The invalidParameter Fault
5.3.4. The operationNotSupported Fault
5.3.5. The noActiveSession Fault
6. Type Reference
6.1. The announcements Type
6.1.1. announcements Examples
6.2. The bookmarkSet Type
6.3. The contentList Type
6.3.1. contentList Examples
6.4. The contentMetadata Type
6.4.1. contentMetadata Examples
6.5. The KeyExchange Type
6.6. The keyRing Type
6.7. The questions Type
6.8. The read Type
6.9. The readingSystemAttributes Type
6.9.1. readingSystemAttributes Examples
6.10. The resources Type
6.10.1. resources Examples
6.11. The serviceAttributes Type
6.11.1. serviceAttributes Examples
6.12. The userResponses Type
6.13. Element Reference
References
A. WSDL Abstract Definition
B. Acknowledgments

1. Introduction

This section is informative

The DAISY Online Delivery protocol grew out of the need for DAISY producers to be able to deliver content to clients and users in a timely and cost-effective way. The challenges associated with distributing content in physical mediums make these solutions difficult to implement, cumbersome to maintain and environmentally unfriendly.

Although DAISY Digital Talking Books are the primary component of the DAISY standard, the standard itself is evolving and the need to distribute various types of accessible media is one that is already faced by many members of the DAISY Consortium. As a result, the service architecture development for this protocol was done with the goal of getting resources from a provider to a reading system, a design principle that should also make the protocol useful as a content delivery mechanism beyond the sphere of accessible publishing.

The second main development objective was to ensure that the protocol was flexible enough to allow it to be customized and tailored to the delivery needs of any individual or organization. The minimal core functionality facilitates the development of simple services that can, for example, allow users to plug their reading system in at night and automatically download their new content. The expanded set of functionality allows for richer and more interactive models where users can browse for and download their own content.

The protocol was also engineered to facilitate the lending of content, not just its delivery. Libraries and other organizations that require a means to deliver content to users for a limited period of time will find a number of features that facilitate this kind of delivery model. The protocol also enables the use of the PDTB2 content protection scheme where explicit digital rights management issues are a concern.

The protocol has been built on a strong foundation of established technologies to reduce the implementation and maintenance costs for individuals and organizations looking to implement this content delivery model: the interaction between reading systems and services is carried out by SOAP messages over the HTTP protocol; the service operations are all defined by a normative WSDL document; and the protocol itself is compliant with WS-I Basic Profile 1.1.

One feature that could not be tackled in this version of the protocol is the discovery of DAISY Online Delivery services. The DAISY Consortium may develop a system and specification for tracking and locating online services at a later date, but currently no such functionality exists that could be integrated with this protocol.

2. Terminology

This section is normative

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119].

In addition, the following terms are used throughout this document with the meanings outlined in this section.

Borrowable Content

Content that may be lent to a User, and must be returned after being lent. The ownership of the Content does not pass to the User. Borrowable Content includes Content that may be rented for a fee.

Content

A resource made available by a Service Provider through a Service, such as a DAISY Digital Talking Book.

Content Identifier

The unique identifier assigned to a Content item. This identifier is defined by the Service and is exposed in the [Dublin Core] identifier field of the contentMetadata type. The identifier must be unique within the scope of the Service and it must not change over time.

Note:

The Content Identifier is not required to match any identifiers used in the Content (for example, the unique identifier for a DAISY Digital Talking Book).

Download

Transfer of Content from the Service to the Reading System, which the Reading System stores in non-volatile memory.

Note:

Download and Streaming are Reading System behaviors, not aspects of this protocol.

Fault

A [SOAP 1.1] Fault. A fault carries error and/or status information in a SOAP message. Section 5.3, “Faults” defines the faults used in this protocol.

Interface

A [WSDL 1.1] port type. A set of Operations supported by the Service.

Issue content

Grant access to Content. A Reading System uses the issueContent operation to request access from the Service.

Operation

A [WSDL 1.1] operation. An action supported by the Service.

Purchasable Content

Content that may be sold to a User, and should not be returned. The ownership of the Content may or may not pass to the User. Purchasable Content includes Content that is offered for free. It includes any Content that does not require return; for example, Content protected by DRM which expires without the need for return.

Reading System

A combination of hardware and/or software that accesses a Service and renders Content to the User. A Reading System may be implemented entirely on one device or it may be split among several. Corresponds to a [WS-I Basic Profile 1.1 Conformance Targets] consumer.

Return content

Give up access to Content. Content is returned when the Reading System has removed any locally-stored data and called the returnContent operation to notify the Service to revoke access and remove from the User's collection of issued Content. This term applies only to Borrowable Content, not Purchasable Content.

Service

A web service that implements the DAISY Online Delivery Protocol. Corresponds to a [WS-I Basic Profile 1.1 Conformance Targets] instance.

Service Delegate

A file hosting server that is not under the control of the Service Provider.

Service Provider

The person(s) or organization(s) who own a Service.

Note:

The Service Provider may not be the same entity who owns the servers the Service runs on.

Session

A sequence of Operations between one Reading System and one Service using a unique identifier defined by the Service. A session may persist across several HTTP connections. Session identifiers may be reused at the Service's discretion. Session identifiers are sent to the Reading System using [HTTP Cookies].

Streaming

Transfer of Content from the Service to the Reading System, which the Reading System renders immediately and stores only temporarily.

Note:

Download and Streaming are Reading System behaviors, not aspects of this protocol.

Type

An [XML Schema 2] datatype.

User

A person who interacts with a Service using a Reading System and/or or accesses Content from the Service.

3. Underlying Technologies

This section is normative

3.1. HTTP

The DAISY Online Delivery protocol uses [HTTP 1.1]:

  • as the transport layer for all SOAP messages sent and received by a Service; and

  • for the transfer of Content data.

Reading Systems must support [HTTP 1.1] and secure HTTP (HTTPS) through either [SSL 3.0] or [TLS 1.0].

The use of HTTP must conform to [HTTP 1.1] and [RFC 2617].

Services and Reading Systems must support HTTP sessions as specified in [RFC 2109].

Note:

An established HTTP session is not in itself a valid indicator that a Reading System has successfully logged on to the Service (refer to Section 4.2, “User Authentication and Session Management”).

A Service must return the appropriate HTTP status code in the HTTP response (as specified by [HTTP 1.1], Section 10) to all HTTP and HTTPS requests sent by a Reading System.

3.1.1. HTTP Cookies

The DAISY Online Delivery protocol requires the use of [HTTP Cookies] (as defined in [WS-I Basic Profile 1.1]) to maintain stateful sessions.

A Reading System must be able to receive and send any cookies that are transmitted to it by a Service. As per the [WS-I Basic Profile 1.1], a compliant Reading System must not process or manipulate the cookies.

A compliant Service must be able to manage HTTP Cookies.

3.1.3. HTTP Basic Authentication

The HTTP Basic Authentication Scheme described in [RFC 2617] may be used to secure Content against unauthorized access.

When using Basic Authentication, a Service must supply the credentials in the server component field of the Content's URI. The scheme for the userinfo field as given in [RFC 2396], section 3.2.2 is: userinfo @ host : port

If the credentials also require a password, then the userinfo field must be of the form: userid : password @ host : port

Security Consideration

  1. [RFC 2396] recommends against the use of the userid : password scheme as it may result in the transmission of passwords in the clear and is known to be a security risk in all cases. A Service should only use this scheme over a secure connection such as HTTPS and Reading Systems should be developed to avoid the known exploits of this method.

  2. The current best practice for the storage of passwords is to only store a cryptographic hash of each password in case a database is compromised. A Service, however, may need to retrieve the unencrypted authentication credentials for a User in order to supply them in the userinfo field. Services implementing Basic Authentication using this scheme consequently risk compromising the security of their databases unless secure retrieval methods are implemented.

When retrieving Content, a Reading System must only send Basic Authentication credentials when they are supplied in the URI returned by a Service.

The credentials required to access Content are not required to be the same as the credentials supplied to the logOn operation.

Note:

HTTP Basic Authentication credentials must not be used to log on to a Service. For authenticating a SOAP session, refer to Session Initialization Sequence.

A compliant Reading System must support Basic Authentication. Service support for Basic Authentication is recommended.

3.1.4. HTTP Range Headers

When using HTTP or HTTPS for serving resources, a Service must honor Range Retrieval Requests (as described in section 14.35 of RFC 2616).

Services must use correct status codes and Content-Range and Content-Length headers when serving partial content (as described in section 14.16 of RFC 2616).

As it is not possible to require support for range headers on Service Delegates, Reading Systems must be able to handle servers that do not support range headers.

3.2. WS-I

3.2.2. WSDL Binding Style

The WSDL binding style used in the abstract WSDL document in Appendix A, WSDL Abstract Definition is wrapped document-literal. The wrapped document-literal style is a subset of the document-literal style and satisfies normative requirement R2712 of [WS-I Basic Profile 1.1].

Conformant Services must use the wrapped document-literal binding style.

4. Protocol Fundamentals

This section is normative

4.1. Service Models

The DAISY Online Delivery protocol supports two basic service models:

A Service may offer Borrowable Content, Purchasable Content or both.

To provide identical Content under both service models, a Service must supply two Content items with different Content Identifiers. The Content items may have the same set of resources.

A Service must use the requiresReturn attribute of the contentMetadata type to indicate the model it will issue the Content item under. If requiresReturn is true, the Content is borrowable If requiresReturn is false, the Content is purchasable.

Once a Content item is issued, the Service must not change the value of the requiresReturn attribute.

4.1.1. Lending Model

4.1.1.1. Service Requirements

Services offering Borrowable Content must:

The following conditions apply to any item of Borrowable Content:

  • the requiresReturn attribute of the Content's contentMetadata type must be set to true;

  • if issued, the Content item must be listed in either the User's issued or expired contentList until it is returned; and

  • the Service must allow the Reading System to call the returnContent operation at any time to return the issued Content item.

4.1.1.2. Reading System Requirements

The Reading System must not call returnContent with a Content Identifier of a Content item unless all local copies of that Content have been removed.

4.1.1.3. Content Expiry

This protocol defines two methods to assist in the automatic return of Content by a Reading System: the returnBy attribute of the contentMetadata type, and the expired contentList .

Note:

This protocol does not require the enforcement of these methods on the Reading System. Service Providers should investigate other methods for protecting Content that must expire at a specific time (for example DRM schemes like [PDTB2]).

The returnBy attribute indicates the time before which the User should return the Content. Reading Systems should delete the Content at the specified time and return the Content to the Service at the next Session.

Note:

Reading Systems should be able to communicate the due date provided in the returnBy attribute to the User.

The expired contentList may be populated by a Service with Borrowable Content that has been issued to indicate that the Service Provider wants the Content to be returned. If a Reading System has any items of Borrowable Content, it should call getContentList with an id parameter of expired to retrieve this list at least once in each Session, and should return the Content items indicated.

Note:

Service Providers should use the expired contentList with caution. Users should be notified that Content has expired and will be deleted.

4.1.2. Acquisition Model

4.1.2.1. Service Requirements

The following conditions apply to any item of Purchasable Content:

4.1.2.2. Reading System Requirements

The Reading System must not call returnContent with a Content Identifier of a Content item whose contentMetadata type's requiresReturn attribute is false.

4.2. User Authentication and Session Management

Before a Reading System can interact with a Service to obtain Content, it must successfully authenticate itself and establish a valid Session. The following subsections outline the steps in this process.

4.2.1. Session Initialization

The following steps must be followed when starting a Session to authenticate a Reading System to a Service:

  1. The Reading System must pass the User's login credentials to the Service by calling the logOn operation.

    Note:

    The Service Provider is responsible for stipulating and supplying the User with the credentials required to authenticate a Reading System. A non-exhaustive list of ways to provide credentials includes: per User, per group or class of User, or per Reading System.

  2. The Service must verify the provided credentials and, if valid, issue a Cookie [[HTTP Cookies]] with a unique identifier for the Session and embed it in the Set-Cookie HTTP response header.

  3. The Service must send the cookie to the Reading System when returning the successful response to the logOn operation.

After receiving a successful logon response, the Reading System must invoke the following Operations in the given sequence:

  1. The getServiceAttributes operation must be called to discover necessary information about the Service.

  2. The setReadingSystemAttributes operation must be called to provide information about the Reading System's capabilities to the Service. If this call is successful, the Service shall return true ([XML Schema 2]).

If a Service returns a Fault during any of the initialization steps, or if a required return value is not provided, a Reading System must attempt to re-initialize the Session or abort the logon process.

Note:

This protocol does not define what Reading System behaviors must occur after a logon attempt fails. A Reading System can alert the user, attempt to reconnect automatically or take whatever action is particular to that device.

A Service must return an invalidOperation fault if a Reading System attempts to invoke any Operation other than the ones outlined in this section before successfully completing the full initialization sequence.

After completing a successful logon and initialization sequence, a Reading System can invoke any Operations defined by this specification, but must complete the initialization sequence outlined in this section again if calling the logOn operation.

4.2.2. Session Duration

A Session begins after a successful logOn operation. The Session must remain active until the Reading System successfully invokes the logOff operation or the Service terminates it.

Note:

This protocol does not define behaviors relating to the termination of Sessions. Time out intervals, reasons for forced termination and related aspects are defined by the implementation.

A Service should persist a Session across multiple HTTP connections by a Reading System so long as the Session is still active. A Service may allow multiple concurrent connections with the same session ID.

4.3. Content Selection Methods

The DAISY Online Delivery protocol supports two content selection methods:

A Service Provider must offer Users at least one content selection method.

Note:

The two methods for selecting Content outlined in this section are not exclusive. Service Providers may choose to implement aspects of both (for example, to provide an automated newspaper delivery service while allowing Users to browse their catalog).

A Reading System should support both content selection methods for maximum interoperability, but is only required to support one method for conformance.

4.3.1. Out-of-band Content Selection Method

A Service offering the Out-of-band Content Selection Method is compliant if it:

A Reading System may also make use of the issued contentList , if available, to access Content that has already been issued.

For automated downloading scenarios using the out-of-band selection method, the Reading System must also execute the steps outlined in Section 4.4, “Issuing and Transfer of Content”, to obtain the Content.

4.3.2. Browse Content Selection Method

A Service offering the Browse Content Selection Method is compliant if it:

4.4. Issuing and Transfer of Content

The steps for a Reading System to request a Service issue content and to Download or begin Streaming the Content are outlined in the following sections.

4.4.1. Content Retrieval Sequence

In order to download Content from a Service, a Reading System must first invoke the following Operations in the given sequence.

Note:

All of the Operations identified in this section take a Content Identifier as a parameter.

  1. The getContentMetadata operation must be called to obtain information about the Content. The returned metadata includes publication information, file format and size and may include the return status and date.

  2. The issueContent operation must be called to inform the Service that the Reading System intends to access the Content. This operation constitutes the formal request for access. The Service must respond to this request with a true ([XML Schema 2]) value in order to proceed to the next step.

    Note:

    A Reading System is not required to immediately proceed to the next step after successfully being issued Content. Other Operations can be called and/or the Reading System can invoke the next step in another Session.

    If a Service returns a false ([XML Schema 2]) value or a fault, then the Content has not been issued. A Reading System must not proceed to the next step until the Service returns a true value.

    Note:

    This protocol does not specify the Reading System behaviors that occur when a Service does not return a true value.

    Note:

    The calling of the issueContent operation does not require a Service to track any information about the request. Services may respond with a true value to all requests.

  3. The getContentResources operation must be called to obtain the location of all the resources that constitute the Content. A Service may allow more than one call to the getContentResources operation for each issued Content item.

    Note:

    Services that track the issuing of Content should return an invalidParameter fault when a Reading System invokes getContentResources for Content that it has not been issued.

    A Service may allow calls to getContentResources for the same Content over more than one Session.

4.4.2. Downloading and Streaming of Content

Once the Reading System has retrieved the list of resources for a Content item, the Reading System may begin downloading or streaming the resources using the URIs supplied in the resource elements.

Note:

A Reading System does not require an active Session to access Content.

A Reading System must not use the uri attribute of the resource element to name resources locally, as the URIs may resolve to scripts or other content delivery mechanisms. The localURI attribute specifies the path the Reading System must use to store/reference the resource locally.

Note:

The localURI attribute contains a relative path for storing the resource relative to the root content directory used by the Reading System.

The localURI attribute should be used by Reading Systems to locate the URI of resources that are referenced within another resource. For example, the URI for an audio resource in a SMIL file can be determined by checking each resource element to find the localURI attribute that matches the given path.

Reading Systems may use the [MIME] type information in the mimeType attribute of a resource to order the transfer of resources. For example, a Streaming Reading System may retrieve the OPF, NCX and SMIL files of a DAISY Digital Talking Book to provide the User full navigation before downloading any audio data.

Resources may be stored on servers belonging to a Service Delegate. A Service must provide the Reading System any credentials required to access content stored on a Service Delegate's servers.

The URI of each resources secured with Basic Authentication must include the credentials required to access that resource. Refer to Section 3.1.3, “HTTP Basic Authentication”.

4.4.3. Publishing Updates and Installments

This section explains how Service Providers can publish updates to their Content using this protocol.

Each contentItem in a contentList has an optional lastModifiedDate attribute that indicates that last time the Content was modified. A Reading Systems can use this information to determine if the Content on the Service has been updated since the last time it was accessed.

When a Reading System determines that a Content item has been updated, it should invoke the getContentResources operation to get an updated resource list. Each resource also has an optional lastModifiedDate attribute that the Reading System can use to determine the specific resources that have been updated and need to be downloaded again.

When using the lastModifiedDate attribute to publish updates, the Services must ensure that the last modified date for the Content item matches the last modified date of the most recently updated resource.

Reading Systems are not required to inspect modification dates or update Content items. Services are not required to provide modification dates on Content or resource items.

Note:

The functionality detailed in this section can also be used to publish installments by progressively updating the same Content item.

4.4.4. Rights management

The [PDTB2] format may be used to protect Content. This protocol provides a key exchange mechanism, the getKeyExchangeObject operation, to allow Reading Systems to request keys from Services to access encrypted content.

Reading Systems and Services are not required to support PDTB2.

4.4.4.1. Declaring PDTB2 Support

If a Reading System supports PDTB2, it should inform a Service by including a supportedContentProtectionFormats element with the value PDTB2 when it invokes the setReadingSystemAttributes operation.

To indicate that a Service supports PDTB2 key exchange, the Service must include an operation element with the value PDTB2_KEY_PROVISION when responding to a Reading System's invocation of the getServiceAttributes operation.

Note:

Services may provide PDTB2-protected Content without supporting the getKeyExchangeObject operation when alternate means of key provision have been implemented. For example, when keys are provided with the Reading System.

4.4.4.2. Identifying PDTB2 Content

If Content is protected using PDTB2, a Service must include a meta attribute in the contentMetadata named pdtb2:specVersion with the value 2005-1.

In addition, the mimeTypes for protected resource(s) returned from the getContentResources operation must be as defined in section 4.1.1, "Package file", of the [PDTB2] specification. Those MIME types begin with application/x-pdtb….

4.4.4.3. Accessing PDTB2 Content

Any Reading System may access Content marked as PDTB2-protected. Reading Systems that do not support PDTB2 will not be able to render some or all of the resources.

PDTB2-protected content will have an Authorization Object (AO). The Reading System can inspect the AO for the name of the key that secures the key required to decrypt the Content. If the Reading System does not have the key to access an encrypted section of an AO, it may request a Key Exchange Object (KXO) from the Service.

To obtain a KXO, a Reading System must call the getKeyExchangeObject operation with a list of key names in its local keyring together with the name of the requested key. The key names provided can be some or all of the symmetric keys or public/private keypairs the Reading System supports.

The Service may choose any of the keys supplied by the Reading System to encrypt the KXO. If the Service does not have any of the keys or if the User is not authorized to access the Content, then the Service must reply with an invalidOperation fault.

Note:

The Service is responsible for keeping a list of authorized key names.

If the Reading System receives a valid KXO from the Service, the Reading System can then use that KXO to access the key in the AO that unlocks the protected Content.

4.5. Service Announcements

The DAISY Online Delivery protocol allows Service Providers to deliver service announcements directly to a User's Reading System. A service announcement is a message in text and/or audio format that conveys information such as expected Service down time and warnings about overdue Content to the User.

To indicate that a Service supports service announcements, the Service must include an operation element with the value SERVICE_ANNOUNCEMENTS when responding to a Reading System's invocation of the getServiceAttributes operation.

Services are not required to support service announcements. Reading Systems should be able to retrieve and render text and audio service announcements for maximum interoperability.

4.5.1. New Announcements

A Reading System can check for new messages at any time when connected to a Service by invoking the getServiceAnnouncements operation. It is recommended that Reading Systems check for announcements immediately after completing the initialization of a new Session.

Note:

A Reading System should check for new announcements at least once per Session.

The Service can set the importance level for each announcement from a level of 1 (most important) to 3 (least important) and specify the type of announcement as one of ERROR, SYSTEM, WARNING or INFORMATION to assist Reading Systems in ordering the announcements for rendering to the User.

Note:

A Service may remove unread announcements from the Service at any time and for any reason. To avoid potential retrieval conflicts, a Reading System must treat the identifier values of individual announcement attributes as valid for no longer than the duration of the active Session.

If a Service does not support service announcements, the Service must return an operationNotSupported fault if a Reading System attempts to invoke the getServiceAnnouncements operation to obtain new announcements.

4.5.2. Read Announcements

After rendering each announcement to a User, a Reading System should immediately invoke the markAnnouncementsAsRead operation to inform the Service not to send the announcement again the next time the User connects to the Service.

To prevent conflicts arising from announcements that have been removed from the Service, a Reading System must only invoke the markAnnouncementsAsRead operation using the identifier values obtained from the last invocation of getServiceAnnouncements operation made during the active Session.

4.6. Bookmarks / Last Reading Position

The DAISY Online Delivery protocol uses the Portable Bookmarks and Highlights grammar from [Z39-86.2005] to record Users' bookmarks. This grammar can also be used by Reading Systems to record the last reading position for each Content item.

Note:

[Z39-86.2005-BOOKMARKS] constitutes the normative reference regarding the use and semantics of this type.

To indicate that a Service supports the retrieval of bookmarks, the Service must include an operation element with the value GET_BOOKMARKS when responding to a Reading System's invocation of the getServiceAttributes operation.

To indicate that a Service supports the setting of bookmarks, the Service must include an operation element with the value SET_BOOKMARKS when responding to a Reading System's invocation of the getServiceAttributes operation.

If a Service supports both the setting and retrieval of bookmarks, a Reading System may use the lastMark attribute of the bookmarkSet type to store the User's last reading position.

Note:

If a Service supports both operations, a Reading System should check for a last reading position before resuming playback.

Contrary to [Z39-86.2005-BOOKMARKS], this version of the DAISY Online Delivery protocol does not allow audio recordings to be submitted to a Service as part of the setBookmarks operation.

A Service may support the retrieval of bookmarks or both the setting and retrieval of bookmarks. A Reading System should support both operations for maximum interoperability.

Note on Z39-86.2005-BOOKMARKS

[Z39-86.2005-BOOKMARKS] was developed exclusively to support bookmarks and highlights for [Z39-86.2005] and its predecessor [Z39-86.2002]. Reading Systems employing this protocol, however, may attempt to make use of this grammar in more than just Z39.86 contexts.

This specification neither endorses or condemns this behavior. Until [Z39-86.2005-BOOKMARKS] is revised to be more agnostic in terms of the content types it supports, the specification only notes that Services should be designed with the awareness that a Reading System may post a bookmarkSet with a content type other than ANSI/NISO Z39.86.

For example, a Reading System may re-purpose this grammar to store bookmarks for [DAISY 2.02] content by using the ncxRef value to point to a fragment in a DAISY 2.02 NCC document instead of a Z39.86 NCX document.

4.7. Dynamic Menus

This section is informative

The DAISY Online Delivery protocol offers the ability for Services to send dynamic menus to compliant Reading Systems. Users can take advantage of the functionality exposed by these menus to manually perform a wide variety of operations, such as browsing the Service's catalog, taking surveys, purchasing items from an online store and downloading service announcements.

The following sections describe the basic principles that must be adhered to when a Service implements a dynamic menuing system. Refer to [Dynamic Menus Primer] for informative usage examples.

4.7.1. Support

This section is normative

To indicate that a Service supports dynamic menus, the Service must include an operation element with the value DYNAMIC_MENUS when responding to a Reading System's invocation of the getServiceAttributes operation.

Services that support the Browse Content Selection Method must also support dynamic menus to allow a User to select Content. Services that only support the Out-of-band Content Selection Method are not required to support dynamic menus.

Note:

Services that only support the Out-of-band Content Selection Method may still support dynamic menus for other user interaction purposes.

Reading Systems should support dynamic menus for maximum interoperability.

4.7.3. Navigation

This section is normative

A question is the basic unit of navigation in the dynamic menu system, as each set of menu options can be conceptually viewed as querying a User about the next step to take.

The getQuestions operation takes one parameter: the userResponses type. The userResponses type must contain the response to the last question(s) or have a questionID set to one of the three reserved keywords defined in Section 4.7.6, “Reserved IDs”.

A User navigates a menu system by repeatedly selecting answers to the questions returned from invocations of the getQuestions operation until one of the end points outlined in Section 4.7.5, “End Points”, is reached.

A Service may send more than one question in response to each call to getQuestions. A Reading System should collect the responses to each question before invoking the getQuestions operation again and each response must be contained in a separate userResponse property.

Note:

Except at menu end points, a Reading System must invoke the getQuestions operation to get the next set of questions to display.

4.7.4. Question Types

This section is normative

The DAISY Online Delivery protocol defines two types of questions for navigating a menu system:

Multiple Choice Questions

Multiple choice questions include a predefined set of options that a User must pick from to answer the question. A multiple choice question is represented by the multipleChoiceQuestion element of the questions type.

Input Questions

Input questions require the user to respond to the question with text and/or audio input. An input question is represented by the inputQuestion element of the questions type.

Note:

A Service must specify if an input question requires a numeric, alphanumeric or audio-based response. The required response modality for an input question is specified in the inputTypes element of the inputQuestion type.

A Reading System that supports dynamic menus must declare which input types it supports in the readingSystemAttributes . A Service should not send any question which requires an input type not supported by the Reading System.

4.7.5. End Points

This section is normative

To indicate to a Reading System that the User has reached the end point of a menu sequence, a Service must return a questions type containing one of:

A Service must send a label when it is providing an informative or concluding statement for the User, such as confirmation of a purchase or thanks for completing a survey.

A Service must send a contentListRef when the menu sequence has resulted in the generation of a list of Content items that User can then access.

Note:

A response containing an input or multiple choice question never represents an end point.

4.7.6. Reserved IDs

This section is normative

There are three reserved values for use as the questionID attribute of a userResponses element:

default

Indicates that the Reading System is requesting the root question. Refer to Section 4.7.2, “Root Question”.

search

Indicates that the Reading System is requesting the search menu.

back

Indicates that the Reading System has requested to step back one menu sequence.

Reading Systems that support dynamic menus must support the default value. Reading Systems that support dynamic menus may support the search and back values.

5. API Reference

This section is normative

5.1. Required Operations

This section documents the protocol operations that all Services must support.

5.1.1. The logOn Operation

Logs a Reading System on to a Service.

Request parameters
username

Type: xs:string [XML Schema 2]

The ID used to access the Service.

password

Type: xs:string [XML Schema 2]

The password associated with the supplied ID.

Response

Type: xs:boolean [XML Schema 2]

Specifies whether the logon was successful.

Faults

internalServerError, invalidOperation

5.1.3. The setReadingSystemAttributes Operation

Sends Reading System properties to a Service.

A Reading System must invoke this operation as part of the Session Initialization Sequence. The operation may be invoked additional times during a Session to record dynamic changes in a Reading System's properties.

Request parameters
readingSystemAttributes

Type: readingSystemAttributes

Contains the Reading System attributes.

Response

Type: xs:boolean [XML Schema 2]

Specifies whether the Service successfully received the ReadingSystemAttributes.

Faults

internalServerError, invalidOperation, invalidParameter, noActiveSession

5.1.5. The getContentMetadata Operation

Retrieves contentMetadata for the specified Content.

This operation must be called as part of the Content Retrieval Sequence.

Request parameters
contentID

Type: xs:string [XML Schema 2]

Contains the Content Identifier of the Content item for which the metadata is being requested (defined by the id attribute of the relevant contentItem in the contentList type).

Response

Type: contentMetadata

Contains the metadata for the specified Content item.

Faults

internalServerError, invalidParameter, noActiveSession

5.1.6. The getContentResources Operation

Retrieves resources for the specified Content.

This operation is only valid if a call to issueContent with a result of true has been made for the given Content during the current or a previous Session.

Request parameters
contentID

Type: xs:string [XML Schema 2]

Contains the Content Identifier of the Content item for which resources are being requested (as defined in the [Dublin Core] identifier field of the contentMetadata type).

Response

Type: resources

Contains the resources for the specified Content item.

Faults

internalServerError, invalidOperation, invalidParameter, noActiveSession

5.1.7. The getServiceAttributes Operation

Retrieves Service properties, including information on which optional Operations the Service supports.

A Reading System must invoke this operation as part of the Session Initialization Sequence and may invoke the operation to retrieve information on possible changes to Service properties at any other time during a Session.

Request parameters

The getServiceAttributes operation has no parameters.

Response

Type: serviceAttributes

Contains the attributes of the Service.

Faults

internalServerError, invalidOperation, noActiveSession

5.1.8. The getContentList Operation

Retrieves a list of Content items.

The list returned by the Service can be a pre-composed type, in which case it is retrieved by passing one of the three reserved values defined in the id parameter below. (Refer to 4, Protocol Fundamentals, for information on the contexts in which these reserved values can be used.)

The list can also be a dynamic type (e.g., the result of a dynamic menu search operation sequence). In this case, the id value used to refer to the list is provided in the return type of a previous operation. (Refer to the questions type for more information.)

Request parameters
id

Type: xs:ID [XML Schema 2]

The identifier for the content list to retrieve.

The following three values are reserved and must not be used as identifiers except as defined below.

issued

Refers to a list of Content that the Service currently has recorded as issued to the User (refer to issueContent ).

The list must include all Borrowable Content items that have been issued regardless of whether they have been downloaded (in part or in full) or not. The list may include Purchasable Content items that have been issued. The list excludes Content that has Section 4.1.1.3, “Content Expiry”.

Services that provide Borrowable Content must recognize this identifier.

new

Refers to a list of Content items available to issue to a User.

The list excludes all Content that is issued.

Services that support the Out-of-band Content Selection Method must recognize this identifier.

expired

Refers to a list of Content that has been issued to the User but has expired.

firstItem

Type: xs:integer [XML Schema 2]

When retrieving a subset of a contentList, contains the first item in the subset to retrieve. The first item in the list has the index 0.

lastItem

Type: xs:integer [XML Schema 2]

When retrieving a subset of a contentList, contains the last item in the subset to retrieve. The value -1 indicates a request to retrieve all items from startIndex to the end of the list.

Response

Type: contentList

Contains the requested Content list (or a segment of the list).

The value of the id attribute on the returned contentList must match the value of the id parameter passed to the getContentList operation.

Faults

internalServerError, invalidOperation, invalidParameter, noActiveSession

5.2. Optional Operations

This section documents additional protocol operations that a Service may support. Refer to Content Selection Methods for conditions when certain of these optional operations become required.

5.2.2. The markAnnouncementsAsRead Operation

Marks the specified announcement(s) as read.

This operation is only valid if a previous call to getServiceAnnouncements has been made during the Session.

Request parameters
read

Type: read

Contains the announcements to mark as read (expressed as references to the ID values specified in the announcements type).

Response

Type: xs:boolean [XML Schema 2]

Specifies whether the announcements were successfully marked as read by the Service.

Faults

internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession

5.2.6. The getQuestions Operation

Retrieves a question from the series of questions that comprise the dynamic menu system.

Request parameters
userResponses

Type: userResponses

Contains the response to a question, or, as defined in userResponse , one of the three reserved IDs: default, search or back.

Response

Type: questions

Contains one or more multiple choice or input questions. May also contain a Label or contentListRef child elements.

Faults

internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession

5.2.7. The getKeyExchangeObject Operation

Requests a [PDTB2] Key Exchange Object from a Service.

Request parameters
keyRing

Type: keyRing

The identifiers of the keys on the Reading System's keyring.

requestedKeyName

Type: xs:string [XML Schema 2]

The identifier of the requested key.

Response

Type: KeyExchange

A [PDTB2] Key Exchange Object, containing the requested key encrypted using one of the keys identified in keyRing.

Faults

internalServerError, invalidOperation, invalidParameter, operationNotSupported, noActiveSession

5.3. Faults

6. Type Reference

This section is normative

The following sections describe the elements defined in the [ XML Schema 1 ] schema do-types-10.xsd, which is a normative part of the abstract WSDL document (refer to Appendix A, WSDL Abstract Definition).

Note:

The following simplified set of SGML syntax rules has been used throughout this section to define the content models:

  • parentheses are used to group sets of elements and/or other groups;

  • within groups, a comma ',' indicates required sequences and a pipe '|' indicates optional sequences; and

  • a question mark '?' after a group or element indicates the item must occur zero or one times, a plus sign '+' indicates one or more, an asterisk '*' zero or more and no modifier means the element or group must occur exactly once.

In the case of any discrepancies between the descriptions in this specification and the definitions in do-types-10.xsd, the latter shall be taken as authoritative.

6.3. The contentList Type

A list of Content items.

Used By

getContentList (response)

Content Model

( label ?, contentItem * )

Attributes

totalItems

The total number of contentItems in the list. This instance of contentList may contain a subset of the total number of items, i.e. it may be segmented. If and only if the contentList is not segmented, the value of this attribute is equal to the number of contentItem children of this element.

Use: required

Data type: xs:integer

firstItem

The 0-based index of the first content item provided in this instance of contentList. This attribute must be provided when a contentList is segmented. If this attribute is present, the lastItem attribute must also be present.

Use: optional

Data type: xs:integer

lastItem

The 0-based index of last content item provided in this instance of contentList. This attribute must be provided when a contentList is segmented. If this attribute is present, the firstItem attribute must also be present.

Use: optional

Data type: xs:integer

id

The identifier of the contentList.

If this contentList is being returned on a call of getContentList where one of the reserved values new, issued or expired is passed as the value of that operations id parameter, then the value of this attribute must equal the passed value, i.e. be new, issued or expired respectively.

If the value of this attribute is not one of the three reserved values above, then this is an arbitrary contentList, typically exposed as an endpoint in a dynamic menu search operation sequence.

Services should persist contentList identitifiers for the duration of a Session. Services must not expose multiple arbitrary contentLists with the same identifier during the same session.

Use: required

Data type: xs:ID

6.3.1. contentList Examples



6.4. The contentMetadata Type

The metadata of a Content item.

Used By

getContentMetadata (response)

Content Model

( sample ?, metadata )

Attributes

category

The publication category for the Content.

Reading Systems may use the value provided here to categorize or sort Content items.

Any value is allowed. The values BOOK, MAGAZINE, NEWSPAPER and OTHER are recommended for those Content items which match any of these terms.

Use: optional

 

returnBy

Specifies the time when the Service requires this Content to be returned, i.e. the end of an issuance period.

This attribute may be present when the requiresReturn attribute is true, and must not be present when the requiresReturn attribute is false.

This attribute may change value between calls, even after the Content is issued.

Use: optional

Data type: xs:dateTime

6.4.1. contentMetadata Examples

Example 6.4. Typical book contentMetadata type

This example shows a contentMetadata type for a borrowed book that is [PDTB2] protected (see Section 4.4.4, “Rights management”).

<contentMetadata xmlns="http://www.daisy.org/ns/daisy-online/"
  requiresReturn="true" category="BOOK">
  <sample id="hp_cos-sample"/>
  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
    <dc:title>Harry Potter and the Chamber of Secrets</dc:title>
    <dc:identifier>com-example-hp_cos</dc:identifier>
    <dc:format>Daisy 2.02</dc:format>
    <dc:language>en-GB</dc:language>
    <narrator>Mary Svensson</narrator>
    <size>8119213</size>
    <meta name="pdtb2:specVersion" content="2005-1" />
  </metadata>
</contentMetadata>

6.9. The readingSystemAttributes Type

Specifies Reading System properties.

The properties specified are valid until the end of the Session.

Used By

setReadingSystemAttributes (parameter)

Content Model

( manufacturer , model , serialNumber ?, version , config )

This element is extensible.

6.9.1. readingSystemAttributes Examples



6.11. The serviceAttributes Type

Properties of the Service.

The properties specified must be constant for the duration of the Session.

Used By

getServiceAttributes (response)

Content Model

( serviceProvider ?, service ?, supportedContentSelectionMethods , supportsServerSideBack , supportsSearch , supportedUplinkAudioCodecs , supportsAudioLabels , supportedOptionalOperations )

6.11.1. serviceAttributes Examples

Example 6.8. serviceAttributes type for a typical minimal library service

This example shows a serviceAttributes type for a Service that only supports the out-of-band Content Selection Methods.

<serviceAttributes xmlns="http://www.daisy.org/ns/daisy-online/">
  <serviceProvider id="uk.com.example" />
  <service id="uk.com.example.libraryServiceBasic" />
  <supportedContentSelectionMethods>
    <method>OUT_OF_BAND</method>
  </supportedContentSelectionMethods>
  <supportsServerSideBack>false</supportsServerSideBack>
  <supportsSearch>false</supportsSearch>
  <supportedUplinkAudioCodecs>
    <codec>audio/mpeg</codec>
  </supportedUplinkAudioCodecs>
  <supportsAudioLabels>true</supportsAudioLabels>
  <supportedOptionalOperations>
    <operation>SET_BOOKMARKS</operation>
    <operation>GET_BOOKMARKS</operation>
    <operation>SERVICE_ANNOUNCEMENTS</operation>
  </supportedOptionalOperations>
</serviceAttributes>

Example 6.9. serviceAttributes type for a typical maximally extended service

This example shows a serviceAttributes type for a Service that supports both available Content Selection Methods and provides some or all of its Content encrypted using [PDTB2].

<serviceAttributes xmlns="http://www.daisy.org/ns/daisy-online/">
  <serviceProvider id="gy-zenith" />
  <service id="gy-zenith-libraryServiceDeluxe" />
  <supportedContentSelectionMethods>
    <method>BROWSE</method>
    <method>OUT_OF_BAND</method>
  </supportedContentSelectionMethods>
  <supportsServerSideBack>true</supportsServerSideBack>
  <supportsSearch>true</supportsSearch>
  <supportedUplinkAudioCodecs>
    <codec>audio/mpeg</codec>
  </supportedUplinkAudioCodecs>
  <supportsAudioLabels>true</supportsAudioLabels>
  <supportedOptionalOperations>
    <operation>DYNAMIC_MENUS</operation>
    <operation>SET_BOOKMARKS</operation>
    <operation>GET_BOOKMARKS</operation>
    <operation>SERVICE_ANNOUNCEMENTS</operation>
    <operation>PDTB2_KEY_PROVISION</operation>
  </supportedOptionalOperations>
</serviceAttributes>

6.12. The userResponses Type

A set of User responses to questions provided by the Service.

For informative examples of the userResponses type, refer to the [Dynamic Menus Primer].

Used By

getQuestions (parameter)

Content Model

( userResponse + )

6.13. Element Reference

A single Content item.

Properties

Content model: ( label )

Parent(s): contentList

Attributes

lastModifiedDate

The last modified time of this contentItem. This is the last modified time of the most recently modified resource in the Content's resources list.

Use: optional

Data type: xs:dateTime

The identifier of a contentList .

A contentListRef as a child of the questions element indicates an endpoint of the sequence of questions that comprise a dynamic menu.

Properties

Data type: xs:ID

Parent(s): questions

Bibliographic and other metadata of the Content.

Elements in the Dublin Core namespace are normatively defined by [Dublin Core]. The value of the Dublin Core identifier element must match the Content Identifier of the Content item.

Additional, non-Dublin Core metadata may be provided using the generic meta element.

The prefix pdtb2 in the name attribute of a meta element is reserved to refer to properties of [PDTB2].

The value pdtb2:specVersion in the name attribute of a meta element means that the Content item is protected using [PDTB2]

Properties

Content model: ( dc:title , dc:identifier , dc:publisher ?, dc:format , dc:date ?, dc:source ?, dc:type *, dc:subject *, dc:rights *, dc:relation *, dc:language *, dc:description *, dc:creator *, dc:coverage *, dc:contributor *, narrator ?, size , meta * )

This element is extensible.

Parent(s): contentMetadata

One of the optional operations or groups of optional operations defined below.

Properties

Allowed values:

Parent(s): supportedOptionalOperations

Specifies whether the Reading System requires audio labels for messages provided by the Service (i.e. whether the audio child element of label is required).

Refer to the supportsAudioLabels element in serviceAttributes for the Service's declaration of support for audio in labels.

This specification does not specify behaviors in the case where the Reading System requires audio labels, and a Service does not support audio labels.

Properties

Data type: xs:boolean

Parent(s): config

Properties

Content model: empty element

Parent(s): resources

Attributes

uri

The URI of the resource.

Use: required

Data type: xs:anyURI

mimeType

The [MIME] type of the resource.

Use: required

Data type: xs:string

size

The size of the resource in bytes.

Use: required

Data type: xs:int

localURI

The local relative path of the resource.

The value of this attribute must be a URI relative to the Content's root directory. The value must contain the literal filename of the resource.

This attribute is used to aid Reading Systems in retrieving resources in the case where the uri attribute does not specify a direct literal URI (such as when the URI resolves to a script, or any other indirection).

Use: required

Data type: xs:anyURI

lastModifiedDate

The last modified time of the resource.

Use: optional

Data type: xs:dateTime

A list of Content Selection Methods supported by this Service. A Service must support at least one of the two methods.

Properties

Content model: ( method {1, 2} )

Parent(s): serviceAttributes

Specifies which content types the Reading System supports.

This applies to both Content and Service messages ( label s).

A Service may use this information to choose which content types to offer to the Reading System as labels and Content.

Content types for which support is implied by the Content formats in supportedContentFormats need not be included here.

Properties

Content model: ( mimeType * )

Parent(s): config

Specifies whether this Service supports the inclusion of audio in label s.

If the value of this element is true and the requiresAudioLabels element of readingSystemAttributes is true in the Reading System's most recent call to setReadingSystemAttributes , then the Service must include the audio element in each label it provides.

Properties

Data type: xs:boolean

Parent(s): serviceAttributes

Specifies whether the Reading System supports multiple selections for a multipleChoiceQuestion .

If this element is set to false, the Service must not present a multipleChoiceQuestion with its allowMultipleSelections attribute set to true to the Reading System.

Properties

Data type: xs:boolean

Parent(s): config

A response to a question. Either the value attribute (for inputQuestion or multipleChoiceQuestion responses) or the data element (for audio-based responses) must be present.

Note:

If a userResponses element is a response to a multipleChoiceQuestion where multiple selections are allowed, then multiple userResponse elements must be used to represent each selection (where each userResponse refers to the same question via the questionID attribute).

Properties

Content model: ( data ? )

Parent(s): userResponses

Attributes

value

In the case of an inputQuestion, this attribute contains the textual response. In the case of a multipleChoiceQuestion, it contains the ID of the choice.

Use: optional

Data type: xs:string

Normative References

[DAISY 2.02] DAISY 2.02 Specification . M. Gylling, et al.. February 2001.

[INFOSET] XML Information Set (Second Edition) . J. Cowan, R. Tobin. February 2004.

[XML Schema 1] XML Schema Part 1: Structures Second Edition . Henry S. Thompson, et al.. 28 October 2004.

[XML Schema 2] XML Schema Part 2: Datatypes Second Edition . P. V. Biron, et al.. 28 October 2004.

[RFC 2109] HTTP State Management Mechanism . D. Kristol. February 1997.

This appendix is normative

The [WSDL 1.1] entities defined in the accompanying do-wsdl-10.wsdl document constitute the abstract Web Service contract that all compliant Services must adhere to.

Service implementors must publish a concrete WSDL document at some URI. The [INFOSET] of the concrete WSDL document must be identical to the do-wsdl-10.wsdl document with the exception of the WSDL service element, which defines the locally supported ports.

The abstract do-wsdl-10.wsdl document may be used as a template for creating the concrete document.